GraphQL Code Generator 客户端预设与 erasableSyntaxOnly 的兼容性问题解析

问题背景

GraphQL Code Generator 是一个强大的工具链，能够根据 GraphQL Schema 自动生成类型安全的代码。其中 client-preset 预设包是专门为客户端开发设计的配置集合，它生成的代码包含了类型化的文档字符串类 TypedDocumentString。

核心问题

在 TypeScript 的严格模式下，特别是当启用 erasableSyntaxOnly 编译选项时，client-preset 生成的代码会出现兼容性问题。具体表现为：

export class TypedDocumentString<TResult, TVariables>
  extends String
  implements DocumentTypeDecoration<TResult, TVariables>
{
  // 问题代码段
  constructor(private value: string, public __meta__?: Record<string, any> | undefined) {
    super(value);
  }
}

这段代码会在 erasableSyntaxOnly 模式下产生两个编译错误：

1. 构造器参数中的 private 修饰符不被允许
2. 构造器参数中的 public 修饰符不被允许

技术原理

erasableSyntaxOnly 是 TypeScript 的一个严格编译选项，它要求所有类型注解和修饰符在编译为 JavaScript 后都能被完全擦除而不影响运行时行为。参数属性（即在构造函数参数前使用 public/private/protected 修饰符）是一种语法糖，它会在编译时同时做两件事：

1. 声明参数
2. 自动创建同名的类属性

这种双重行为违反了 erasableSyntaxOnly 的设计原则，因为修饰符不仅影响类型系统，还会改变运行时行为。

解决方案

正确的做法是将参数属性和类属性声明分离：

export class TypedDocumentString<TResult, TVariables>
  extends String
  implements DocumentTypeDecoration<TResult, TVariables>
{
  private value: string;
  public __meta__?: Record<string, any> | undefined;

  constructor(value: string, __meta__?: Record<string, any> | undefined) {
    super(value);
    this.value = value;
    this.__meta__ = __meta__;
  }
}

这种写法完全符合 erasableSyntaxOnly 的要求，因为：

1. 所有类型信息都可以被安全擦除
2. 属性初始化是显式的
3. 运行时行为清晰明确

影响范围

该问题主要影响以下场景：

1. 使用 client-preset 预设的项目
2. 启用了 TypeScript 严格模式或明确设置了 erasableSyntaxOnly 选项
3. 需要生成类型化文档节点的应用

最佳实践

对于需要同时满足类型安全和严格编译要求的项目，建议：

1. 升级到最新版本的 @graphql-codegen/client-preset (4.7.0+) 和 @graphql-codegen/typed-document-node (5.1.0+)
2. 在 codegen 配置中明确指定这些版本
3. 定期检查 GraphQL Code Generator 的更新，获取最新的兼容性改进

总结

GraphQL Code Generator 的客户端预设与 TypeScript 严格模式的兼容性问题，本质上反映了类型系统语法糖与编译严格性要求之间的权衡。通过将参数属性重构为显式的属性声明和初始化，既保持了类型安全，又满足了 erasableSyntaxOnly 的编译要求，为开发者提供了更灵活的配置选择。