RESTful API 设计指南：打造优雅的接口

好的 API 设计让前端开发事半功倍。本文分享 RESTful API 设计的核心原则和最佳实践。

REST 核心原则

1. 资源导向

API 围绕资源设计，而非动作：

✅ GET    /users          # 获取用户列表
✅ GET    /users/123      # 获取单个用户
✅ POST   /users          # 创建用户
✅ PUT    /users/123      # 更新用户
✅ DELETE /users/123      # 删除用户

❌ GET    /getUsers
❌ POST   /createUser
❌ POST   /deleteUser

2. 使用 HTTP 方法语义

• GET: 读取（幂等）
• POST: 创建
• PUT: 全量更新（幂等）
• PATCH: 部分更新
• DELETE: 删除（幂等）

3. 正确的状态码

200 OK          # 成功
201 Created     # 创建成功
204 No Content  # 删除成功（无返回体）
400 Bad Request # 请求参数错误
401 Unauthorized # 未认证
403 Forbidden   # 无权限
404 Not Found   # 资源不存在
409 Conflict    # 资源冲突
422 Unprocessable Entity # 验证失败
429 Too Many Requests # 请求过多
500 Internal Server Error # 服务器错误

URL 设计规范

使用复数名词

✅ /users
✅ /articles
❌ /user
❌ /article

小写字母 + 连字符

✅ /user-profiles
✅ /order-items
❌ /userProfiles
❌ /UserProfiles

嵌套资源表示从属关系

GET /users/123/orders      # 用户 123 的订单
GET /orders/456/items      # 订单 456 的商品

查询参数

分页

GET /users?page=2&limit=20
GET /users?offset=40&limit=20

排序

GET /users?sort=created_at&order=desc
GET /users?sort=-created_at  # - 表示降序

过滤

GET /users?status=active&role=admin
GET /products?price_min=100&price_max=500

字段选择

GET /users/123?fields=id,name,email

响应格式

统一结构

{
  "success": true,
  "data": { ... },
  "message": "操作成功",
  "timestamp": 1711516800000
}

错误响应

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "参数验证失败",
    "details": [
      { "field": "email", "message": "邮箱格式不正确" }
    ]
  }
}

列表响应

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 156,
    "totalPages": 8
  }
}

版本控制

URL 版本（推荐）

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

Header 版本

Accept: application/vnd.myapi.v1+json

安全考虑

1. 始终使用 HTTPS
2. 认证授权：JWT、OAuth 2.0
3. 速率限制：防止滥用
4. 输入验证：防止注入攻击
5. 敏感数据脱敏：密码、token 不返回

文档

用 OpenAPI/Swagger 自动生成文档：

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

结语

好的 API 设计是自文档化的。遵循这些原则，你的 API 会让开发者爱不释手。

---

你设计过最满意的 API 是什么样的？