graphql-architect

GraphQL 架构设计

设计明确、稳定且高性能的 GraphQL API。

适用场景

• 新建 GraphQL schema 或模块
• 设计解析器和 mutation
• 分页、筛选和搜索
• 减少 N+1 查询并实现批处理
• 处理 GraphQL 的授权、验证和错误格式

工作流

1. 了解现有 GraphQL 结构

• 检查 schema 文件、解析器结构和上下文设置
• 添加新内容前，至少查找 3 个现有的解析器或 schema 模式
• 遵循主流的命名、可空性和错误处理惯例

2. 先设计契约，再开始实现

• 从客户端使用场景出发，而不是从数据库表出发
• 先定义 schema 结构：查询、mutation、输入类型和输出类型
• 保持类型稳定且明确；避免含义模糊的字段或用途过多的 mutation

3. 清晰划分解析器边界

• 保持解析器精简；将业务逻辑放入服务中
• 在 API 边界验证输入
• 在靠近入口的位置执行授权
• 避免在 schema 类型中直接暴露数据库细节

4. 尽早控制性能

• 对相关字段使用批处理／数据加载器，避免请求分散
• 对大型列表，优先使用游标分页，而非临时采用偏移分页
• 避免添加会触发隐式高开销操作、但客户端意图不明确的字段
• 每当列表返回嵌套实体时，都要评估 N+1 风险

5. 验证客户端易用性

• 字段名应描述领域概念，而非存储细节
• 可空性必须反映实际保证
• mutation 结果应返回足够的数据，以便立即更新 UI
• 错误应保持一致且可用于采取行动

核心规则

• 查询用于读取；mutation 用于更改状态
• 输入类型和输出类型应彼此区分
• mutation 名称应以动词开头且含义具体
• 优先使用明确的枚举，而非魔法字符串
• 演进 schema 时，先弃用再移除

常见陷阱

• 使用 updateThing 这类包罗万象的 mutation
• 默认返回庞大的嵌套对象
• 解析器逻辑在同一层直接与数据库和网络交互
• 未经明确约定，就用 null 隐藏授权失败
• 添加字段时未考虑缓存键或客户端变更成本

输出

使用此技能时，请提供：

• 建议的 schema／解析器变更
• 关于性能和授权影响的说明
• 任何迁移风险或对客户端的影响