技能介绍

要解决的具体问题

GraphQL API 设计常陷入几类典型陷阱：直接把数据库 schema 映射为 GraphQL schema，导致接口耦合过紧；解析嵌套字段时不做批量加载，引发 N+1 查询问题；在大数据集上使用 offset 分页而非游标分页，分页性能随数据量增长迅速恶化；Resolver 直接抛出原始错误而非返回结构化错误负载；将所有类型定义堆在单一 schema 文件中，难以维护；以及缺乏查询深度和复杂度限制，使恶意查询能够拖垮服务。

核心能力与关键步骤

该技能围绕 Schema 设计、Resolver 优化 与 Subscriptions 三个层面提供工程化指导。在 Schema 设计上，列表字段应使用 Relay-style connections 进行游标分页，Mutation 返回的 payload 类型需同时包含 result 和 errors 字段，以便客户端统一处理成功与失败。

在 Resolver 层面，通过 DataLoader 解决 N+1 查询问题：每个请求在 context 中创建独立的 DataLoader 实例，避免跨用户缓存污染。所有批量实体查找都应经过 DataLoader 进行合并。

对于 Subscriptions，需使用过滤后的主题（filtered topics）进行推送，避免将消息广播给所有客户端。

此外，技能强调 模块化：将 schema 拆分为领域专属模块而非单体文件，Mutation 参数使用输入类型（Input types），并配置查询深度与复杂度限制以防范恶意查询。

适用边界与注意点

该技能适用于需要构建可扩展、高健壮性 GraphQL API 的后端工程师，尤其是团队协作或对外开放的 API 场景。需要注意，DataLoader 实例必须按请求创建，不可复用全局实例；直接暴露数据库 schema 会丧失 GraphQL 的灵活性优势；查询深度和复杂度限制是生产环境的必要配置，不能省略。