技能介绍

要解决的问题

GraphQL 的 introspection 能力很强，但一个成熟的 schema 往往包含成百上千个类型、字段、参数和指令。当你在排查一个字段为什么在前端查不到、确认某个类型继承关系、或者只是想快速回答"这个 API 里到底有哪些可查询的字段"时，靠肉眼翻阅源码或反复试错都很低效。GraphQL 模式探索器就是针对这个场景的轻量工具，它把对 schema 结构的浏览、检索和理解封装成一个可脚本化的能力。

它如何工作

这个技能基于 GraphQL.js 实现，也就是 GraphQL 官方参考实现的 JavaScript 版本。核心能力与关键步骤包括：

模式加载：通过 GraphQL.js 的 API 载入已定义的 schema，无论是来自代码中的 GraphQLSchema 实例，还是通过 introspection 获取到的模式描述。
结构遍历：对类型系统做程序化遍历，枚举 Query、Mutation、Subscription 等根类型下的字段，以及自定义类型、接口、联合类型和枚举之间的关系。
元信息提取：读取字段的参数列表、返回类型、描述信息和弃用标记，把这些原本散落在代码里的元数据组织成可读的摘要。
结果输出：以结构化形式呈现探索结果，方便你写进文档、做代码审查，或者直接在终端里验证接口行为。

适用边界与注意点

它依赖 GraphQL.js 本身，因此 schema 必须是符合 GraphQL 规范的类型系统；非标准或实验性的类型扩展需要额外处理。
GraphQL.js 是通用库，在 Node 服务端同时支持 require() 的 CommonJS 写法和 import 的 ESModule 写法，使用时需要和你的工程模块规范保持一致。
模式探索解决的是"理解结构"的问题，不涉及查询执行、缓存或网络层；复杂的 schema 治理仍需配合校验、lint 和文档生成工具使用。
上游文档以 GraphQL.js 的 README 为准，具体 API 行为随库版本演进可能变化，建议在项目内锁定版本。