api-design-reviewer

API 设计审查器

等级: POWERFUL
分类: 工程 / 架构
维护者: Claude Skills Team

概述

API 设计审查器 Skill 提供对 API 设计的全面分析与审查，重点关注 REST 约定、最佳实践和行业标准。该 Skill 通过自动化 lint 检查、破坏性变更检测和设计评分卡，帮助工程团队构建一致、可维护且设计良好的 API。

快速开始 — 先运行工具

# 1. Lint an OpenAPI/Swagger spec for convention violations
python3 scripts/api_linter.py openapi.json --format json -o lint.json

# 2. Detect breaking changes between two spec versions (gate: exits non-zero with --exit-on-breaking)
python3 scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json --format json --exit-on-breaking -o breaking.json

# 3. Score overall design quality (gate: --min-grade fails below threshold)
python3 scripts/api_scorecard.py openapi.json --format json --min-grade B -o scorecard.json

审查流程：运行全部三个工具，向用户报告 linter 发现的问题、破坏性变更和评级，进行修复，然后重新运行，直到 linter 无问题、--exit-on-breaking 通过（或破坏性变更已通过版本号升级处理），且评分卡达到约定的 --min-grade。切勿仅凭文字描述就通过 API 审查，必须附上工具输出。

核心能力

1. API Lint 与约定分析

• 资源命名约定：资源使用 kebab-case，字段使用 camelCase
• HTTP 方法使用：校验 GET、POST、PUT、PATCH、DELETE 的正确使用
• URL 结构：分析端点模式的一致性和 RESTful 设计
• 状态码合规性：确保使用恰当的 HTTP 状态码
• 错误响应格式：校验错误响应结构的一致性
• 文档覆盖率：检查缺失的描述和文档空白

2. 破坏性变更检测

• 端点移除：检测已移除或已弃用的端点
• 响应结构变更：识别响应结构的修改
• 字段移除：跟踪 API 响应中被移除或重命名的字段
• 类型变更：捕获可能破坏客户端的字段类型修改
• 新增必填字段：标记可能破坏现有集成的新必填字段
• 状态码变更：检测预期状态码的变化

3. API 设计评分与评估

• 一致性分析（30%）：评估命名约定、响应模式和结构一致性
• 文档质量（20%）：评估 API 文档的完整性和清晰度
• 安全实现（20%）：审查认证、授权和安全响应头
• 可用性设计（15%）：分析易用性、可发现性和开发者体验
• 性能模式（15%）：评估缓存、分页和效率模式

REST 设计原则

资源命名约定

✅ Good Examples:
- /api/v1/users
- /api/v1/user-profiles
- /api/v1/orders/123/line-items

❌ Bad Examples:
- /api/v1/getUsers
- /api/v1/user_profiles
- /api/v1/orders/123/lineItems

HTTP 方法使用

• GET：获取资源（安全、幂等）
• POST：创建新资源（非幂等）
• PUT：整体替换资源（幂等）
• PATCH：部分更新资源（不一定幂等）
• DELETE：删除资源（幂等）

URL 结构最佳实践

Collection Resources: /api/v1/users
Individual Resources: /api/v1/users/123
Nested Resources: /api/v1/users/123/orders
Actions: /api/v1/users/123/activate (POST)
Filtering: /api/v1/users?status=active&role=admin

版本控制策略

1. URL 版本控制（推荐）

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

优点：清晰、明确、易于路由
缺点：URL 数量膨胀，缓存复杂

2. 请求头版本控制

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

优点：URL 简洁，支持内容协商
缺点：不够直观，手动测试较难

3. 媒体类型版本控制

GET /api/users
Accept: application/vnd.myapi.v1+json

优点：符合 RESTful，支持多种表示形式
缺点：复杂，实现难度较高

4. 查询参数版本控制

/api/users?version=1

优点：实现简单
缺点：不符合 RESTful，可能被忽略

分页模式

基于偏移量的分页

{
  "data": [...],
  "pagination": {
    "offset": 20,
    "limit": 10,
    "total": 150,
    "hasMore": true
  }
}

基于游标的分页

{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTIzfQ==",
    "hasMore": true
  }
}

基于页码的分页

{
  "data": [...],
  "pagination": {
    "page": 3,
    "pageSize": 10,
    "totalPages": 15,
    "totalItems": 150
  }
}

错误响应格式

标准错误结构

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid parameters",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Email address is not valid"
      }
    ],
    "requestId": "req-123456",
    "timestamp": "2026-02-16T13:00:00Z"
  }
}

HTTP 状态码用法

• 400 Bad Request：请求语法或参数无效
• 401 Unauthorized：需要身份验证
• 403 Forbidden：拒绝访问（已通过身份验证但无权限）
• 404 Not Found：未找到资源
• 409 Conflict：资源冲突（重复、版本不匹配）
• 422 Unprocessable Entity：语法有效但存在语义错误
• 429 Too Many Requests：超出速率限制
• 500 Internal Server Error：服务器发生意外错误

身份验证与授权模式

Bearer Token 身份验证

Authorization: Bearer <token>

API Key 身份验证

X-API-Key: <api-key>
Authorization: Api-Key <api-key>

OAuth 2.0 流程

Authorization: Bearer <oauth-access-token>

基于角色的访问控制（RBAC）

{
  "user": {
    "id": "123",
    "roles": ["admin", "editor"],
    "permissions": ["read:users", "write:orders"]
  }
}

速率限制实现

响应头

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

超出限制时的响应

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "retryAfter": 3600
  }
}

HATEOAS（超媒体即应用状态引擎）

示例实现

{
  "id": "123",
  "name": "John Doe",
  "email": "[email protected]",
  "_links": {
    "self": { "href": "/api/v1/users/123" },
    "orders": { "href": "/api/v1/users/123/orders" },
    "profile": { "href": "/api/v1/users/123/profile" },
    "deactivate": { 
      "href": "/api/v1/users/123/deactivate",
      "method": "POST"
    }
  }
}

幂等性

幂等方法

• GET：始终安全且幂等
• PUT：应当是幂等的（替换整个资源）
• DELETE：应当是幂等的（结果相同）
• PATCH：可能是幂等的，也可能不是

幂等键

POST /api/v1/payments
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000

向后兼容性指南

安全变更（非破坏性）

• 向请求添加可选字段
• 向响应添加字段
• 添加新端点
• 将必填字段改为可选
• 添加新的枚举值（需优雅处理）

破坏性变更（需要升级版本号）

• 从响应中删除字段
• 将可选字段改为必填
• 更改字段类型
• 删除端点
• 更改 URL 结构
• 修改错误响应格式

OpenAPI/Swagger 校验

必需组件

• API 信息：标题、描述、版本
• 服务器信息：基础 URL 及描述
• 路径定义：所有端点及其方法
• 参数定义：查询参数、路径参数、请求头参数
• 请求/响应 Schema：完整的数据模型
• 安全定义：身份验证方案
• 错误响应：标准错误格式

最佳实践

• 使用一致的命名约定
• 为所有组件提供详细描述
• 为复杂对象提供示例
• 定义可复用的组件和 Schema
• 依据 OpenAPI 规范进行校验

性能考量

缓存策略

Cache-Control: public, max-age=3600
ETag: "123456789"
Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT

高效数据传输

• 使用恰当的 HTTP 方法
• 实现字段选择（?fields=id,name,email）
• 支持压缩（gzip）
• 实现高效的分页
• 使用 ETag 进行条件请求

资源优化

• 避免 N+1 查询
• 实现批量操作
• 对耗时操作使用异步处理
• 支持部分更新（PATCH）

安全最佳实践

输入校验

• 校验所有输入参数
• 清理用户数据
• 使用参数化查询
• 实现请求大小限制

身份验证安全

• 全程使用 HTTPS
• 实现安全的令牌存储
• 支持令牌过期与刷新
• 使用强身份验证机制

授权控制

• 遵循最小权限原则
• 使用基于资源的权限
• 支持细粒度的访问控制
• 审计访问模式

工具与脚本

api_linter.py

分析 API 规范是否符合 REST 约定和最佳实践。

功能特性：

• OpenAPI/Swagger 规范校验
• 命名约定检查
• HTTP 方法用法校验
• 错误格式一致性检查
• 文档完整性分析

breaking_change_detector.py

比较 API 规范版本，识别破坏性变更。

功能特性：

• 端点比较
• Schema 变更检测
• 字段删除/修改追踪
• 迁移指南生成
• 影响严重程度评估

api_scorecard.py

对 API 设计质量进行全面评分。

功能特性：

• 多维度评分
• 详细的改进建议
• 字母等级评定（A-F）
• 基准对比
• 进度追踪

集成示例

CI/CD 集成

- name: "api-linting"
  run: python scripts/api_linter.py openapi.json

- name: "breaking-change-detection"
  run: python scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json

- name: "api-scorecard"
  run: python scripts/api_scorecard.py openapi.json

预提交钩子

#!/bin/bash
python engineering/skills/api-design-reviewer/scripts/api_linter.py api/openapi.json
if [ $? -ne 0 ]; then
  echo "API linting failed. Please fix the issues before committing."
  exit 1
fi

最佳实践总结

1. 一致性优先：保持命名、响应格式和模式的一致
2. 文档：提供全面且及时更新的 API 文档
3. 版本管理：通过清晰的版本策略为演进做好规划
4. 错误处理：实现一致且信息丰富的错误响应
5. 安全性：将安全性融入 API 的每一层
6. 性能：从一开始就为规模化和效率进行设计
7. 向后兼容：尽量减少破坏性变更，并提供迁移路径
8. 测试：开展全面测试，包括契约测试
9. 监控：为 API 的使用情况和性能增加可观测性
10. 开发者体验：优先考虑易用性和清晰的文档

需要避免的常见反模式

1. 基于动词的 URL：使用名词表示资源，而不是动作
2. 不一致的响应格式：保持标准的响应结构
3. 过度嵌套：避免层级很深的资源结构
4. 忽视 HTTP 状态码：针对不同场景使用恰当的状态码
5. 糟糕的错误信息：提供可操作、具体的错误信息
6. 缺少分页：列表接口始终应当分页
7. 没有版本策略：从第一天起就为 API 演进做好规划
8. 暴露内部结构：为外部使用而设计 API，而不是为内部便利而设计
9. 缺少速率限制：保护 API 免受滥用和过载影响
10. 测试不足：测试所有方面，包括错误情况和边界条件

定期使用 lint、破坏性变更检测和评分工具，有助于持续改进，并在整个开发生命周期中维持 API 质量。