GraphQL 架构师

要解决什么问题

GraphQL 服务上线后常见的性能陷阱很集中：resolver 里逐条查库造成的 N+1 请求、客户端一个深层嵌套查询把整张类型图拖垮、联邦（Federation）子图schema 与本地规范逐渐漂移。这类问题在代码评审阶段很难靠肉眼发现，等压测报告出来时往往已经欠下技术债。

这个技能的定位是 GraphQL 架构师助手：接收你的自然语言需求描述（可附带代码片段），输出结构化的 GraphqlSchema 工件，并给出针对性的优化建议。

核心能力与工作方式

技能按五步工作流推进，每一步都对应 GraphQL 设计中一个具体的决策点：

• 明确类型：梳理领域对象及其关系，先把实体和边的边界画清楚
• 定义 schema：字段、参数、分页策略的取舍，形成第一版类型定义
• 实现 resolver 与 DataLoader：用 DataLoader 做请求批处理与缓存，从根上消解 N+1 查询
• 查询优化：设置查询深度（depth）与复杂度（complexity）限制，防止恶意或失控查询打爆服务
• 产出工件：输出 {types: [string], queries: [string], notes: string} 结构的 GraphqlSchema，同时附带一段自然语言摘要和质量自检结论

输出分两部分：先是完整的结构化工件，再是摘要——包含质量自检结果和最应该优先修改的 2～3 个点。完整模板（工作流要点、质量自检清单、工件示例、常见陷阱）在技能的 references/template.md 中。

适用边界

• 适用于：GraphQL schema 设计、resolver/DataLoader 实现、Apollo Federation 与实时订阅场景、查询安全限制
• 不适用：纯 REST 接口设计，那是 api-designer 的职责；也不处理 GraphQL 网关的商业特性
• 输入可为自然语言需求，也可直接接收结构化的 GraphqlSchema 做二次优化；下游消费时交给 api-designer 对齐规范

如果你的系统还是 REST，先把 REST 接口设计好再考虑迁到 GraphQL，顺序反了容易把两种范式的缺点叠加在一起。