GraphQL Code Generator 中 fragmentMasking 配置的正确使用方式

在使用 GraphQL Code Generator 生成 TypeScript 类型定义时，开发者经常会遇到 fragment 相关类型的处理问题。最近，一位开发者在升级 GraphQL Code Generator 和相关依赖后，发现生成的类型结构发生了显著变化，导致代码无法正常使用。

问题现象

升级前，生成的类型定义是简洁明了的联合类型：

export type SomeMutation = {
  __typename: 'Mutation',
  myProject: {
    __typename: 'MyProject',
    ...
  } | {
    __typename: 'MyProjectClosedError',
    message: string
  } | ...
};

升级后，类型定义中出现了复杂的 fragment 引用标记：

export type SomeMutation = {
  __typename: 'Mutation',
  myProject: (
    { __typename: 'MyProject' }
    & { ' $fragmentRefs'?: {
      'ProjectFirstLevelPropertiesFragmentFragment': ...,
      'ProjectSupplierFragmentFragment': ...,
      ...
    } }
  ) | ...
};

问题根源

这个问题源于 GraphQL Code Generator 4.0 版本引入的 fragment masking 功能。该功能默认启用，旨在通过类型系统强制实施 fragment 的使用规范，确保查询只访问 fragment 中定义的字段。

解决方案

要禁用 fragment masking 功能，需要在配置文件中正确设置 presetConfig.fragmentMasking 参数。关键在于配置的位置必须正确：

正确配置方式：

generates: {
  '输出目录': {
    preset: 'client',
    presetConfig: {  // 正确的配置位置
      fragmentMasking: false
    },
    // 其他配置...
  }
}

错误配置方式：

generates: {
  '输出目录': {
    preset: 'client',
    config: {  // 错误的配置位置
      presetConfig: {
        fragmentMasking: false
      }
    },
    // 其他配置...
  }
}

技术背景

fragment masking 是 GraphQL Code Generator 提供的一项高级功能，它通过类型系统实现了以下特性：

1. 类型安全：确保组件只能访问其 fragment 中声明的字段
2. 封装性：防止组件意外访问未声明的字段
3. 重构友好：修改 fragment 定义时会立即反映在类型检查中

然而，对于已有项目或不需要这种严格约束的场景，禁用此功能可能是更合适的选择。

最佳实践建议

1. 新项目：建议保留 fragment masking 功能，它能提供更好的类型安全和代码组织
2. 已有项目迁移：可以先禁用该功能，逐步调整代码结构后再启用
3. 配置验证：生成类型定义后，应检查输出是否符合预期
4. 版本兼容性：注意不同版本间配置方式的变化

通过正确理解和使用 fragment masking 配置，开发者可以更灵活地控制 GraphQL Code Generator 的类型生成行为，满足不同项目的需求。