RESTful API 设计规范：从入门到最佳实践

什么是 RESTful？

REST (Representational State Transfer) 是一种 API 设计风格，核心是资源导向。

核心原则

1. 资源命名

# ✅ 好：用名词，复数形式
GET /users
GET /users/123
GET /users/123/posts

# ❌ 坏：用动词
GET /getUsers
POST /createUser

2. HTTP 方法

方法	用途	幂等
GET	获取资源	是
POST	创建资源	否
PUT	全量更新	是
PATCH	部分更新	是
DELETE	删除资源	是

3. 状态码

# 2xx 成功
200 OK          # 成功
201 Created     # 创建成功
204 No Content  # 成功但无返回

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

# 5xx 服务端错误
500 Internal Error   # 服务器错误
503 Service Unavailable # 服务不可用

请求响应设计

请求示例

# 创建用户
POST /users
Content-Type: application/json

{
  "name": "John",
  "email": "john@example.com",
  "age": 25
}

响应格式

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "John",
    "email": "john@example.com"
  },
  "timestamp": 1711094400
}

错误响应

{
  "code": 40001,
  "message": "邮箱格式不正确",
  "errors": [
    {
      "field": "email",
      "message": "必须是有效的邮箱地址"
    }
  ]
}

分页设计

方案 1: Offset-Based

GET /users?page=1&pageSize=20

# 响应
{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 100,
    "totalPages": 5
  }
}

方案 2: Cursor-Based (推荐)

GET /users?cursor=abc123&limit=20

# 响应
{
  "data": [...],
  "nextCursor": "def456",
  "hasMore": true
}

Cursor 分页更适合大数据量和高并发场景。

过滤与排序

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

# 范围
GET /users?age[gte]=18&age[lte]=60

# 搜索
GET /users?q=john

# 排序
GET /users?sort=-createdAt,name
# - 表示降序，无符号表示升序

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

版本控制

# URL 路径 (推荐)
GET /api/v1/users
GET /api/v2/users

# 请求头
GET /users
Accept: application/vnd.myapi.v1+json

安全最佳实践

1. 认证

# Bearer Token
Authorization: Bearer <token>

# API Key (服务端间调用)
X-API-Key: <key>

2. 限流

# 响应头告知限流信息
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1711094400

3. CORS

add_header Access-Control-Allow-Origin "https://yourdomain.com";
add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE";
add_header Access-Control-Allow-Headers "Content-Type, Authorization";

文档化

使用 OpenAPI/Swagger:

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        200:
          description: 成功

结语

好的 API 设计让前端开发更高效，后端维护更轻松。遵循规范、保持一致、文档完善，才能构建优秀的 API！

#API #RESTful #后端开发 #接口设计 #最佳实践