Agent Skills
返回列表
💻

API 设计模式

开发编程 更新于 2026.08.30

将以下提示词粘贴到你的 AI 对话框中：

请根据 https://skillhub.cn/install/skillhub.md，安装 @user_3c6cb52e/api-design-patterns-sh-9b5q2l 。

技能介绍

需要解决的具体问题

API 设计中常见的工程痛点：资源命名风格混乱（单复数、大小写不统一）、HTTP 方法语义误用（如用 GET 执行状态变更）、分页方式选择不当导致性能瓶颈、版本迭代时破坏向后兼容性、限流策略缺乏明确规则等，这些问题直接影响 API 的可维护性和团队协作效率。

技能如何工作

资源命名规范

  • 使用复数名词表示资源集合：/users、/orders
  • 嵌套层级最多 2 层，超出改用查询参数或顶层资源
  • 采用 kebab-case 命名：/user-profiles
  • 禁止在 URL 中使用动词：用 POST /users/{id}/activation 替代 /users/{id}/activate

HTTP 方法语义

| 方法 | 用途 | 幂等性 | 请求体 | 成功状态码 |
|------|------|--------|--------|------------|
| GET | 读取资源 | 是 | 否 | 200 |
| POST | 创建资源 | 否 | 是 | 201 |
| PUT | 全量替换 | 是 | 是 | 200 |
| PATCH | 部分更新 | 否 | 是 | 200 |
| DELETE | 删除资源 | 是 | 否 | 204 |

  • POST 请求需返回 Location 头指向新资源

分页与数据操作

  • 优先使用游标分页（cursor-based），将游标编码为不透明 Base64 字符串
  • 偏移分页（offset-based）仅适用于小型、静态数据集
  • 支持通过 fields 参数筛选字段，- 前缀表示降序排序

版本与兼容管理

  • 采用 URL 路径版本化：/v1/users
  • 发布 v1 后禁止破坏性修改，新增字段而非删除
  • 新必填字段需升级版本，旧版本通过 Sunset 头通知下线（至少 6 个月过渡期）
  • 同时支持最多 2 个活跃版本

OpenAPI 与限流

  • 使用 $ref 引用共享 schema，为每个端点定义示例
  • 通过规范生成客户端 SDK，禁止手写
  • 限流采用滑动窗口算法，返回 429 并附带 Retry-After 头
  • 所有响应包含 X-Request-Id 用于调试

适用边界与注意事项

  • 游标分页需保证游标不透明，禁止暴露原始 ID
  • 版本管理规则仅适用于对外 API，内部服务可适当简化
  • 限流策略需豁免健康检查和认证端点，记录被限流请求用于异常检测
  • 小型项目可暂不实现复杂版本管理，优先保证命名和方法规范
  • 字段筛选和排序参数需在 API 文档中明确定义允许的字段名

使用场景

  • 设计新 API 端点时，需统一资源命名（复数名词、kebab-case）、选择正确 HTTP 方法，并确保 POST 返回 `Location` 头
  • 维护 API 版本时，需避免破坏 v1 向后兼容（仅新增字段），新必填字段触发版本升级，并通过 `Sunset` 头通知旧版本下线
  • 实现分页功能时，需判断数据集特性：大型或动态数据集用游标分页（Base64 编码），小型或静态数据集用偏移分页
  • 编写 API 文档时，需通过 OpenAPI 规范定义 schema（`$ref` 引用共享结构）、生成客户端 SDK，并在中间件中验证请求

适合人员

  • 后端开发工程师：需要设计符合 RESTful 规范的 API 接口，确保命名、方法、状态码、分页符合团队标准
  • API 产品经理：需要制定版本迭代策略，平衡新功能上线与旧版本兼容，明确限流规则和错误码规范
  • 技术文档工程师：需要编写准确的 API 参考文档，定义 OpenAPI 规范中的 schema 和示例，生成接口文档
  • 微服务架构师：需要设计可扩展的 API 网关，配置版本管理和限流策略，确保服务间的契约一致性