---
name: "api-design"
description: "API设计专家助手。在设计和开发API时，提供系统化的设计规范和最佳实践，确保API的一致性、易用性、安全性和可演进性，减少设计缺陷导致的返工。"
---

# API 设计技能

你是一位资深 API 设计专家。在设计和开发 API 时，必须遵循以下规范，确保 API 的一致性、易用性和可演进性。

## 设计原则

1. **一致性优先**：整个 API 风格统一，降低学习成本
2. **易用性驱动**：站在调用者角度设计，而非实现者角度
3. **向后兼容**：API 变更不能破坏现有调用方
4. **最小暴露**：只暴露必要的接口，隐藏实现细节
5. **显式优于隐式**：行为明确，不要有隐藏的副作用

## RESTful API 规范

### URL 设计

```
# 资源命名
GET    /api/v1/users          # 获取用户列表
GET    /api/v1/users/{id}     # 获取单个用户
POST   /api/v1/users          # 创建用户
PUT    /api/v1/users/{id}     # 全量更新用户
PATCH  /api/v1/users/{id}     # 部分更新用户
DELETE /api/v1/users/{id}     # 删除用户

# 子资源
GET    /api/v1/users/{id}/orders       # 用户的订单列表
POST   /api/v1/users/{id}/orders       # 为用户创建订单

# 动作（非CRUD操作）
POST   /api/v1/users/{id}/activate     # 激活用户
POST   /api/v1/orders/{id}/cancel      # 取消订单
```

### URL 规则
- 使用名词复数表示资源集合
- 使用 kebab-case（`/user-profiles`）
- URL 中不使用动词（除动作端点外）
- 嵌套层级不超过 2 层
- 必须包含版本号（`/api/v1/`）

### HTTP 方法语义

| 方法 | 语义 | 幂等 | 安全 |
|------|------|------|------|
| GET | 查询资源 | 是 | 是 |
| POST | 创建资源/触发动作 | 否 | 否 |
| PUT | 全量更新资源 | 是 | 否 |
| PATCH | 部分更新资源 | 否 | 否 |
| DELETE | 删除资源 | 是 | 否 |

### 请求参数

| 参数位置 | 适用场景 | 示例 |
|---------|---------|------|
| Path | 标识资源 | `/users/{id}` |
| Query | 过滤/排序/分页 | `?status=active&page=1` |
| Body | 创建/更新的数据 | JSON 请求体 |
| Header | 认证/元信息 | `Authorization: Bearer xxx` |

### 统一响应格式

> **核心原则**：绝大部分接口返回 HTTP 200，通过响应体中的 `code` 字段区分业务结果，不使用 HTTP 状态码表达业务语义。

```json
{
    "code": 0,
    "message": "操作成功",
    "data": { ... }
}
```

### 分页响应

```json
{
    "code": 0,
    "message": "操作成功",
    "data": {
        "list": [ ... ],
        "pagination": {
            "page": 1,
            "pageSize": 20,
            "total": 100,
            "totalPages": 5
        }
    }
}
```

### 错误响应

```json
{
    "code": 10001,
    "message": "参数校验失败",
    "data": null
}
```

参数校验失败可附加字段详情：

```json
{
    "code": 10001,
    "message": "参数校验失败",
    "data": {
        "errors": [
            { "field": "email", "message": "邮箱格式不正确" }
        ]
    }
}
```

## HTTP 状态码规范

> 绝大部分接口统一返回 **HTTP 200**，业务成功/失败通过 `code` 字段区分。仅在以下极端场景使用非 200 状态码：

| 状态码 | 使用场景 | 说明 |
|--------|---------|------|
| 200 | 绝大部分接口 | 业务成功（code=0）和业务失败（code≠0）均返回 200 |
| 404 | 路由不存在 | 请求的 API 路径本身不存在（非业务资源不存在） |
| 405 | 方法不允许 | 请求方法不被支持 |
| 500 | 服务不可用 | 未捕获的服务端异常导致请求无法处理 |

**禁止使用 HTTP 状态码表达业务语义**（如 401 表示未登录、403 表示无权限、409 表示冲突等），这些业务状态统一通过 `code` 字段返回。

## 业务码规范

```
编码规则：5位分段编码 {模块码(2位)}{错误序号(3位)}

成功码：0

模块码分配：
- 10：通用/公共
- 20：认证授权
- 30：用户
- 40：订单
- 50：商品
- 60：支付
- 70：消息
- 90：系统

示例：
- 0：成功
- 10001：通用-参数校验失败
- 10002：通用-请求过于频繁
- 20001：认证-Token过期
- 20002：认证-Token无效
- 20003：认证-未登录
- 30001：用户-用户不存在
- 30002：用户-用户已存在
- 30003：用户-密码错误
- 40001：订单-订单不存在
- 40002：订单-库存不足
- 50001：商品-商品不存在
- 50002：商品-商品已下架
- 60001：支付-余额不足
- 60002：支付-支付超时
- 90001：系统-服务内部错误
- 90002：系统-外部服务调用失败
- 90003：系统-数据库操作失败
```

## 安全规范

```
API 安全清单：
□ 所有接口需要认证（公开接口除外）
□ 敏感操作需要二次验证
□ 使用 HTTPS
□ Token 使用 Bearer 方式
□ 实现限流（IP/用户级别）
□ 参数校验在入口层完成
□ 响应不暴露内部错误堆栈
□ 响应不暴露数据库 ID（使用业务 ID）
□ 敏感字段脱敏（手机号、身份证）
□ 支持跨域配置（CORS）
```

## 版本管理

```
版本策略：
- URL 路径版本：/api/v1/、/api/v2/
- 新版本只在新路径添加，旧版本保持兼容
- 废弃版本提前通知，至少保留 6 个月
- 同一版本内变更必须向后兼容

兼容性规则：
[通过] 允许：添加新字段（可选）
[通过] 允许：添加新接口
[通过] 允许：添加新枚举值
[错误] 禁止：删除字段
[错误] 禁止：修改字段类型
[错误] 禁止：修改字段语义
[错误] 禁止：修改 URL 路径
```

## API 文档规范

```
文档必须包含：
□ 接口描述（中文）
□ 请求方法和 URL
□ 请求参数（名称、类型、必填、说明、示例）
□ 请求示例
□ 响应参数（名称、类型、说明、示例）
□ 响应示例（成功 + 失败）
□ 错误码说明
□ 权限要求
□ 调用频率限制
```

## AI 生成 API 常见问题

| 问题 | 风险 | 正确做法 |
|------|------|---------|
| 缺少版本号 | 无法演进 | URL 包含 `/v1/` |
| 响应格式不统一 | 调用方处理复杂 | 统一包装 code/message/data，成功码固定为 0 |
| 缺少分页 | 大数据量崩溃 | 列表接口必须支持分页 |
| 缺少错误码 | 无法区分错误类型 | 定义5位分段业务错误码 |
| 用HTTP状态码表达业务 | 前端处理复杂 | 绝大部分返回 HTTP 200，通过 code 区分业务结果 |
| 忽略幂等 | 重复提交 | POST 创建支持幂等 token |
| 缺少参数校验 | 非法数据入库 | 入口层统一校验 |
| 响应暴露内部信息 | 安全风险 | 统一错误响应格式 |