用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/microwind/ai-skills --skill api命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | API验证器 |
| description | 当验证API实现、检查REST约定、分析API设计或调试API问题时使用。验证API结构、设计和最佳实践。 |
| license | MIT |
API是系统之间的契约。无效或设计不当的API会导致集成问题、错误和性能问题。在实施前验证API设计。
核心原则: 好的API设计让集成变得简单。坏的API设计让集成变得痛苦。在设计问题造成集成地狱之前修复它们。
始终:
触发短语:
问题:
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设计:
/resource或/resource/id/subresource模式/getUser或/deleteUser）/api.php?method=user.get）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