Agent Skills
返回列表
💻

GraphQL API 设计

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中：

请根据 https://skillhub.cn/install/skillhub.md，安装 @user_3c6cb52e/graphql-api-design。

技能介绍

解决 GraphQL 后端开发的常见痛点

在构建 GraphQL API 时，开发者常面临几个典型问题：列表查询导致的 N+1 性能瓶颈、缺乏一致性的 Mutation 设计、以及基于 offset 的分页在数据变动时出现的数据漂移或重复。手动编写类型定义与解析器不仅耗时，还容易在复杂嵌套查询中引入安全漏洞。

核心工作流与工程实践

该技能通过结构化的工作流引导 AI 代理生成生产可用的 Schema 与解析器：

  • 领域建模与类型设计：将业务实体转化为具体的 GraphQL 对象、输入类型、枚举和接口。合理使用 ! 非空注解与自定义标量（如 DateTime）。
  • 查询与变更规范：遵循名词优先的查询（Query）和动词优先的变更（Mutation）原则，并强制要求变更操作返回包含结果与错误信息的 Payload 类型。
  • Relay 连接与分页：为列表字段实现基于游标的 Relay 规范，通过 edges、node 和 pageInfo 提供稳定的分页体验。
  • DataLoader 优化：在上下文工厂中按请求实例化 DataLoader，批量缓存关联数据以彻底解决 N+1 问题。
  • 安全与实时性：添加查询深度限制（10-15层）和复杂度分析，利用 Pub/Sub 后端实现精简的 Subscription 订阅。

适用边界与避坑指南

虽然该技能能生成健壮的代码，但在实际应用中仍需注意以下边界情况：

  • 空值传播：非空字段抛出异常会导致异常向上级可空父节点传播，需谨慎设计可空边界。
  • 循环引用：如 User -> Posts -> Author 是合法的，但必须依赖深度限制和 DataLoader 防止无限解析。
  • 文件上传：GraphQL 原生不支持文件上传，需借助 multipart 规范或独立的 REST 端点处理。
  • 订阅断线：WebSocket 连接可能中断，应设计客户端在重连后通过重新查询来恢复状态，而非仅依赖订阅流。

使用场景

  • 从需求文档或自然语言描述出发，设计包含查询、变更、订阅和输入类型的完整 GraphQL Schema，并输出解析器实现。
  • 列表接口返回大量数据时，需要实现基于游标的 Relay 分页连接，避免 offset 分页在数据增删时出现漂移。
  • 解析器频繁触发关联数据加载导致 N+1 查询时，需要引入 DataLoader 按请求批量缓存数据库查询。
  • 微服务架构下多个服务各自维护 GraphQL Schema，需要通过 Schema Stitching 或 Federation 合并为单一入口。

适合人员

  • 后端工程师：需要从需求描述快速产出结构一致、可运行的 GraphQL Schema 与解析器代码。
  • 微服务架构师：需要在多服务间拆分 GraphQL Schema 并通过联邦合并，同时保证查询深度和复杂度可控。
  • 平台开发者：需要为列表接口统一实现游标分页、空结果集和断线重连等边界处理。
  • 技术负责人：需要在团队中推行统一的 Mutation 返回格式、标量类型选择与版本演进规范。