Apollo Client中useMutation和useLazyQuery的类型安全问题解析

在Apollo Client的最新版本开发中，团队发现并修复了一个关于useMutation和useLazyQuery钩子函数的类型安全问题。这个问题主要涉及在使用TypeScript和TypedDocumentNode时，变量传递的类型检查不够完善。

问题背景

在Apollo Client的文档中，useMutation和useLazyQuery都支持两种方式传递变量：

1. 作为钩子本身的选项参数
2. 作为执行函数（mutate或execute）的参数

理论上，这两种方式应该支持变量合并，即执行函数可以覆盖钩子中定义的默认变量值。然而，在使用TypeScript和TypedDocumentNode时，类型系统会强制要求在所有地方都提供完整的变量对象，即使某些变量已经在钩子选项中定义。

具体表现

以一个添加人员的mutation为例：

mutation AddPerson($name: String, $title: String) {
  addPerson(name: $name, title: $title) {
    node {
      id
      name
      title
    }
  }
}

在TypeScript中尝试以下用法时会出现类型错误：

const [addEngineer] = useMutation(TYPED_DOCUMENT_NODE, {
  variables: {
    title: 'Engineer' // 缺少name字段的类型错误
  }
});

useEffect(() => addEngineer({ 
  variables: { name: 'Alvin' } // 缺少title字段的类型错误
}), []);

尽管这种用法在运行时能正常工作（通过any类型强制绕过类型检查），但类型系统无法正确理解变量合并的语义。

解决方案

Apollo Client团队在4.0版本中对这个问题进行了重大改进：

1. 对于useMutation：

   • 现在会正确检查必需变量是否在钩子选项或执行函数中提供
   • 在钩子选项中定义的变量在执行函数中变为可选
   • 确保所有必需变量最终都会被提供

2. 对于useLazyQuery：

   • 移除了钩子选项中的variables参数
   • 现在要求所有变量必须通过execute函数传递
   • 改进了类型检查，确保必需变量不会被意外遗漏

技术决策背后的考量

团队在解决这个问题时做出了几个重要决策：

1. 简化变量传递方式：特别是对于useLazyQuery，移除了钩子选项中的variables参数，避免了变量生效时机的歧义。

2. 类型安全优先：确保开发者在编译时就能发现变量缺失的问题，而不是等到运行时。

3. 一致性：使API行为更加一致和可预测，减少开发者的认知负担。

升级建议

对于现有项目，建议：

1. 逐步迁移到新的变量传递方式
2. 检查所有useLazyQuery调用，确保变量都通过execute函数传递
3. 利用改进的类型检查发现潜在的问题

这些改进将在Apollo Client 4.0中正式发布，目前可以通过alpha版本提前体验。团队鼓励开发者提供反馈，帮助进一步完善这些变更。