API 设计最佳实践：RESTful 风格详解

好的 API 设计让前后端协作更顺畅。本文详解 RESTful API 设计的核心原则。

资源命名规范

✅ 正确做法

GET    /users          # 获取用户列表
GET    /users/123      # 获取单个用户
POST   /users          # 创建用户
PUT    /users/123      # 更新用户（全量）
PATCH  /users/123      # 更新用户（部分）
DELETE /users/123      # 删除用户

❌ 错误做法

GET    /getUsers       # 动词不应该出现在 URL 中
POST   /createUser     # 同上
DELETE /deleteUser/123 # 同上

原则：URL 表示资源，HTTP 方法表示操作。

状态码使用

状态码	含义	使用场景
200	OK	成功获取/更新
201	Created	资源创建成功
204	No Content	删除成功，无返回体
400	Bad Request	请求参数错误
401	Unauthorized	未认证
403	Forbidden	无权限
404	Not Found	资源不存在
409	Conflict	资源冲突（如重复）
422	Unprocessable	数据验证失败
429	Too Many Requests	频率限制
500	Internal Error	服务器错误

响应格式统一

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "张三"
  }
}

错误响应

{
  "code": 40001,
  "message": "参数验证失败",
  "errors": [
    {"field": "email", "message": "邮箱格式不正确"}
  ]
}

分页设计

方案 1：Offset-Limit（简单）

GET /users?page=2&limit=20

方案 2：Cursor（推荐，适合大数据）

GET /users?cursor=eyJpZCI6MTIzfQ&limit=20

# 响应包含 next_cursor
{
  "data": [...],
  "next_cursor": "eyJpZCI6MTQzfQ",
  "has_more": true
}

过滤、排序、字段选择

# 过滤
GET /users?status=active&role=admin

# 排序
GET /users?sort=-created_at  # 负号表示降序

# 字段选择
GET /users?fields=id,name,email

# 组合
GET /users?status=active&sort=-created_at&fields=id,name

版本控制

方案 1：URL 路径（推荐）

/api/v1/users
/api/v2/users

方案 2：请求头

Accept: application/vnd.myapi.v1+json

认证方式

JWT Token（推荐）

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API Key（服务间调用）

X-API-Key: your_api_key_here

速率限制

# 响应头告知限制
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1647360000

文档化

• 使用 OpenAPI/Swagger 规范
• 保持文档与代码同步
• 提供示例请求和响应

总结

好的 API 设计原则：

1. 资源命名清晰
2. 状态码准确
3. 响应格式统一
4. 支持分页过滤
5. 版本控制
6. 完善文档

API 是产品，不是内部实现。