RESTful API 设计指南：从规范到实战

REST 核心原则

REST 不是协议，而是一种架构风格。遵循这些原则，让你的 API 更优雅、更易用。

URL 设计规范

使用名词，不用动词

# ✅ 好
GET /users
POST /users
GET /users/123
PUT /users/123
DELETE /users/123

# ❌ 差
GET /getUsers
POST /createUser
POST /deleteUser

使用复数名词

# ✅ 统一使用复数
GET /articles
GET /articles/456/comments

# ❌ 避免混用
GET /article
GET /articles

资源嵌套要适度

# ✅ 合理嵌套（最多 2 层）
GET /users/123/orders

# ❌ 过度嵌套
GET /users/123/orders/456/items/789/details

HTTP 方法语义

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

状态码正确使用

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

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

500 Internal Server Error # 服务器错误
503 Service Unavailable   # 服务不可用

响应格式规范

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

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

分页设计

# 推荐：基于游标的分页
GET /articles?cursor=abc123&limit=20

# 或：页码分页
GET /articles?page=2&pageSize=20

# 响应包含分页信息
{
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 2,
    "pageSize": 20,
    "hasMore": true
  }
}

版本控制

# URL 路径版本（推荐）
GET /api/v1/users

# 或：Header 版本
Accept: application/vnd.myapi.v1+json

实战建议

1. 统一响应格式：成功、错误结构一致
2. 完善的错误信息：帮助调用者快速定位问题
3. 合理的限流：保护服务稳定
4. 详细的文档：Swagger/OpenAPI

结语

好的 API 设计让前后端协作更顺畅。遵循规范，从第一个接口开始！