# API Design Guidelines

> 后端 RESTful API 设计规范与最佳实践。当用户需要设计新接口、重构现有接口、编写 API 文档，或询问如何设计符合 RESTful 标准的路由、状态码、分页、过滤和版本控制时使用此 skill。

- Skill: `migoxlab/api-design-guidelines` (Agent Skill)
- Install (CLI): `npx skillmds@latest add migoxlab/api-design-guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/migoxlab/api-design-guidelines/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: migoxlab (https://skillmd.com/u/migoxlab)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/migoxlab/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 文档或系统设计文档时，请严格遵循以下模板化格式，不要随意发明数据结构。规范需明确数据类型、是否必填以及字段含义：

**标准文档模板：**
```text
// 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]
}
```

**完整示例：**

```text
// 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`

返回结构应包含分页元数据：
```json
{
  "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 应主动指出并提供规范的修改建议。