SuperAPI AI 工具集

graphql-architect

通用与其它

查看项目

更新于 10-16 01:48

技能介绍

用途:该技能面向 GraphQL API 的设计与评审,适用于新建 schema 或模块、resolver 与 mutation 设计、分页过滤与搜索、N+1 查询削减与批处理、以及 GraphQL 的授权、校验和错误塑形。

工作流程:先阅读现有 GraphQL 形态,检查 schema 文件、resolver 结构与 context 设置,在新增模式前至少找到 3 个已有 resolver 或 schema 模式,并沿用主流的命名、可空性和错误处理约定。随后先设计契约再实现,从客户端用例而非数据库表出发,先定义查询、mutation、输入类型和输出类型,保持类型稳定明确,避免歧义字段或职责过载的 mutation。实现时保持 resolver 边界清晰:resolver 保持轻量,业务逻辑下沉到服务层;在 API 边界校验输入,在入口附近执行授权,避免把数据库细节直接泄漏到 schema 类型。性能方面尽早控制:相关字段扇出时使用批处理或 data loader;大型列表优先游标分页而非临时偏移分页;避免在没有明确客户端意图时触发隐藏的高开销工作;列表返回嵌套实体时评估 N+1 风险。最后验证客户端易用性:字段名应描述领域概念而非存储细节,可空性应反映真实保证,mutation 结果应返回足以立即更新 UI 的数据,错误应一致且可操作。

核心规则:查询读取,mutation 改变状态;输入类型与输出类型应彼此独立;mutation 名称以动词开头且具体;优先使用显式枚举而非魔法字符串;演进 schema 时先弃用再移除。

常见陷阱包括:类似 updateThing 的笼统 mutation;默认返回庞大的嵌套对象;resolver 同一层同时直连数据库和网络;用 null 隐藏授权失败而无明确契约;新增字段时不考虑缓存键或客户端改动成本。

输出:使用该技能时产出建议的 schema 或 resolver 变更、性能与授权影响说明,以及迁移或客户端影响风险。

限制:资料未提供具体安装命令、价格、平台支持或代码示例,均暂未提供。