首页　>　文章列表　>　独特的符号：如何使用符号确保类型安全

独特的符号：如何使用符号确保类型安全

173 2025-04-03

独特的符号：如何使用符号确保类型安全

如果您使用 React 一段时间，您可能已经接触过 React Query 的 queryOptions() 函数。其实现看似非常简单：

export function queryOptions(options: unknown) {
  return options;
}

然而，其真正的强大之处在于其函数重载签名。那么，它究竟有何特别之处呢？

还不了解函数重载？请参考这篇文章：函数重载：巧妙处理多个函数签名

类型安全的数据库查询

受到 React Query 方法的启发，我创建了一个辅助函数，它可能对非 React 开发者也同样有用：一种创建类型安全数据库查询（例如 SQL 查询）的简便方法。

export declare const queryParamsSymbol: unique symbol;
export declare const queryReturnSymbol: unique symbol;

export type Query<
  TParams extends Record<string, any> = {},
  TReturn extends Record<string, any> | undefined = undefined,
  TStatement extends string = string
> = {
  statement: TStatement;
  [queryParamsSymbol]: TParams;
  [queryReturnSymbol]: TReturn;
};

export function Query<
  TParams extends Record<string, any> = {},
  TReturn extends Record<string, any> | undefined = undefined,
  TStatement extends string = string
>(statement: TStatement): Query<TParams, TReturn> {
  return { statement } as Query<TParams, TReturn, TStatement>;
}

类似于 queryOptions()，这个函数本身也相当简洁：它接收一个 SQL 语句，将其包装在一个 Query 类型的对象中，然后返回该对象。

这是一个简单的调用示例：

const getUserById = Query<
  { id: number },
  { name: string; email: string }
>('SELECT name, email FROM users WHERE id = $id');

请注意我们如何将两种类型作为泛型参数传递。第一个是必需的查询参数——在本例中为 id。第二个代表查询的返回类型——name 和 email。

在底层，Query() 函数将这两种类型嵌入到返回的对象中，并分别存储在 queryParamsSymbol 和 queryReturnSymbol 中。这些符号被声明为唯一符号，这意味着它们只存在于类型空间中，不会出现在编译后的 JavaScript 代码中。

我使用这些符号来临时存储参数和返回类型，并在需要时检索它们。

type InferQueryParams<TQuery> = TQuery extends Query<infer Params>
  ? Params
  : never;

type UserQueryParams = InferQueryParams<typeof getUserById>;
//        ^? { id: number }

type InferQueryReturn<TQuery> = TQuery extends Query<any, infer Return>
  ? Return
  : never;

type UserQueryReturn = InferQueryReturn<typeof getUserById>;
//        ^? { name: string; email: string }

InferQueryParams 和 InferQueryReturn 只是辅助类型，用于验证参数和返回类型是否被正确推断。实际上您可能并不需要它们，但它们有助于验证我们的方法。

数据库客户端

现在我们知道如何在查询对象中嵌入参数和返回类型，那么我们如何实际执行这些查询呢？让我们来看一个可以执行类型安全查询的简单数据库客户端：

class DatabaseClient {
  async execute<
    TParams extends Record<string, any>,
    TReturn extends Record<string, any>
  >(
    query: Query<TParams, TReturn>,
    params: TParams
  ): Promise<Array<TReturn>> {
    // 执行查询并返回结果
    // ...
    return [];
  }
}

const db = new DatabaseClient();

// 返回类型和参数从查询对象中推断
const result = await db.execute(getUserById, { id: 1 });
//                                              ^? { id: number }
//      ^? Array<{ name: string; email: string }>
console.log(result);

在这个例子中，我们将类型安全的 getUserById 查询对象传递给 db.execute() 方法。由于 Query 类型同时包含参数和返回类型信息，TypeScript 会自动推断它们。我们可以通过将鼠标悬停在 result 上轻松验证这一点，TypeScript 还会提示 id 作为参数对象的属性。