api-design-principles

技能简介

该技能帮助开发者掌握 REST 与 GraphQL API 的设计原则，构建直观、可扩展、易维护的 API。无论是设计新 API、审查既有规范，还是制定团队设计标准，它都能提供最佳实践与示例参考。

使用场景

• 设计新的 REST 或 GraphQL API
• 重构既有 API 以提升易用性
• 为团队制定 API 设计标准
• 在实现前评审 API 规格说明
• 在 REST 与 GraphQL 等不同范式之间迁移

使用方法

本技能作为 Claude 的 Skill 使用，无需独立安装。在你支持 Claude Skills 的环境中加载该技能后，直接提出 API 设计相关需求即可，例如：

• “帮我设计一个用户管理的 REST API。”
• “评审这份 GraphQL schema，并指出可改进之处。”
• “为团队制定统一的 API 版本控制策略。”

技能会围绕以下核心原则给出建议：

• RESTful 设计：资源导向 URL、正确使用 HTTP 方法（GET、POST、PUT、PATCH、DELETE）、统一命名规范。
• GraphQL 设计：Schema 优先、类型定义领域模型、Query/Mutation/Subscription 分离、强类型与内省支持。
• API 版本控制：URL 版本、Header 版本或查询参数版本等策略。
• 常见模式：分页与过滤、错误处理与状态码、HATEOAS 超媒体链接等。

如需深入了解，可参考该技能内置的代码示例与模式说明。