API Design Guidelines

RESTful API 设计规范 Skill

描述

这个 skill 帮助开发者在设计和实现后端接口时，遵循团队统一的 RESTful API 设计规范。它涵盖了资源命名、HTTP 动词使用、状态码返回、分页、过滤、版本控制等核心设计原则。

何时使用

在以下场景中使用这个 skill：

• AI 协助设计新的 API 接口时
• 重构现有不规范的接口路由时
• 编写 API 文档（如 Swagger/OpenAPI）时
• 用户询问如何设计分页、过滤或版本控制方案时

核心设计原则

1. 资源命名规范 (Resource Naming)

API 应该围绕资源（Resources）进行设计，而不是动作（Actions）。

• 使用名词，避免动词：
  • ✅ GET /users (获取用户列表)
  • ❌ GET /getUsers 或 POST /createUser
• 使用复数名词：
  • ✅ GET /users/123
  • ❌ GET /user/123
• 层级关系表示从属：
  • ✅ GET /users/123/orders (获取用户 123 的订单)
• 使用 kebab-case（短横线）分隔长单词：
  • ✅ GET /user-profiles
  • ❌ GET /userProfiles 或 GET /user_profiles

2. HTTP 动词的正确使用

• GET：读取资源（幂等且安全）
• POST：创建新资源（非幂等）
• PUT：全量更新资源（幂等）
• PATCH：局部更新资源（幂等）
• DELETE：删除资源（幂等）

特殊动作的处理： 如果一个操作难以映射到标准 CRUD，可以使用子资源或动词后缀：

• ✅ POST /users/123/suspend (封禁用户)
• ✅ POST /articles/456/publish (发布文章)

3. HTTP 状态码规范

必须返回标准的 HTTP 状态码，避免所有请求都返回 200 OK 并在 Body 中包含错误码。

成功响应：

• 200 OK：GET 成功，PUT/PATCH 成功，DELETE 成功
• 201 Created：POST 创建成功
• 204 No Content：操作成功但无内容返回（常用于 DELETE）

客户端错误：

• 400 Bad Request：参数校验失败、格式错误
• 401 Unauthorized：未登录或 Token 失效
• 403 Forbidden：已登录但无权限访问该资源
• 404 Not Found：资源不存在
• 409 Conflict：资源状态冲突（如重复创建）
• 429 Too Many Requests：触发限流

服务端错误：

• 500 Internal Server Error：服务器内部异常
• 502 Bad Gateway：网关或上游服务异常
• 503 Service Unavailable：服务不可用（如维护中）

4. 统一的响应结构与文档模板 (Response Format & Documentation Template)

所有 API（特别是发生错误时）应保持统一的 JSON 结构。在编写 API 文档或系统设计文档时，请严格遵循以下模板化格式，不要随意发明数据结构。规范需明确数据类型、是否必填以及字段含义：

标准文档模板：

// Request
Schema: [协议，如 HTTP / HTTPS / RPC]
Path: [API 路径，如 /api/v1/resource]
Method: [如 GET / POST / PUT / DELETE 等]
Headers: (可选，如需特殊 Header 时填入)
    [Header 键]: [Header 值说明]
Query: (Method 为 GET 或需要 URL 参数时填入)
    [参数名] [数据类型] // [是否必填, 如 Required/Optional] [参数说明]
Body: (Method 为 POST/PUT/PATCH 等时填入，使用类 JSON 格式)
{
    "字段名": [数据类型] // [是否必填, 如 Required/Optional]  [字段说明]
}

// Response
Status Code: [HTTP 状态码，如 200]
Body:
{
    "code": [数据类型], // [业务状态码说明，0 表示成功]
    "msg": [数据类型],  // [提示信息说明，如 "success"]
    "data": {          // [核心返回数据]
        // [返回的 JSON 结构，并使用注释标注字段名和数据类型]
    },
    "trace_id": String // [链路追踪 ID]
}

完整示例：

// Request
Schema: HTTPS
Path: /api/v1/articles
Method: POST
Body:
{
    "title": String,   // (Required) 文章标题
    "content": String  // (Required) 文章内容
}

// Response
Status Code: 200
Body:
{
    "code": Integer,        // 业务状态码，0 表示成功
    "msg": String,          // 提示信息，如 "success"
    "data": {
        "article_id": Integer // 新创建的文章 ID
    },
    "trace_id": "req-xyz-789"
}

--------------------------------------------------

// Request
Schema: HTTPS
Path: /api/v1/articles
Method: GET
Query:
    page    Integer  // (Optional) 页码，从 1 开始，默认 1
    size    Integer  // (Optional) 每页数量，默认 20

// Response
Status Code: 200
Body:
{
    "code": Integer,
    "msg": String,
    "data": {
        "total": Integer,          // 总记录数
        "list": [                  // 文章列表
            {
                "article_id": Integer,
                "title": String 
            }
        ]
    },
    "trace_id": "req-xyz-789"
}

5. 分页、过滤与排序 (Pagination, Filtering & Sorting)

分页 (Pagination)： 优先使用 page 和 page_size（或 limit 和 offset）。

• ✅ GET /users?page=1&page_size=20

返回结构应包含分页元数据：

{
  "data": {
    "list": [...],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}

过滤 (Filtering)： 使用查询参数进行精确匹配。

• ✅ GET /users?status=active&role=admin

排序 (Sorting)： 使用 sort 或 order_by 参数，前缀 - 表示降序。

• ✅ GET /users?sort=-created_at,name (按创建时间降序，名称升序)

6. 版本控制 (Versioning)

API 必须包含版本号，建议在 URL 路径中体现大版本。

• ✅ GET /api/v1/users
• ✅ GET /api/v2/users

AI 交互指导

当 AI 协助生成 API 接口代码（如 go-zero 的 .api 文件或 Controller 层代码）时，必须：

1. 检查路由命名是否符合复数名词、kebab-case 规范。
2. 检查 HTTP 方法是否语义正确。
3. 确保请求参数和响应体结构符合团队规范（特别是分页接口）。
4. 如果用户提供的设计不符合 RESTful 规范，AI 应主动指出并提供规范的修改建议。