GraphQL API 工程师

设计 GraphQL API 时，最常见的问题不是「会不会写 type」，而是关系型数据模型映射到 GraphQL Schema 后，嵌套层次与查询性能之间的矛盾。你可能已经尝过这些苦头：前端一个看似无辜的查询，在 Resolver 层触发了 N+1；Schema 写得太宽，客户端可以无限递归拉取数据，把网关打满；或者 Schema 写完后，才发现缺少输入校验，脏数据直接落库。

解决什么问题

• Schema 设计缺乏章法：Type、Query、Mutation、Subscription 混在一起，字段命名随意，后续维护成本陡增。
• N+1 查询难以根治：posts 里每条记录都单独查库，请求数随关联对象数量线性增长。
• 安全策略缺失：没有深度限制、复杂度分析或认证配置，恶意查询可以轻易拖垮服务。
• 学习曲线陡峭：从「会写 type」到「能独立排查性能问题」之间，缺少可动手的中间环节。

技能如何工作

这个技能把 Agent 设定为GraphQL 工程师角色，按以下流程带你走完一个 API 的生命周期：

1. 分析数据模型与查询需求：先理清业务实体之间的关系，再决定暴露哪些字段。
2. 设计 GraphQL Schema：定义 Type、Query、Mutation、Subscription，遵循最佳实践，避免过度嵌套。
3. 实现 Resolver 与数据加载器：用 DataLoader 对关联查询做批处理，从根本上缓解 N+1 问题。
4. 优化查询性能：检查字段使用频率，合并相似查询，必要时引入缓存。
5. 配置安全策略：加上深度限制、复杂度分析、认证与输入验证，防止恶意查询。

技能不会一次性塞给你所有内容，而是通过「试试写一段…」这样的动手挑战，每推进两三个步骤就停下来确认你的思路，让知识当场落地。它还内置了一套经验值进度系统，从初学者到专家级，逐步解锁更复杂的场景；当你输入「结束」，它会以一句「GraphQL 开发指南完成。」收尾。

适用边界与注意点

这个技能适合从零设计 GraphQL API或重构已有的不合理 Schema的场景。但它不是万能的：

• 它生成的 Schema 和 Resolver 代码需要你结合实际业务审核，尤其是涉及权限控制的字段。
• DataLoader 是批处理优化手段，不是缓存方案，数据一致性问题仍需自行处理。
• 安全策略的配置要根据你的网关、认证体系和业务风险容忍度来调整，不能照搬默认值。