Appearance
利用 AI 掌握 REST 与 GraphQL 的 API 设计原则
解决 API 设计混乱、缺乏统一标准的问题：通过 AI 引导，在设计之初就遵循业界成熟的 REST 和 GraphQL 原则，确保接口易用、可扩展且具备长期的可维护性。
为什么需要这个技能
很多开发者在编写 API 时倾向于直接实现功能，而忽略了接口的“可用性”。缺乏标准的设计会导致接口命名混乱、版本管理缺失、分页逻辑不统一，最终增加调用者的沟通成本，并在后期重构时带来巨大的技术债。
通过该技能，AI 可以充当资深架构师，帮你审视资源模型、定义统一的错误处理机制，并在 REST 与 GraphQL 两种范式之间做出最合适的选择，确保你的 API 能够经受住业务增长的考验。
适用场景
- 从零设计新接口：在编写代码前，先由 AI 协助定义资源模型和端点规范。
- 重构旧有 API：将不直观的旧接口优化为符合行业标准的现代 API。
- 制定团队规范：为团队建立统一的 API 设计标准和评审清单。
- 范式迁移：需要将部分 REST 接口迁移至 GraphQL 以优化数据获取效率。
- 优化文档：生成对开发者友好的 API 规格说明书。
核心工作流
- 需求分析：定义 API 的消费者是谁、核心用例是什么以及有哪些技术约束。
- 风格选择与建模：根据场景选择 REST 或 GraphQL，定义核心资源（Resource）或类型（Type）及其关系。
- 细节定义：明确错误码设计、版本控制策略、分页机制以及鉴权方案。
- 验证与评审：通过具体请求示例验证逻辑一致性，并对照
resources/implementation-playbook.md中的检查清单进行最终评审。
下载和安装
下载 api-design-principles 中文版 Skill ZIP
解压后将目录放入你的 AI 工具 skills 文件夹，重启工具后即可使用。具体路径参考内附的 USAGE.zh.md。
你可能还需要
暂无推荐