API 设计原则

API 设计原则

掌握 REST 和 GraphQL API 设计原则，构建直观、可扩展且易于维护的 API，提升开发者体验并确保长期可用性。

适用场景

• 设计新的 REST 或 GraphQL API

• 重构现有 API 以提升可用性

• 为团队制定 API 设计标准

• 在实现前评审 API 规范

• 在不同 API 范式之间迁移（如从 REST 迁移到 GraphQL）

• 编写开发者友好的 API 文档

• 针对特定用例（如移动端、第三方集成）优化 API

不适用场景

• 仅需要特定框架的实现指导

• 仅进行不涉及 API 契约的基础设施工作

• 无法更改或对公共接口进行版本管理

操作指南

1. 定义消费者、用例和约束条件。
2. 选择 API 风格并对资源或类型进行建模。
3. 明确错误处理、版本控制、分页和认证策略。
4. 通过示例进行验证并检查一致性。

详细模式、检查清单和模板请参考 resources/implementation-playbook.md。

相关资源

• resources/implementation-playbook.md：包含详细模式、检查清单和模板。

局限性

• 仅在任务明确符合上述范围时使用此技能。

• 不要将输出结果视为环境特定验证、测试或专家评审的替代方案。

• 如果缺失必要的输入、权限、安全边界或成功标准，请停止并请求澄清。