GraphQL 模式内省映射器

它要解决的具体问题

GraphQL 团队最常见的维护负担不是写查询，而是让文档和类型定义跟上真实服务。一次 breaking change 落地后，前端拿到的 __type 信息、生成的 TS 类型、CI 里的 schema 校验规则往往各改各的：SDL 手工维护会过期，graphql-codegen 的类型是事后产物，改了字段没人记得同步 @deprecated 标记。结果就是编译期通过、运行时报错，或者更糟——静默丢字段。

这个技能把「摸清 schema 实际长什么样」这件事收敛成一条可重复的路径，而不是每次翻文档。

核心能力与工作方式

它通过标准的 __schema 内省查询去拉取服务端自描述的类型系统，然后把三件事一起做完：

• 类型关系映射：把 OBJECT、INTERFACE、UNION、INPUT_OBJECT 之间的字段归属和 implements 关系梳理成结构化视图，而不是让你对着 __type(name: "...") 的原始 JSON 自己脑补。
• 弃用字段识别：单独捞出带 isDeprecated 的字段和 deprecationReason，方便判断哪些还在被消费、哪些可以直接进清理清单。
• 循环引用探测：标出相互引用的对象类型，这在生成代码或做文档导航时会直接影响输出结构，早一步看到能少一次重构。

在此基础上它产出三类可落地的结果：

1. SDL 导出——把内省结果还原成 Schema Definition Language，可以直接提交进仓库当作 schema 快照。
2. TypeScript 类型——交由 graphql-codegen 依据这份映射生成强类型文件，让 useQuery 的返回值在编译期就有约束。
3. 版本差异报告——比较两个版本之间的 schema，输出新增、删除、变更的字段，而不是靠 git diff 去肉眼找。

关键步骤是：先确认服务端允许内省（生产环境常被关掉），再发起 __schema 查询，随后做关系整理与循环引用分析，最后按用途分流成 SDL、类型或 diff 报告。

适用边界与注意点

• 内省能力受服务端配置限制。如果网关或 Apollo 层关闭了 introspection，这条路直接走不通，需要改用导出的 SDL 文件作为输入。
• 它描述的是服务端当时的状态。如果 schema 在你读取之后被改动，diff 报告的基准就失真了，做版本对比时要保证两侧快照来自同一次部署。
• 底层依赖的 GraphQL.js 是通用库，同时支持 Node 服务里的 CommonJS（require()）和 ESModule（import）写法。引入工程时注意项目自身的模块规范，避免混用。
• deprecated 字段只是元数据提示，不改变运行时行为；真正的下线还需要配合查询日志确认没人在用。
• 对自研的非标准类型系统（自定义标量、缺乏描述的 schema）映射结果会偏弱，生成的文档信息量取决于原 schema 的注释完整度。