如何利用TypeScript类型级编程实现GraphQL查询变量的类型校验？

GraphQL把类型检查的希望寄托在schema上，但前端调用时传参这件事，很多时候依然处于“裸奔”状态：查询字符串里声明了一个$id: ID!，调用方传参时却传了个number，甚至干脆漏传，这类错误在编译期毫无感知，只有等到请求发出去、服务端返回错误才暴露。TypeScript的类型系统经过多年的迭代，已经具备了模板字面量类型、递归条件类型等强大能力，足以在纯类型层面解析GraphQL查询字符串，并对变量对象做静态校验。这篇文章就来拆解这套思路的完整实现路径。

一、为什么GraphQL变量校验值得在类型层做

先看一个常见的调用场景。假设有这样一段查询：

query GetUser($id: ID!, $withPosts: Boolean = false) {
  user(id: $id) {
    name
    posts(include: $withPosts) { title }
  }
}

调用时我们通常会把变量包成一个对象传进去。问题在于，这个对象和查询字符串之间的关联，TypeScript默认是完全看不见的。$id是非空的ID!，意味着必须传且不能为null；$withPosts带了默认值，调用方可以不传。如果这些约束靠人肉记忆或者手写接口来维护，一旦查询改了、接口忘了改，类型就对不上了，而且编译器不会给任何提示。

传统做法是使用代码生成工具（比如GraphQL Code Generator），从schema生成TS类型。这个方案成熟可靠，但它依赖构建流程，对于动态拼接查询、或者只是想轻量校验一个变量的场景，引入整套生成链路显得笨重。而类型级编程的思路是：直接把查询字符串当作类型层面的输入来解析，让TypeScript自己推导出变量应有的形状。这样做的好处是零运行时开销，约束和查询字符串永远绑定在一起，改了查询立刻就能在调用处看到编译错误。

二、GraphQL变量语法到TypeScript类型的映射

动手写工具类型之前，先要把GraphQL的变量声明语法翻译成TS能理解的东西。GraphQL内置标量类型不多：Int、Float、String、Boolean、ID，加上!表示非空，方括号表示列表。映射关系很直接：

type GraphQLScalar = {
  Int: number;
  Float: number;
  String: string;
  Boolean: boolean;
  ID: string;
};

// 处理非空标记：解析掉末尾的 "!"，并标记为必填
type StripNonNull<T extends string> =
  T extends `${infer Base}!` ? Base : T;

// 处理列表类型：[X!]! 之类
type StripList<T extends string> =
  T extends `[${infer Inner}]` ? StripList<Inner>[] : MapScalar<StripNonNull<T>>;

type MapScalar<T extends string> =
  T extends keyof GraphQLScalar ? GraphQLScalar[T] : T extends "ID" ? string : never;

这里的关键技巧是模板字面量类型配合infer做字符串解构。T extends \`${infer Base}!\`这样的写法能在类型层面“正则匹配”字符串尾部，把感叹号剥掉。注意!只能出现在类型末尾，所以从尾部剥是安全的。而列表需要递归处理，因为[[Int]]这种嵌套列表在语法上是合法的，StripList递归调用自身直到不再匹配方括号为止。

还有一个容易忽略的细节：带默认值的变量在GraphQL语义中是“调用方可选”的，即便它声明为非空。所以解析$withPosts: Boolean = false时，除了提取类型Boolean，还要识别出=后面的默认值部分，把这个变量标记为可选属性。这一点在后面的完整实现中会体现。

三、从查询字符串中提取变量类型的完整实现

现在进入核心部分：解析整个查询字符串。思路分三步：先提取query XXX(...)括号内的变量声明区，再按逗号切分出每个变量声明，最后逐个解析成键值对并组装成对象类型。

// 第一步：提取括号内的变量声明串
type ExtractVariablesDecl<Query extends string> =
  Query extends `${string}(${infer Decl})${string}` ? Decl : "";

// 第二步：按逗号切分（简化版，假设类型内不含逗号）
type SplitByComma<S extends string> =
  S extends `${infer Head},${infer Rest}`
    ? [Head, ...SplitByComma<Rest>]
    : [S];

// 第三步：解析单个声明 "$name: Type = default" 或 "$name: Type!"
type ParseVariable<Decl extends string> =
  Decl extends `$${infer Name}:${infer Rest}`
    ? Rest extends `${infer Type} = ${string}`
      ? { [K in Name]?: MapScalar<StripList<Type>> }
      : { [K in Name]: MapScalar<StripList<Type extends `${infer T} = ${string}` ? T : Rest>> }
    : {};

// 组装所有变量
type QueryVariables<Query extends string> =
  SplitByComma<ExtractVariablesDecl<Query>> extends infer Decls
    ? UnionToIntersection<{ [K in keyof Decls]: ParseVariable<Decls[K]> }[number]>
    : never;

其中UnionToIntersection是一个常见的类型工具，把联合类型转成交叉类型，这里不展开，网上有现成实现。使用效果如下：

const query = `
  query GetUser($id: ID!, $withPosts: Boolean = false, $tags: [String!]) {
    user(id: $id) { name }
  }
` as const;

type Vars = QueryVariables<typeof query>;
// 推导结果等价于：
// {
//   id: string;          // ID! 非空必填
//   withPosts?: boolean; // 有默认值，可选
//   tags?: (string)[];   // 列表本身可空
// }

// 编译期直接报错：id 类型不符，tags 元素类型不符
const bad: Vars = { id: 123, tags: [true] };

这套实现演示了类型级编程的完整链路：模板字面量做字符串切割、infer做模式匹配、递归类型处理嵌套结构、映射类型组装结果。需要坦白的是，上面的代码是简化版，真实的GraphQL查询可能包含变量默认值里的逗号、注释、多操作定义等复杂情况，逐个处理会让工具类型膨胀到数百行。但原理就是这样一层层剥洋葱，遇到新语法就加一条匹配分支。

四、自研工具类型与成熟方案的取舍

类型级方案的优势很鲜明：不需要构建工具链，类型和查询字符串天然同步，改查询立即触发调用处检查。但劣势也不能回避。首先是性能问题，TypeScript对递归深度的实例化有上限，查询字符串很长时编译会明显变慢，甚至触发“类型实例化过深”的错误。其次是维护成本，GraphQL语法的边角情况很多，schema中的自定义标量、input类型嵌套等，纯靠字符串解析很难覆盖全面。

而GraphQL Code Generator这类方案走的是另一条路：从schema生成完整的TS类型和请求函数，变量类型、返回类型都能精确校验，还能配合graphql-request或Apollo的hooks使用。它的代价是需要配置构建流程，且生成的类型和手写查询之间隔了一层生成物。实践中的建议是：项目已经接入了schema、查询数量多且复杂，优先用代码生成；只是少量查询、或想在纯前端项目里快速拿到变量约束，类型级方案足够轻量好用。两者也完全可以共存，核心查询走生成器，临时查询用工具类型兜底。

最后提醒一点，类型校验只解决了“传参正确”这半个问题，返回值的类型同样重要。类型级编程同样可以解析查询的selection set推导返回结构，只是复杂度更高。理解了本文的字符串解析套路之后，你就掌握了继续深入的那把钥匙——剩下的，不过是更多层的递归和更多条的匹配分支而已。

TypeScript类型级编程GraphQL变量校验修改时间：2026-09-09 08:10:43