Post Title

一个好的 API 设计能让前后端协作如丝般顺滑，而一个糟糕的 API 设计则是所有开发者的噩梦。这篇文章整理 RESTful API 设计的最佳实践。

一、URL 命名规范

# 好的设计
GET    /api/v1/users          # 获取用户列表
GET    /api/v1/users/123      # 获取单个用户
POST   /api/v1/users          # 创建用户
PUT    /api/v1/users/123      # 更新用户
DELETE /api/v1/users/123      # 删除用户

# 子资源
GET    /api/v1/users/123/orders      # 用户的订单
GET    /api/v1/users/123/orders/456  # 用户的某个订单

# 不好的设计（不要这样写）
GET /api/v1/getUsers
POST /api/v1/createUser
GET /api/v1/user?id=123

命名规则

用复数名词：/users 而不是 /user
用横线分隔：/user-profiles 而不是 /userProfiles
层级不超过3层
不用动词，用 HTTP 方法表达动作

二、HTTP 状态码

# 成功
200 OK              # 请求成功
201 Created         # 创建成功
204 No Content      # 删除成功（无返回内容）

# 客户端错误
400 Bad Request     # 请求参数错误
401 Unauthorized    # 未认证
403 Forbidden       # 无权限
404 Not Found       # 资源不存在
422 Unprocessable Entity  # 参数验证失败

# 服务端错误
500 Internal Server Error  # 服务器内部错误
502 Bad Gateway            # 网关错误
503 Service Unavailable    # 服务不可用

三、分页、排序和过滤

# 分页
GET /api/v1/users?page=1&page_size=20

# 排序
GET /api/v1/users?sort=-created_at  # 降序
GET /api/v1/users?sort=name         # 升序

# 过滤
GET /api/v1/users?status=active
GET /api/v1/users?age__gte=18&age__lte=30

# 搜索
GET /api/v1/users?q=小明

四、统一响应格式

// 成功响应
{
    "code": 0,
    "message": "success",
    "data": {
        "id": 123,
        "name": "小明"
    }
}

// 列表响应
{
    "code": 0,
    "message": "success",
    "data": {
        "items": [...],
        "total": 100,
        "page": 1,
        "page_size": 20
    }
}

// 错误响应
{
    "code": 40001,
    "message": "用户名不能为空",
    "details": [
        {"field": "username", "reason": "required"}
    ]
}

五、版本管理

URL 路径版本：/api/v1/users（推荐）
请求头版本：Accept: application/vnd.api.v1+json
查询参数版本：/api/users?version=1（不推荐）

六、认证和安全

用 JWT Token，通过 Authorization: Bearer <token> 传递
接口强制 HTTPS
做好频率限制（Rate Limiting）
敏感数据加密存储
输入校验永远不要信任客户端数据

七、API 文档

好的 API 必须有好的文档。推荐工具：

Swagger / OpenAPI：业界标准
Postman：团队协作方便
Apifox：国产利器，集文档、测试、Mock 于一体

记住一个原则：API 是给开发者用的产品，不是给自己看的代码。站在使用者的角度去设计。