API设计Skill api-design

---

名称: api-design 描述: 设计遵循规范的RESTful API，包括适当的错误处理、版本控制和文档化。在创建或修改API端点时使用。

API设计技能

目的

创建一致、设计良好的API。

REST规范

参考: standards/rest-conventions.md

HTTP方法

方法	使用场景	幂等性
GET	检索资源	是
POST	创建资源	否
PUT	替换资源	是
PATCH	部分更新	否
DELETE	删除资源	是

URL模式

GET    /users           # 列出用户
GET    /users/:id       # 获取用户
POST   /users           # 创建用户
PUT    /users/:id       # 替换用户
PATCH  /users/:id       # 更新用户
DELETE /users/:id       # 删除用户

GET    /users/:id/posts # 嵌套资源

响应状态码

代码	含义	使用时机
200	成功	成功的GET、PUT、PATCH
201	已创建	成功的POST
204	无内容	成功的DELETE
400	错误请求	验证错误
401	未授权	需要认证
403	禁止访问	认证不足
404	未找到	资源不存在
422	无法处理	业务规则违反
500	服务器错误	意外错误

错误响应格式

参考: standards/error-responses.md

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "验证失败",
    "details": [
      {
        "field": "email",
        "message": "无效的邮箱格式"
      }
    ]
  }
}

版本控制

参考: standards/versioning.md

选项:

• URL: /api/v1/users
• 头部: Accept: application/vnd.api.v1+json

推荐: 使用URL版本控制以简化

端点文档

使用模板: templates/endpoint-doc.md