GraphQL Code Generator client-preset 中 useFragment 返回类型的优化解析

背景介绍

GraphQL Code Generator 是一个强大的工具，它能够根据 GraphQL 模式自动生成类型安全的代码。其中的 client-preset 预设特别为前端开发提供了便利，能够生成与 GraphQL 操作相关的 TypeScript 类型和 React Hook。

在 client-preset 的使用过程中，开发者发现了一个关于 useFragment Hook 返回类型的问题：当传入数组类型的片段数据时，无论原始数据是否为只读数组，useFragment 总是返回 ReadonlyArray 类型。这在某些场景下会导致类型不兼容的问题，特别是当需要将处理后的数据传递给期望可变数组的组件或函数时。

问题分析

useFragment 是 client-preset 提供的一个重要 Hook，它的主要作用是将 GraphQL 片段引用转换为实际的数据对象。在 TypeScript 类型系统中，ReadonlyArray 和普通数组 (Array) 是不同的类型，前者表示不可变数组，后者表示可变数组。

问题的核心在于：

1. 当开发者传入 Array<FragmentType<T>> 时，useFragment 总是返回 ReadonlyArray<DocumentType<T>>
2. 这会导致类型系统强制下游代码处理只读数组
3. 在现有项目中引入 client-preset 时，可能需要大量修改现有代码以适应只读数组类型

技术实现

从技术角度来看，这个问题涉及到 TypeScript 的类型推断和泛型处理。理想的实现应该是：

• 当输入是普通数组 (Array) 时，返回普通数组
• 当输入是只读数组 (ReadonlyArray) 时，返回只读数组

这种设计遵循了 TypeScript 的类型系统原则，即保持输入和输出类型的一致性。它也更符合开发者的直觉，因为开发者通常期望 Hook 的行为不会意外地改变数据的可变性特征。

解决方案

GraphQL Code Generator 团队在 client-preset 的 4.3.0 版本中修复了这个问题。新的实现现在能够：

1. 正确识别输入数组的类型特征
2. 保持输入数组的可变性特征
3. 仅对片段引用进行转换，不改变数组的可变性

这意味着：

• 如果传入 Array<FragmentType<T>>，将得到 Array<DocumentType<T>>
• 如果传入 ReadonlyArray<FragmentType<T>>，将得到 ReadonlyArray<DocumentType<T>>

升级建议

对于正在使用 client-preset 的开发者：

1. 升级到 4.3.0 或更高版本以获得此修复
2. 检查项目中是否存在因之前的行为而添加的类型断言或类型转换
3. 考虑是否需要更新相关组件和函数的类型定义以更好地利用类型系统

最佳实践

在使用 useFragment 时，建议：

1. 明确声明组件属性的数组类型特征（是否只读）
2. 在需要可变数组的场景下，确保传入的是普通数组
3. 在需要不可变保证的场景下，使用 ReadonlyArray 类型
4. 考虑在项目中使用一致的数组类型策略，避免混用

总结

GraphQL Code Generator 的 client-preset 4.3.0 版本对 useFragment Hook 的类型处理进行了优化，使其更加符合开发者的预期和 TypeScript 的类型系统原则。这一改进减少了类型不兼容的问题，使得在现有项目中引入 client-preset 更加顺畅，同时也为开发者提供了更灵活的类型选择。