API是现代软件系统的血管，连接着各个组件和服务。一个设计良好的API能让开发者事半功倍，而一个糟糕的API则会成为永恒的噩梦。RESTful API是目前最流行的Web API设计风格，它基于HTTP协议，简洁、清晰、易于理解。在这篇文章中，我将详细介绍RESTful API的设计规范和最佳实践。

REST原则

REST（Representational State Transfer）是一种架构风格，它定义了一组约束条件和原则。RESTful API遵循这些原则：

• 客户端-服务器分离：关注点分离，提高可移植性
• 无状态：每个请求包含所有必要信息，服务器不保存会话状态
• 可缓存：响应应该明确标识是否可缓存
• 统一接口：使用标准方法、资源标识、标准表示
• 分层系统：客户端不需要知道连接的是终端服务器还是中间层

资源命名规范

使用名词而非动词

/* 正确：使用名词 */
GET    /users        # 获取用户列表
GET    /users/123    # 获取指定用户
POST   /users        # 创建用户
PUT    /users/123    # 更新指定用户
DELETE /users/123    # 删除指定用户

/* 错误：使用动词 */
GET    /getUsers
POST   /createUser
DELETE /deleteUser/123

使用复数形式

/* 正确 */
/users
/products
/orders

/* 不推荐 */
/user
/product
/order

表达层级关系

/* 用户下的订单 */
GET /users/123/orders       # 用户123的所有订单
GET /users/123/orders/456   # 用户123的订单456

/* 避免过深的嵌套，超过2-3层考虑重构 */
/* 不推荐 */
/users/123/orders/456/items/789/variants

使用小写和连字符

/* 正确 */
/user-profiles
/order-items

/* 错误 */
/userProfiles
/user_profiles
/OrderItems

HTTP方法

方法	操作	是否幂等	是否安全
GET	读取资源	是	是
POST	创建资源	否	否
PUT	完整更新	是	否
PATCH	部分更新	否	否
DELETE	删除资源	是	否

/* 创建资源 */
POST /users
Content-Type: application/json

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

/* 完整更新 */
PUT /users/123
Content-Type: application/json

{
  "name": "John Smith",
  "email": "john.smith@example.com"
}

/* 部分更新 */
PATCH /users/123
Content-Type: application/json

{
  "name": "John Smith"
}

状态码

正确使用HTTP状态码让API更加语义化：

成功响应（2xx）

• 200 OK：请求成功（GET、PUT、PATCH）
• 201 Created：资源创建成功（POST）
• 204 No Content：成功但无返回内容（DELETE）

客户端错误（4xx）

• 400 Bad Request：请求格式错误
• 401 Unauthorized：未认证
• 403 Forbidden：已认证但无权限
• 404 Not Found：资源不存在
• 409 Conflict：资源冲突（如重复创建）
• 422 Unprocessable Entity：语义错误
• 429 Too Many Requests：请求过于频繁

服务器错误（5xx）

• 500 Internal Server Error：服务器内部错误
• 503 Service Unavailable：服务不可用

响应格式

成功响应

{
  "data": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com",
    "created_at": "2026-03-05T10:00:00Z"
  }
}

列表响应

{
  "data": [
    { "id": 1, "name": "User 1" },
    { "id": 2, "name": "User 2" }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20,
    "total_pages": 5
  }
}

错误响应

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

版本控制

URL版本

/* 最常用 */
GET /api/v1/users
GET /api/v2/users

Header版本

GET /api/users
Accept: application/vnd.myapi.v2+json

查询参数版本

GET /api/users?version=2

推荐使用URL版本，更直观，便于调试和缓存。

分页、过滤、排序

分页

/* 偏移分页 */
GET /users?page=2&per_page=20

/* 游标分页（适合大数据量） */
GET /users?cursor=abc123&limit=20

过滤

/* 简单过滤 */
GET /users?status=active
GET /users?role=admin

/* 范围过滤 */
GET /users?created_after=2026-01-01
GET /products?price_min=100&price_max=500

/* 搜索 */
GET /users?q=john

排序

/* 单字段排序 */
GET /users?sort=created_at
GET /users?sort=-created_at  /* 降序 */

/* 多字段排序 */
GET /users?sort=-created_at,name

字段选择

/* 只返回指定字段 */
GET /users?fields=id,name,email

安全性

认证

/* Bearer Token */
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

/* API Key */
X-API-Key: your-api-key

HTTPS

所有API必须使用HTTPS，保护数据传输安全。

速率限制

/* 响应头 */
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1617283200

文档

API文档是开发者体验的重要组成部分。推荐使用OpenAPI（Swagger）规范：

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'

总结

RESTful API设计不仅仅是技术实现，更是一种艺术。遵循这些规范和最佳实践，你能设计出清晰、一致、易用的API，为开发者带来良好的体验。

记住，好的API设计需要在标准化和灵活性之间找到平衡。在实际项目中，根据团队和业务需求进行适当调整，保持一致性是最重要的。