mcpField
A
api-design-principles

api-design-principles

github.com/wshobson开发41.9k30.7k 次安装2 周前更新
代码仓库

关于 api-design-principles

面向设计、评审或编写 REST 与 GraphQL API 文档的团队，介绍资源建模、版本管理和接口设计原则。

主要功能

  1. 01REST 资源与 HTTP 方法设计
  2. 02GraphQL Schema 与查询结构
  3. 03API 版本管理策略
  4. 04分页、限流与错误处理建议

适用场景

  1. 01设计新的 REST 或 GraphQL API
  2. 02评审 API 规范并制定团队标准
  3. 03改进 API 文档与开发者体验
  4. 04规划 API 范式迁移

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wshobson/agents --skill api-design-principles

安装后在 Claude Code 中输入/api-design-principles确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

assets/
api-design-checklist.md
rest-api-template.py
references/
details.md
graphql-schema-design.md
rest-best-practices.md

详细介绍

API 设计原则

掌握 REST 和 GraphQL API 设计原则，构建直观、可扩展且易于维护的 API，让开发者满意，并经受住时间的考验。

何时使用此技能

  • 设计新的 REST 或 GraphQL API
  • 重构现有 API 以提升易用性
  • 为团队建立 API 设计标准
  • 在实现前审查 API 规范
  • 在 API 范式之间迁移（REST 到 GraphQL 等）
  • 创建对开发者友好的 API 文档
  • 针对特定用例优化 API（移动端、第三方集成）

核心概念

1. RESTful 设计原则

面向资源的架构

  • 资源是名词（users、orders、products），而不是动词
  • 使用 HTTP 方法表示操作（GET、POST、PUT、PATCH、DELETE）
  • URL 表示资源层级
  • 一致的命名约定

HTTP 方法语义：

  • GET：检索资源（幂等、安全）
  • POST：创建新资源
  • PUT：替换整个资源（幂等）
  • PATCH：部分更新资源
  • DELETE：删除资源（幂等）
2. GraphQL 设计原则

Schema 优先开发

  • 类型定义你的领域模型
  • 查询用于读取数据
  • 变更用于修改数据
  • 订阅用于实时更新

查询结构：

  • 客户端只请求所需内容
  • 单一端点，多种操作
  • 强类型 Schema
  • 内置内省
3. API 版本管理策略

URL 版本管理：

/api/v1/users
/api/v2/users

请求头版本管理：

Accept: application/vnd.api+json; version=1

查询参数版本管理：

/api/users?version=1

详细模式与完整示例

详细模式文档位于 references/details.md。当上方的导航层级不够用时，请阅读该文件。

最佳实践

REST API
  1. 一致命名：集合使用复数名词（/users，而不是 /user）
  2. 无状态：每个请求都包含所有必要信息
  3. 正确使用 HTTP 状态码：2xx 成功，4xx 客户端错误，5xx 服务端错误
  4. 为 API 添加版本：从第一天起就为破坏性变更做好规划
  5. 分页：始终对大型集合进行分页
  6. 速率限制：用速率限制保护你的 API
  7. 文档：使用 OpenAPI/Swagger 提供交互式文档
GraphQL API
  1. Schema 优先：在编写解析器之前先设计 Schema
  2. 避免 N+1：使用 DataLoader 实现高效数据获取
  3. 输入验证：在 Schema 和解析器层面进行验证
  4. 错误处理：在变更响应中返回结构化错误
  5. 分页：使用基于游标的分页（Relay 规范）
  6. 弃用：使用 @deprecated 指令实现渐进式迁移
  7. 监控：跟踪查询复杂度和执行时间

常见陷阱

  • 过度获取/获取不足（REST）：GraphQL 中已解决，但需要 DataLoader
  • 破坏性变更：为 API 添加版本或使用弃用策略
  • 错误格式不一致：标准化错误响应
  • 缺少速率限制：没有限制的 API 容易遭受滥用
  • 文档不足：无文档的 API 会让开发者感到沮丧
  • 忽视 HTTP 语义：对幂等操作使用 POST 会破坏预期
  • 紧密耦合：API 结构不应照搬数据库 Schema

评论

支持 Markdown