API 设计评审员

api-design-reviewer

分类编程

作者Alireza Rezvani

许可MIT

评分4.30/5

使用16.7K

API 设计审查员 (API Design Reviewer)

等级： POWERFUL
类别： 工程 / 架构
维护者： Claude Skills Team

概述

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

快速上手 — 请先运行工具

bash

# 1. 对 OpenAPI/Swagger 规范进行 Lint 检查，查找约定违规
python3 scripts/api_linter.py openapi.json --format json -o lint.json
2. 检测两个规范版本之间的破坏性变更（门禁：使用 --exit-on-breaking 时，若有破坏性变更则以非零状态退出）
python3 scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json --format json --exit-on-breaking -o breaking.json
3. 对整体设计质量评分（门禁：低于 --min-grade 阈值则失败）
python3 scripts/api_scorecard.py openapi.json --format json --min-grade B -o scorecard.json

审查流程：运行上述三个工具，向用户报告 Lint 结果 + 破坏性变更 + 评分，修复问题，然后重新运行，直到 Lint 检查通过、--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 设计原则

资源命名约定

code

✅ 正确示例： /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

code

### 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

code

## 版本控制策略
1. URL 版本控制（推荐）

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

code

优点: 清晰、明确，易于路由  
缺点: URL 数量激增，缓存复杂度增加
2. Header 版本控制

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

code

优点: URL 简洁，支持内容协商  
缺点: 可见性较低，手动测试较困难
3. 媒体类型 (Media Type) 版本控制

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

code

优点: 符合 RESTful 规范，支持多种表示形式  
缺点: 复杂，实现难度较高
4. 查询参数版本控制

/api/users?version=1

code

优点: 实现简单  
缺点: 不符合 RESTful 规范，容易被忽略
分页模式
基于偏移量 (Offset-Based) 的分页

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

code

### 基于游标 (Cursor-Based) 的分页

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

code

### 基于页码 (Page-Based) 的分页

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

code

## 错误响应格式
标准错误结构

json { "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" } }

code

### 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>

code

### API Key 认证

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

code

### OAuth 2.0 流程

Authorization: Bearer <oauth-access-token>

code

### 基于角色的访问控制 (RBAC)

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

code

## 速率限制实现
响应头

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

code

### 超过限制时的响应

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

code

## HATEOAS (超媒体作为应用程序状态的引擎)
示例 I
实现

json { "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" } } }

code

## 幂等性
幂等方法
GET: 始终安全且幂等
PUT: 应幂等（替换整个资源）
DELETE: 应幂等（结果相同）
PATCH: 可能幂等，也可能不幂等
幂等键 (Idempotency Keys)

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

code

## 向后兼容指南
安全变更（非破坏性）
在请求中添加可选字段
在响应中添加字段
添加新端点
将必填字段改为可选
添加新的枚举值（需具备优雅处理机制）
破坏性变更（需要升级版本）
从响应中删除字段
将可选字段改为必填
更改字段类型
删除端点
更改 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

code

### 高效数据传输
使用合适的 HTTP 方法
实现字段筛选 (?fields=id,name,email)
支持压缩 (gzip)
实现高效的分页
使用 ETag 进行条件请求
资源优化
避免 N+1 查询
实现批量操作
对繁重操作使用异步处理
支持部分更新 (PATCH)
安全最佳实践
输入验证
验证所有输入参数
对用户数据进行清洗 (Sanitize)
使用参数化查询
实现请求大小限制
认证安全
全面使用 HTTPS
实现安全的令牌存储
支持令牌过期和刷新
使用强认证机制
权限控制
遵循最小权限原则
使用基于资源的权限管理
支持细粒度访问控制
审计访问模式
工具与脚本
api_linter.py
分析 API 规范是否符合 REST 约定和最佳实践。
功能：
OpenAPI/Swagger 规范验证

命名规范检查

HTTP 方法使用验证

错误格式一致性检查

文档完整性分析

breaking_change_detector.py
对比 API 规范版本以识别破坏性变更。
功能：
端点对比

Schema 变更检测

字段删除/修改追踪

迁移指南生成

影响严重程度评估

api_scorecard.py
对 API 设计质量提供综合评分。
功能：
多维度评分

详细的改进建议

等级评估 (A-F)

基准对比

进度跟踪

集成示例
CI/CD 集成

yaml

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

code

### Pre-commit 钩子

bash #!/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 在整个开发生命周期中持续改进并保持高质量。

API 设计评审员

API 设计审查员 (API Design Reviewer)

概述

快速上手 — 请先运行工具

2. 检测两个规范版本之间的破坏性变更（门禁：使用 --exit-on-breaking 时，若有破坏性变更则以非零状态退出）

3. 对整体设计质量评分（门禁：低于 --min-grade 阈值则失败）

核心能力

1. API Lint 检查与约定分析

2. 破坏性变更检测

3. API 设计评分与评估

REST 设计原则

资源命名约定

URL 结构最佳实践

1. URL 版本控制（推荐）

2. Header 版本控制

3. 媒体类型 (Media Type) 版本控制

4. 查询参数版本控制

分页模式

基于偏移量 (Offset-Based) 的分页

标准错误结构

认证与授权模式

Bearer Token 认证

响应头

示例 I

幂等方法

幂等键 (Idempotency Keys)

安全变更（非破坏性）

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

OpenAPI/Swagger 验证

必要组件

最佳实践

性能考量

缓存策略

资源优化

安全最佳实践

输入验证

认证安全

权限控制

工具与脚本

api_linter.py

breaking_change_detector.py

api_scorecard.py

集成示例

CI/CD 集成

最佳实践总结

应避免的常见反模式

扫码进交流群

`URL 结构最佳实践`

`1. URL 版本控制（推荐）`

`2. Header 版本控制`

`3. 媒体类型 (Media Type) 版本控制`

`4. 查询参数版本控制`

`基于偏移量 (Offset-Based) 的分页`

`标准错误结构`

`Bearer Token 认证`

`响应头`

`幂等键 (Idempotency Keys)`

`缓存策略`

`CI/CD 集成`