API设计原则：用一套可复用的方法论，把 API 从“能跑”做到“好用、可扩展、可维护”
- 它是什么：API设计原则（api-design-principles）是一个面向架构师的 AI 技能，专注 REST 与 GraphQL 两种主流 API 范式的设计原则、审查标准与建模方法。
- 它解决什么：API 设计靠个人经验、风格不统一、上线后频繁破坏性变更、文档难懂、团队无标准可依的问题。
- 核心流程：先定义消费者、用例与约束，再选风格并建模资源或类型，然后规定错误处理、版本控制、分页与认证策略，最后用示例验证并审查一致性。
- 边界清晰：技能明确列出了“不该用”的场景（只需要框架实现指导、无 API 合同的基础设施工作、无法变更或版本化的公共接口），避免误用。
- 配套资源：内置
resources/implementation-playbook.md，提供详细模式、检查清单与模板，可直接作为团队评审依据。
该技能叫什么？如何下载安装 AI 技能提升开发效率？
基础信息一览
| 项目 | 内容 |
|---|---|
| 中文名 | API设计原则 |
| 英文名 | api-design-principles |
| 技能ID | 12930 |
| 版本 | 1.0.0 |
| 许可证 | MIT |
| 所属领域 | 架构 |
| 角色定位 | 架构师 |
| 作用范围 | 系统设计 |
| 输出格式 | 架构 |
| 触发词 | API设计、REST、GraphQL、API标准、API规范、API审查 |
| 关联技能 | API模式、API安全最佳实践 |
它到底解决什么问题
接口设计往往是“写完就跑”的环节：命名随意、错误码各写各的、分页参数三种风格、版本策略事后才补。等到第三方接入或移动端上线，才发现接口语义不清、扩展困难、改动一次就要拉上全部调用方。这个技能的价值，就是把架构师脑子里的隐性经验固化成一条可执行的设计链路——从使用者出发，而不是从数据库表结构出发。
“一键安装”AI 技能提升开发效率的思路
AI 技能的安装方式因平台而异，官方并未在本技能内提供具体安装命令，因此这里给出通用思路，具体命令、入口地址与是否收费请以官方说明为准：
- 确认安装前提：你的 AI 编程助手或客户端需要支持“技能（Skill）”能力，并已登录可用账号；若团队使用私有部署，需确认技能市场或技能仓库已开放。
- 找到安装入口：通常有两条路径——在技能市场/技能商店中搜索中文名“API设计原则”或技能ID“12930”；或导入技能包/技能清单文件（本技能为 MIT 许可，清单中标注为
api-design-principles）。 - 执行安装：按平台提示确认安装，通常为一次点击或一条安装指令；若平台支持按需启用，建议在“架构设计”相关会话中启用，而不是全局常开，避免无关任务被干扰。
- 验证是否生效：新建一个会话，直接输入触发词，例如“帮我按 REST 原则设计一个订单查询 API，并给出错误处理与分页策略”。若返回的是结构化的架构建议（包含消费者分析、资源建模、错误与版本策略），说明技能已生效；若只是泛泛而谈，则可能未加载成功，可检查技能是否启用或重新安装。
- 检查配套资源：确认技能目录下的
resources/implementation-playbook.md可正常读取，后续评审与落地时可以直接引用其中的模式、检查清单与模板。
该技能的主要功能和特点
- 双范式覆盖：同时覆盖 REST 与 GraphQL，而不是只讲一种。写 REST 时关注资源建模、状态码与分页；写 GraphQL 时关注类型建模与查询边界，避免“只会一种就会偏科”。
- 四步设计流水线：内置固定的指令流程——定义消费者/用例/约束 → 选择 API 风格并建模资源或类型 → 指定错误处理、版本控制、分页与认证策略 → 用示例验证并审查一致性。每一步都有明确产出，不会聊着聊着跑偏。
- 面向“人”而非“表”：第一步就要求先弄清谁在调用、用来做什么、有什么限制，这直接把“按数据库表生成接口”的坏习惯挡在门外。
- 天然带审查视角：不仅能“设计新 API”，还支持“在实施前审查 API 规范”“重构现有 API 以提高可用性”，可在代码落地前拦住问题。
- 支持范式迁移：明确覆盖“在 API 范式之间迁移（如从 REST 到 GraphQL 等）”，对正在做接口升级的团队尤其有用。
- 明确的否定清单：写清了不适用场景，避免用户拿它去解决“某个框架怎么写”的实现级问题，也避免在接口不可变更、不可版本化的环境里做无用功。
- 输出为“架构”形态：产出物是结构化的设计方案，而非零散代码片段，便于直接进入评审、归档、写进技术方案文档。
- 可通过触发词精准唤起：API设计、REST、GraphQL、API标准、API规范、API审查六个触发词，覆盖从初始设计到事后审查的全过程。
- MIT 许可，落地阻力小：宽松许可意味着可在商业项目与内部规范建设中自由使用。
- 与关联技能可组合：可衔接“API模式”和“API安全最佳实践”，形成“设计原则 → 模式选型 → 安全加固”的完整链路。
和普通工具比强在哪：普通代码生成工具只回答“这段代码怎么写”，它回答的是“这个接口该不该这么设计、以后能不能改、别人用起来会不会骂”。
如何使用该技能？
以下是基于技能内置指令整理的标准使用流程，可直接照做。
第 1 步：判断是否该用它 先对照技能的使用条件：设计新 REST/GraphQL API、重构现有 API、建立团队 API 标准、实施前审查规范、范式迁移、编写开发者友好文档、针对移动端或第三方集成做定向优化——命中任意一条即可用。若你只是想知道某个框架的注解怎么写，或接口根本无法版本化，则不建议使用。
第 2 步：用触发词唤起并给出上下文 最简单的方式是直接说出触发词并描述任务。示例输入：
“用 API设计 技能帮我规划一个面向第三方开发者的订单服务 REST API。消费者：外部商户系统（技术能力参差）、我们自己的移动端；用例：创建订单、查询订单列表、取消订单；约束：日调用量百万级、必须支持灰度发布与向后兼容。”
第 3 步：让它先定消费者、用例与约束 不要跳过这一步。技能会先帮你把“谁在用、怎么用、有什么限制”梳理清楚，这一段的产出建议直接抄进技术方案的第一章，后续所有设计决策都要能回溯到它。
第 4 步：选风格并建模 技能会在 REST 与 GraphQL 之间给出取舍，然后产出资源或类型的建模结果。示例输出形态：订单作为资源，包含集合资源与单个资源的路径语义、列表查询的参数设计、以及哪些字段适合内联、哪些适合独立资源。
第 5 步：拿到横切策略 继续索取四类策略的具体规定：错误处理（错误结构、错误分类、可读性）、版本控制（版本标识方式与废弃节奏）、分页（参数与返回结构）、认证（鉴权方式与作用范围）。这一步最容易暴露团队历史遗留的不一致问题。
第 6 步：用示例验证并做一致性审查 让技能用具体请求/响应示例走一遍主流程和异常流程，然后逐条核对：命名是否统一、错误是否可区分、分页是否一致、字段是否冗余。发现偏差就要求它给出修正建议。
第 7 步：沉淀为团队标准
把最终结论整理成规范文档，并引用 resources/implementation-playbook.md 中的详细模式、检查清单与模板，形成可复用的评审清单，供后续每个接口复用。
第 8 步（可选）：做范式迁移评估 若正准备从 REST 迁移到 GraphQL，可让技能对照现有资源模型给出类型化方案与迁移风险点，再决定是否推进。
同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| API设计原则（本技能） | 架构师视角的 API 设计方法论与审查助手 | REST/GraphQL 双范式设计、四步指令流程、错误/版本/分页/认证策略、规范审查、配套 playbook | 需支持技能能力的 AI 客户端，从技能市场或技能包安装；会话语义即可调用，无需编码 | 新 API 设计、存量重构、团队标准建设、接口评审、范式迁移 | 优势：流程固定、覆盖横切关注点、明确否定清单、输出即架构方案；不足：不提供具体框架实现代码，深度依赖你提供的上下文质量 |
| 通用大模型直接对话 | 通用问答 | 可以聊 API 设计，但没有固定流程与检查清单 | 极低，打开即用 | 零散问题、快速确认概念 | 优势：随时可用；不足：容易泛泛而谈、缺少错误/版本/分页等系统性覆盖，结论不稳定，难以沉淀为团队标准 |
| 官方 API 风格指南文档（如各类 RESTful 设计指南） | 静态规范参考 | 提供命名、状态码、分页等条文式规则 | 低，阅读即可 | 查条款、写规范文档 | 优势：权威、稳定、可引用；不足：是“字典”不是“顾问”，不会根据你的消费者与约束做取舍，也无法主动审查你的设计 |
| 接口描述规范工具链（OpenAPI/Schema 类工具） | 规范描述与契约工具 | 描述接口、生成文档与客户端、做契约校验 | 中，需要编写规范文件与接入工具链 | 契约管理、文档生成、自动化测试 | 优势：可自动化、可校验；不足：只保证“描述一致”，不判断“设计是否合理”，坏设计一样能被完美描述出来 |
一句话选型建议：需要“有人陪你做设计决策”选本技能；需要“查条文”看风格指南；需要“管契约”上规范工具链；三者并不冲突，可以串联使用。
该技能的典型应用场景与实际体验情况
场景一：后端架构师从零设计一套对外开放 API 痛点：对外开放意味着调用方技术能力参差、无法强制升级，一次破坏性变更可能引发大量投诉。使用方式：先输入消费者画像（外部商户 + 自有移动端）、核心用例与调用量约束，让技能先定风格，再逐步产出资源模型、错误结构、版本与分页策略。实际体验：上手几乎没有门槛，只要把上下文说清楚，产出的结构化程度明显高于直接问通用模型；注意点是一定要如实描述约束（尤其是“必须向后兼容”这类硬条件），否则方案会偏理想化。
场景二：平台团队要统一 API 设计标准 痛点：多个业务线各写各的，错误码三套、分页参数五种，新人上手要读十几份文档。使用方式：让技能基于现有若干接口样例做一致性审查，归纳冲突点，再输出一份可执行的规范草案与评审清单，引用 playbook 中的检查清单固化下来。实际体验：它擅长把“感觉不统一”变成“具体哪几条不统一”，评审会上更容易达成共识；注意事项是规范落地需要配合流程（比如接口评审卡点），单靠文档不会自动生效。
场景三：接口上线前的规范审查 痛点：设计评审常常变成“拍脑袋大会”，缺少统一标尺。使用方式：把接口规范草稿贴进去，要求按 API审查 视角逐条检查错误处理、版本控制、分页与认证是否齐备，并给出改进项。实际体验：产出偏“清单式”，非常适合作为评审会的检查表；注意它不替代安全专项审查，涉及鉴权细节还应串联“API安全最佳实践”技能。
场景四：从 REST 迁移到 GraphQL，或为移动端优化接口 痛点：移动端抱怨字段冗余、请求次数多；迁移又怕踩坑。使用方式：让技能对比现有 REST 资源模型与 GraphQL 类型模型的差异，指出哪些聚合关系适合类型化、哪些查询会带来复杂度风险。实际体验：对“要不要迁、怎么迁”的判断有帮助，但它给出的是架构层面的取舍，具体 Schema 落地与性能验证仍需团队自己完成。
该技能能为用户带来的价值
- 把经验变成流程：四步指令让 API 设计从“看人”变成“看流程”，团队里经验较少的工程师也能走完一套完整的设计动作，减少对资深架构师的单点依赖。
- 把返工挡在编码之前：错误处理、版本控制、分页、认证这四类最容易事后返工的横切关注点被前置规定，避免接口上线后再补丁式修改。
- 显著降低沟通成本：一套统一的术语与检查清单，让后端、前端、第三方对接方在同一个语境里讨论问题，评审会从“争论风格”转向“核对清单”。
- 提升对外开放接口的长期可用性：面向消费者建模、明确版本与兼容策略，直接减少第三方集成过程中的反复沟通与破坏性升级。
- 知识资产可沉淀：输出格式为架构方案，配合
resources/implementation-playbook.md的模式、检查清单与模板，可逐步积累成团队自己的 API 设计手册。 - 零成本的引入门槛：MIT 许可、以对话方式使用、无需改造现有技术栈，适合作为团队规范建设的起点工具。
常见问题 FAQ
Q1：这个技能怎么安装？有具体命令吗？ A：安装方式取决于你所使用的 AI 平台。通用做法是在技能市场/技能商店中搜索中文名“API设计原则”或技能ID“12930”，或导入对应的技能包；具体命令、入口与权限要求请以官方说明为准。安装后可输入触发词“API设计”“REST”“GraphQL”等验证是否生效。
Q2：它收费吗？ A：技能本身标注为 MIT 许可证，属于宽松开源许可。但运行它所需的 AI 客户端/平台是否收费、按什么标准计费，取决于平台方，请以官方说明为准。
Q3：它适合谁用？ A：主要面向架构师、后端技术负责人、负责对外开放平台的工程师，以及需要建立团队 API 规范的 Tech Lead。前端或客户端工程师也可用它来评估接口是否好用。如果你只是想查某个框架的注解写法，它并不合适。
Q4：它和 OpenAPI/Swagger 这类工具冲突吗？ A：不冲突，二者层次不同。本技能解决“接口该怎么设计才合理”，规范工具解决“如何把接口描述清楚并自动化”。推荐顺序是：先用本技能完成设计与审查，再用规范工具产出契约与文档。
Q5：用了它是不是就不用写文档了？ A：不是。技能支持“创建开发者友好的 API 文档”这一目标，产出的是架构层面的设计方案与策略约定，可显著提升文档质量与一致性，但最终文档仍需团队整理发布，并配合示例与错误码说明。