SuperAPI AI 工具集

graphql-schema-design

设计与创作

查看项目

更新于 10-15 20:12

技能介绍

用途:作为资深 API 架构师,确保每次 GraphQL schema 变更都是有意的、对客户端友好且可演进的。它不写实现代码,只产出 SDL 提案和设计反馈,实现属于配套技能 graphql-backend。规则与框架无关,示例用 Book/Author 领域,模式适用于任意 GraphQL API。

两种模式:设计模式(默认),用户描述功能或用例,如“添加作者资料”“书评”;审查模式,用户要求 review、audit 或检查现有 schema 变更。

设计模式为交互式迭代:先理解需求,提出 3-5 个针对性问题(客户端要做什么、谁消费、相关现有类型、边界情况),未获明确答复不继续;再按 SDL 起草变更并加行内注释,按需加载命名、变更设计、可空性、连接与分页、错误处理、类型设计、schema 演进等参考清单;随后“拷问”每个设计决策,如可空性含义、类型共享耦合、变更粒度、布尔参数是否应为枚举、裸列表是否应改为连接、弃用与破坏性变更;再迭代更新并重新校验;最后给出完整 SDL、决策日志、演进说明和破坏性变更迁移路径,并停下等待用户明确批准,批准后交给 graphql-backend。

审查模式:用 git diff main 过滤 schema 文件(.graphql、schema.*)收集差异,若未发现则提示用户指明文件;加载全部参考清单;逐项审计新增、修改、删除的元素,将发现分为 Issues(必须修复)、Warnings(需确认的权衡)、Good(做得好的模式);按指定格式报告,含摘要与首要行动。

设计原则:为客户端而非数据库设计;让不可能状态不可能;默认可空、有把握才非空;每个变更用清晰动词;每个列表都要有分页决策;schema 变更是契约;持续演进而非版本化。

限制:不写实现代码;不替代实现技能;具体参考文件内容与完整规则需按需加载,资料未提供其细节。