Apollo Client 中泛型类型不匹配问题的深入解析

问题背景

在使用 Apollo Client 进行 GraphQL 查询时，开发者经常会遇到类型系统相关的挑战。本文探讨一个典型的类型不匹配问题，该问题出现在尝试抽象化查询操作时，涉及泛型类型的协变和逆变特性。

核心问题分析

开发者试图创建一个通用的 getById 函数，该函数接受 GraphQL 查询文档和 ID 参数，返回一个类型化的查询结果。函数定义如下：

const getById = <TData extends Record<string, string>>(gql: DocumentNode, id: string) => {
  return useQuery<TData>(
    gql,
    computed(() => ({ id }))
  )
}

当尝试将返回的查询结果赋值给不同类型的变量时，TypeScript 报出了看似矛盾的类型错误：

const query: ByIdQuery<Record<string, string>> = getById<{ foo: string }>(MyQuery, "1")

错误信息表明 Record<string, string> 不能赋值给 { foo: string }，这与直觉相反。

类型系统原理

这个问题的根源在于 TypeScript 的类型系统中协变和逆变的概念：

1. 协变（Covariance）：如果 A 是 B 的子类型，那么 F<A> 也是 F<B> 的子类型
2. 逆变（Contravariance）：如果 A 是 B 的子类型，那么 F<B> 是 F<A> 的子类型
3. 双变（Bivariance）：同时支持协变和逆变

在 Apollo Client 的 useQuery 返回类型中，TData 既出现在协变位置（如返回的结果类型），也出现在逆变位置（如某些回调参数类型）。这种混合使用导致了类型检查的复杂性。

解决方案

1. 使用 TypedDocumentNode

Apollo Client 提供了 TypedDocumentNode 类型，可以更好地处理类型推断：

const getById = <TData>(gql: TypedDocumentNode<TData>, id: string) => {
  return useQuery(
    gql,
    computed(() => ({ id }))
  )
}

这种方式让 TypeScript 能够自动推断类型，避免了手动指定泛型参数可能带来的不一致性。

2. 避免不必要的类型注解

在大多数情况下，直接使用 useQuery 而不添加额外的抽象层是更简单且类型安全的选择：

const result = useQuery(gql, computed(() => ({ id })))

最佳实践建议

1. 优先使用自动类型推断：让 TypeScript 从 GraphQL 查询文档中自动推断类型，而不是手动指定
2. 谨慎使用类型约束：过度使用 extends 约束可能会引入类型系统复杂性
3. 保持查询与类型同步：确保 GraphQL 查询文档与 TypeScript 类型定义保持同步
4. 避免违反 Hook 规则：在创建抽象层时，确保不违反 React Hook 的使用规则

总结

在 Apollo Client 中使用泛型时，理解 TypeScript 的类型系统特性至关重要。通过合理使用 TypedDocumentNode 和类型推断，可以避免大多数类型不匹配的问题，同时保持代码的简洁性和类型安全性。对于复杂的 CRUD 操作抽象，建议从简单实现开始，逐步增加类型复杂性，并在每一步验证类型系统的行为是否符合预期。