⚡

API设计审查员 api-design-reviewer

API设计审查员技能专注于REST API设计的综合分析和审查，包括自动化linting、破坏性变更检测和设计评分卡，以确保API的一致性、文档完整性和安全性。

架构设计 0 次安装 0 次浏览 更新于 3/5/2026

API设计审查员

**层级：**强大
**类别：**工程/架构
**维护者：**Claude技能团队

概览

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

核心能力

1. API Linting和约定分析

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

2. 破坏性变更检测

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

3. API设计评分和评估

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

REST设计原则

资源命名约定

✅ 好的示例：
- /api/v1/users
- /api/v1/user-profiles
- /api/v1/orders/123/line-items

❌ 坏的示例：
- /api/v1/getUsers
- /api/v1/user_profiles
- /api/v1/orders/123/lineItems

HTTP方法使用

  • GET：检索资源（安全，幂等）
  • POST：创建新资源（不幂等）
  • PUT：替换整个资源（幂等）
  • PATCH：部分资源更新（不一定幂等）
  • DELETE：移除资源（幂等）

URL结构最佳实践

集合资源：/api/v1/users
单个资源：/api/v1/users/123
嵌套资源：/api/v1/users/123/orders
动作：/api/v1/users/123/activate (POST)
过滤：/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": "2024-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：意外的服务器错误

认证和授权模式

持有者令牌认证

Authorization: Bearer <token>

API密钥认证

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": "john@example.com",
  "_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和描述
  • 路径定义：所有端点及其方法
  • 参数定义：查询、路径、头参数
  • 请求/响应模式：完整的数据模型
  • 安全定义：认证方案
  • 错误响应：标准错误格式

最佳实践

  • 使用一致的命名约定
  • 为所有组件提供详细的描述
  • 为复杂对象提供示例
  • 定义可重用的组件和模式
  • 根据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）
  • 实现高效分页
  • 使用ETags进行条件请求

资源优化

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

安全最佳实践

输入验证

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

认证安全

  • 在任何地方使用HTTPS
  • 实施安全的令牌存储
  • 支持令牌过期和刷新
  • 使用强大的认证机制

授权控制

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

工具和脚本

api_linter.py

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

特点：

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

breaking_change_detector.py

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

特点：

  • 端点比较
  • 模式变更检测
  • 字段移除/修改跟踪
  • 迁移指南生成
  • 影响严重性评估

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/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. 不充分的测试：测试所有方面，包括错误情况和边界条件

结论

API设计审查员技能提供了一个全面的框架，用于构建、审查和维护高质量的REST API。通过遵循这些指导方针和使用提供的工具，开发团队可以创建一致的、文档齐全的、安全的和可维护的API。

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