API 设计原则
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/rmyndharis-antigravity-skills-api-design-principles。
技能介绍
要解决什么问题
团队里常见的痛点不是「不会写接口代码」,而是对外契约长期漂移:资源命名不一致、错误体各端各样、分页与鉴权没有统一约定,重构时又怕破坏存量客户端。REST 与 GraphQL 选型也常停留在口头上,缺少从消费者、用例到约束的落地路径。
本技能面向「把 API 当产品」的设计与评审阶段,帮助你在不写具体框架代码的前提下,把接口契约想清楚、写一致,并为文档与演进留好结构。
技能如何工作
技能把设计过程收成四步,并可对照 resources/implementation-playbook.md 中的模式、清单与模板深化:
- 界定消费者、用例与约束——谁调用、在什么场景下要什么数据、有哪些性能或合规边界。
- 选定 API 风格并建模——在 REST 资源模型与 GraphQL 类型/schema 之间做有意识的选择,而不是默认抄路由表。
- 约定横切能力——统一说明
errors、版本策略、分页与 鉴权/授权策略,避免各端自行解释。 - 用示例校验并做一致性评审——用代表性请求/响应走查命名、状态码、错误码与文档是否自洽。
适用情境包括:从零设计 REST 或 GraphQL、改造难用的存量 API、给团队定设计规范、实现前审 OpenAPI/GraphQL SDL,以及在 REST 与 GraphQL 之间迁移时的契约梳理;也可针对移动端或第三方集成优化资源粒度与批量能力。
适用边界
- 若你只需某一框架(如 Spring/FastAPI)的落地代码片段,而不是契约与标准,本技能不是主路径。
- 纯基础设施(网关、部署、观测)且不涉及对外 API 契约时,不必启用。
- 若无法调整或版本化对外公开接口,设计层面的重构建议价值有限,应优先弄清变更窗口。
使用场景
- 新服务上线前,要在 REST 与 GraphQL 之间选型并画出资源或类型模型
- 存量接口被投诉难用,需重构 URL、错误体与分页而不先动框架代码
- 合并前要用统一清单评审 OpenAPI/GraphQL SDL,查漏命名与错误码不一致
- 计划从 REST 迁到 GraphQL,需梳理契约与版本策略再给客户端排期
适合人员
- 负责对外 B2B API 的后端负责人,希望团队有统一的错误与版本约定
- 写 OpenAPI 规范的工程师,需要在评审会上用示例揪出不一致端点
- 从单体拆微服务的架构师,要定义各服务边界资源而非先堆路由
- 维护第三方开发者文档的技术写作者,要把用例与约束写进可读文档