an8079 api-reviewer
API 质量专项审查技能 — RESTful/GraphQL/WebSocket 接口规范性、安全性、性能审查
触发词
api review, 接口审查, API质量, 接口安全, api-review
概述
作为 api-reviewer，专注于 API 的质量审查，涵盖 RESTful 设计规范、GraphQL schema 设计、WebSocket 协议、安全性和性能问题。
核心审查维度
1. API 设计规范
- RESTful 路由规范（名词复数、层级嵌套限制）
- HTTP 方法正确使用（GET/POST/PUT/DELETE/PATCH）
- 状态码标准使用（200/201/400/401/403/404/500）
- 错误响应格式一致性（error object 结构）
- GraphQL schema 规范（Query/Mutation/Subscription 分离）
2. 接口安全性
- 认证授权检查（JWT 验证、权限校验）
- 敏感数据暴露（密码、token 不应在响应中返回）
- SQL/NoSQL 注入风险
- 参数校验（类型、范围、格式）
- CORS 配置检查
- Rate Limiting 实现检查
3. 接口性能
- N+1 查询问题检测
- 不必要的全量查询
- 分页实现检查
- 缓存头部设置（Cache-Control/ETag）
- 响应体大小（是否压缩）
4. 版本管理
- API 版本控制规范（URL versioning vs Header versioning）
- 破坏性变更标识
- 废弃 API 标识
5. 文档完整性
- OpenAPI/Swagger 文档存在性
- 请求/响应示例完整性
- 字段说明完整性
- 错误码文档
审查检查清单
[ ] RESTful 规范
- [ ] 路由使用名词复数 /users, /orders
- [ ] 正确 HTTP 方法
- [ ] 状态码标准使用
- [ ] 嵌套路由不超过 2 层
[ ] GraphQL（如适用）
- [ ] Query 不应有副作用
- [ ] Mutation 返回有意义数据
- [ ] 避免深度嵌套查询
- [ ] N+1 问题（DataLoader）
[ ] 安全审查
- [ ] 所有变更操作用 POST/PUT/PATCH/DELETE
- [ ] 敏感字段已过滤（password, token）
- [ ] 输入参数校验存在
- [ ] SQL 注入风险评估
[ ] 性能审查
- [ ] 大列表有分页
- [ ] 无 N+1 查询
- [ ] 响应有 ETag/Cache-Control
[ ] 文档审查
- [ ] OpenAPI 文档存在且最新
- [ ] 所有端点有示例
- [ ] 错误码有说明
执行流程
Step 1: 定位 API 代码
# 查找 API 路由文件
find . -name "*.ts" -path "*/routes/*" -o -name "*.py" -path "*/endpoints/*"
find . -name "*.ts" -path "*/api/*" -o -name "*.go" -path "*/handlers/*"
# 查找 GraphQL
find . -name "schema.*" -o -name "*.graphqls"
# 查找 OpenAPI
find . -name "openapi.*" -o -name "swagger.*" -o -name "*.yaml" -path "*/api/*"
Step 2: 分析 API 结构
- 读取路由定义
- 分析输入输出模型
- 检查中间件链
- 审查认证逻辑
Step 3: 安全扫描
- 敏感数据流分析
- 权限模型检查
- 输入验证覆盖度
Step 4: 输出报告
## API 审查报告
### 端点统计: X 个
- RESTful: X | GraphQL: X | WebSocket: X
### 发现问题: X个
| 严重度 | 端点 | 问题 | 建议 |
|--------|------|------|------|
| 🔴 Critical | POST /api/users | 密码明文返回 | 过滤 password 字段 |
| 🟡 Warning | GET /api/orders | 无分页参数 | 添加 ?page=&limit= |
输出标准
- 端点全覆盖: 列出所有审查的端点
- 问题具体化: 端点 + HTTP方法 + 问题描述
- 安全第一: 安全隐患必须高亮
- 可执行建议: 提供修复代码示例
工具推荐
eslint-plugin-security— JavaScript 安全扫描sobelow— Elixir API 安全bandit— Python 安全扫描OWASP ZAP— API 渗透测试