技能介绍

你要解决的问题

当你接手一个 GraphQL 服务，或准备基于别人的 API 写客户端时，最先碰到的难题往往不是某个具体 query 怎么写，而是schema 本身是什么样：有多少类型、字段之间如何关联、哪些字段已经废弃、可空性是否合理。手工翻代码或反复试错既慢又容易遗漏，尤其当 schema 规模上来以后，循环引用、隐式 N+1、废弃字段混用这类问题会悄悄积累，直到线上出问题才被发现。

这个技能做什么

它通过 GraphQL 标准的 __schema 内省查询，直接拉取服务端暴露的类型系统信息，然后借助 graphql-js 提供的 buildClientSchema 与 printSchema 工具把内省结果还原成可读的结构，并做针对性分析：

N+1 模式检测：识别在循环或深层嵌套字段上可能触发重复请求的写法，提醒你把数据层级合并到一次请求里。
循环类型检查：找出互相引用的类型定义，确认是否会破坏序列化或客户端缓存。
废弃字段扫描：标出仍被使用但已标记 deprecated 的字段，推动调用方迁移到替代字段。
可空性标注审计：检查哪些字段缺了显式 nullability 标注，避免前端因默认可空而写出脆弱的判空逻辑。

整个流程不依赖服务端私有工具，只要目标 API 允许内省，就能在本地拿到完整 schema 并离线分析。

适用边界与注意点

需要内省权限：如果服务端关闭了 introspection（线上常见），你需要先用其他方式拿到 schema，例如导出 SDL 文件。
环境要求：底层依赖 graphql 库，在 Node 服务端可同时用于 CommonJS（require()）与 ESModule（import）两种写法，导入方式需与项目模块体系保持一致。
它是分析工具而非修复器：它能帮你定位 N+1 和循环引用的位置，但最终合并请求或拆分类型仍要人工修改 resolver 与 schema。
schema 漂移：分析结果对应的是当前线上状态，代码仓库里的 schema 与线上不同步时，需要以线上为准或补做差异对比。