Agent skill
api-design
RESTful API 设计最佳实践。当用户需要设计 API 接口、定义端点规范、编写 API 文档、或评估现有 API 设计时使用此技能。
Install this agent skill to your Project
npx add-skill https://github.com/enoch-robinson/agent-skill-collection/tree/main/skills/development/api-design
SKILL.md
API Design
提供专业的 RESTful API 设计指导，确保接口一致性、可用性和可扩展性。
设计原则
- 资源导向：URL 表示资源，HTTP 方法表示操作
- 一致性：命名、格式、错误处理保持统一
- 版本化：支持 API 演进而不破坏现有客户端
- 自描述：响应包含足够信息供客户端理解
URL 设计规范
资源命名
GET /users# 获取用户列表
GET /users/{id} # 获取单个用户
POST /users # 创建用户
PUT /users/{id} # 更新用户（全量）
PATCH /users/{id} # 更新用户（部分）
DELETE /users/{id} # 删除用户
命名规则
- 使用名词复数：
/users而非/user - 使用小写和连字符：
/user-profiles而非/userProfiles - 避免动词：
POST /users而非/createUser - 嵌套资源：
/users/{id}/orders（最多 2 层）
HTTP 状态码
| 状态码 | 含义 | 使用场景 |
|---|---|---|
| 200 | OK | GET/PUT/PATCH 成功 |
| 201 | Created | POST 创建成功 |
| 204 | No Content | DELETE 成功 |
| 400 | Bad Request | 请求参数错误 |
| 401 | Unauthorized | 未认证 |
| 403 | Forbidden | 无权限 |
| 404 | Not Found | 资源不存在 |
| 422 | Unprocessable | 业务验证失败 |
| 500 | Server Error | 服务器错误 |
响应格式
成功响应
{
"data": {
"id": "123",
"name": "张三",
"email": "zhang@example.com"
},
"meta": {
"timestamp": "2024-01-15T10:30:00Z"
}
}
列表响应（带分页）
{
"data": [...],
"pagination": {
"page": 1,
"per_page": 20,
"total": 100,
"total_pages": 5
}
}
错误响应
{
"error": {
"code": "VALIDATION_ERROR",
"message": "请求参数验证失败",
"details": [
{"field": "email", "message": "邮箱格式不正确"}
]
}
}
版本控制
推荐 URL 路径版本：
/api/v1/users
/api/v2/users
查询参数规范
# 分页
?page=1&per_page=20
# 排序
?sort=created_at&order=desc
# 过滤
?status=active&role=admin
# 字段选择
?fields=id,name,email
# 搜索
?q=keyword
设计检查清单
- URL 使用名词复数
- HTTP 方法语义正确
- 状态码使用恰当
- 响应格式统一
- 错误信息清晰
- 支持分页和过滤
- 包含版本号
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
enoch-robinson/agent-skill-collection
your-skill-name
清晰描述这个 Skill 的功能以及何时使用它。包含触发条件和使用场景。
enoch-robinson/agent-skill-collection
changelog-writer
变更日志编写技能。当用户需要编写 CHANGELOG、版本发布说明、更新记录，或需要整理 Git 提交历史生成变更日志时使用此技能。
enoch-robinson/agent-skill-collection
PDF 处理工具包。用于提取文本和表格、创建新 PDF、合并拆分文档、旋转页面、处理表单。当需要程序化处理、生成或分析 PDF 文档时使用此技能。
enoch-robinson/agent-skill-collection
docx
Word 文档处理工具包。用于创建新文档、编辑现有文档、处理修订追踪、添加批注、提取文本。当需要处理 .docx 文件进行文档创建、修改或分析时使用此技能。
enoch-robinson/agent-skill-collection
xlsx
Excel 电子表格处理工具包。用于创建和编辑电子表格、数据分析、公式计算、格式化。当需要处理 .xlsx/.csv 文件进行数据操作、报表生成或财务建模时使用此技能。
enoch-robinson/agent-skill-collection
doc-generator
技术文档生成技能。当用户需要编写 README、API 文档、项目文档、技术规范、使用指南或任何技术文档时使用此技能。
Didn't find tool you were looking for?