api-design-principles-zh：API 设计原则
API 设计原则
掌握 REST 与 GraphQL 的 API 设计原则，构建直观、可扩展、易维护且让开发者满意、经得起时间考验的 API。
使用本技能的时机
- 设计新的 REST 或 GraphQL API
- 重构现有 API 以提升可用性
- 为团队建立 API 设计标准
- 在实现前评审 API 规范
- 在 API 范式之间迁移（如 REST 到 GraphQL）
- 编写对开发者友好的 API 文档
- 针对特定场景优化 API（移动端、第三方集成）
不使用本技能的时机
- 你只需要某个具体框架的实现指引
- 你做纯基础设施工作、没有 API 契约
- 你无法更改或给公共接口做版本管理
指令
- 定义调用方、使用场景与约束条件。
- 选择 API 风格，并对资源或类型建模。
- 明确错误、版本管理、分页与鉴权策略。
- 用示例校验，并评审一致性。
详见 resources/implementation-playbook.md 获取详细模式、检查清单与模板。
资源
resources/implementation-playbook.md提供详细模式、检查清单与模板。