microwind API验证器技能
概述
API是系统之间的契约。无效或设计不当的API会导致集成问题、错误和性能问题。在实施前验证API设计。
核心原则: 好的API设计让集成变得简单。坏的API设计让集成变得痛苦。在设计问题造成集成地狱之前修复它们。
何时使用
始终:
- 在实施新API之前
- 在代码审查期间验证API设计
- 检查REST约定
- 审查API结构
- 规划API变更或迁移
- 调试集成问题
- 当客户端报告集成问题时
触发短语:
- "这个API设计好吗？"
- "检查REST约定"
- "验证API结构"
- "这个端点应该如何工作？"
- "审查API设计"
- "为什么这个客户端无法集成？"
- "设计一个新的API端点"
API验证器功能
设计分析
- REST约定合规性（GET/POST/PUT/DELETE/PATCH）
- 端点命名一致性
- HTTP方法正确性
- 状态码使用（200, 201, 400, 404, 500）
- 请求/响应结构一致性
- 头部管理（Content-Type, Authorization）
- 版本控制策略
反模式检测
- 受保护端点缺少身份验证
- 错误处理差（模糊的错误消息）
- 端点间命名不一致
- 过于复杂的端点（参数太多）
- 缺少版本控制（破坏性变更）
- RPC风格端点（非RESTful）
- 混合关注点（数据+导航）
最佳实践检查
- 一致的响应格式（JSON结构）
- 正确的错误响应格式
- API文档完整性
- 速率限制设计
- 分页实现
- 缓存头部（ETag, Cache-Control）
- 适当情况下的HATEOAS链接
常见API设计问题
错误的HTTP方法
问题:
POST /users/delete/123 ❌ 使用POST进行删除
GET /users/create ❌ 使用GET进行创建
PUT /users ❌ 使用PUT进行部分更新
后果:
- 客户端对用法感到困惑
- 缓存破坏（GET应该是幂等的）
- REST工具无法识别模式
- 难以文档化和测试
解决方案:
DELETE /users/123 ✓ 清晰的意图
POST /users ✓ 创建新资源
PATCH /users/123 ✓ 部分更新（或PUT用于完整更新）
不一致的命名
问题:
GET /users ✓
GET /all_products ❌ 不一致的命名
POST /add_item ❌ URL中的动词
GET /getUserById ❌ 不一致的风格
后果:
- 难以记住端点结构
- 客户端必须不断查看文档
- 容易出错
- 不是自文档化的
解决方案:
GET /users ✓ 一致
GET /products ✓ 一致
POST /items ✓ 一致
GET /users/123 ✓ ID的一致模式
缺少版本控制
问题:
/api/users ❌ 没有版本 - 破坏性变更会破坏所有客户端
POST /users body: {name, email} ❌ 后来添加必填字段，破坏旧客户端
后果:
- 无法演进API
- 破坏性变更影响所有人
- 无法保持向后兼容性
- 客户端困在旧版本
解决方案:
/api/v1/users ✓ 清晰的版本
/api/v2/users ✓ 用于不兼容变更的新版本
Accept: application/vnd.api+json;version=2 ✓ 基于头部的版本控制
差的错误响应
问题:
"error": "Something went wrong" ❌ 模糊 - 出了什么问题？
HTTP 500 for validation error ❌ 错误的状态码
No error codes / only message ❌ 难以程序化处理
后果:
- 客户端无法正确处理错误
- 难以调试集成问题
- 用户体验差
- 无法智能重试
解决方案:
{
"error": "validation_error",
"message": "Email is required",
"field": "email",
"code": 400
}
✓ 清晰、具体、可操作
缺少身份验证/授权
问题:
GET /admin/users ❌ 没有身份验证检查
POST /payments ❌ 任何用户都可以访问
DELETE /users/123 ❌ 用户可以删除其他用户
后果:
- 安全漏洞
- 数据泄露
- 未授权访问
- 合规性违规
解决方案:
要求授权头部
检查用户权限
记录安全要求
使用OAuth/JWT令牌
验证检查清单
RESTful设计:
- 每个操作使用正确的HTTP方法（GET, POST, PUT, PATCH, DELETE）
- 所有端点遵循
/resource或/resource/id/subresource模式 - URL中没有动词（例如，不是
/getUser或/deleteUser） - 没有RPC风格端点（例如，不是
/api.php?method=user.get） - 端点间命名一致（复数名词，小写）
- HTTP状态码正确（200, 201, 400, 404, 500）
- 响应格式一致（所有返回相同JSON结构）
- 错误响应包含：代码、消息、详情
API成熟度:
- API版本控制策略已记录
- 身份验证/授权要求清晰
- 速率限制已记录
- 列表端点已实现分页
- 过滤/排序选项已记录
- 旧端点的弃用路径
- 破坏性变更已处理（版本控制）
- CORS头部已记录（如适用）
文档:
- 每个端点都有示例记录
- 请求/响应模式已记录
- 错误代码和消息已记录
- 身份验证方法已记录
- 速率限制已记录
- 提供了示例curl/代码片段
如何使用
基础API设计审查
审查你的API端点：
1. 将所有端点映射到HTTP方法
2. 检查每个使用正确的方法（GET/POST/PUT/PATCH/DELETE）
3. 验证命名一致
4. 检查状态码是否适当
5. 确保错误响应一致
示例：
✓ GET /api/v1/users (列表)
✓ GET /api/v1/users/123 (获取一个)
✓ POST /api/v1/users (创建)
✓ PATCH /api/v1/users/123 (更新)
✓ DELETE /api/v1/users/123 (删除)
所有都使用一致的命名、正确的方法、可预测的结构。
遇到困难时
| 问题 | 解决方案 |
|---|---|
| "我应该使用PUT还是PATCH？" | PUT替换整个资源，PATCH部分更新。更新时使用PATCH。 |
| "如何为API版本控制？" | 在URL或Accept头部中使用/api/v1/、/api/v2/。从一开始就规划版本控制。 |
| "应该使用什么状态码？" | 200（成功）、201（已创建）、400（错误请求）、404（未找到）、500（服务器错误）。 |
| "如何处理错误？" | 一致格式：{代码、消息、详情}。使用HTTP状态码进行分类。 |
| "客户端无法集成 - 为什么？" | 检查：方法正确、端点路径已记录、身份验证正常工作、响应格式与文档匹配。 |
| "破坏性变更 - 怎么办？" | 创建新版本（/v2/）。保持旧版本正常工作。记录迁移路径。 |
反模式（红旗警告）
❌ RPC风格API（非RESTful）
GET /api/getUser?id=123
GET /api/deleteUser?id=123
POST /api/createUser
↓
难以理解、非RESTful、令人困惑
❌ 不一致的命名
GET /users
GET /all_products
POST /add_item
DELETE /removeUser/123
↓
无法预测端点结构，难以记住
❌ 错误的HTTP方法
POST /users/delete/123
GET /users/create
PUT /users/123 (当你需要部分更新时)
↓
破坏缓存、混淆工具、违反REST
❌ 没有错误结构
响应: "Error: Something went wrong"
没有错误代码、没有详情、模糊消息
↓
客户端无法正确处理错误
❌ 缺少身份验证
POST /admin/users (没有身份验证检查)
DELETE /users/123 (任何用户都可以删除任何用户)
GET /payments (敏感数据暴露)
↓
安全漏洞
❌ 没有版本控制
/api/users
后来在POST正文中添加必填字段
所有旧客户端立即破坏
↓
无法安全地演进API
相关技能
- security-scanner - 检查API安全和身份验证
- code-review - 审查API实现
- api-tester - 测试API端点正常工作
- request-debugger - 调试API请求/响应问题