RESTful API 设计规范：打造优雅的接口

什么是 RESTful？

REST（Representational State Transfer）是一种架构风格，强调资源导向和无状态通信。遵循 REST 规范的 API 更易理解、维护和扩展。

一、核心原则

1. 资源导向

URL 应该表示资源，而非动作：

❌ 错误设计：

GET /getUsers
POST /createUser
PUT /updateUser/123
DELETE /deleteUser/123

✅ 正确设计：

GET /users
POST /users
PUT /users/123
DELETE /users/123

2. 使用 HTTP 方法表达操作

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

3. 无状态

每个请求包含所有必要信息，服务器不保存会话状态。

二、URL 设计规范

使用名词复数

GET /articles       # 获取文章列表
GET /articles/123   # 获取单篇文章

嵌套资源表示关系

GET /users/123/articles      # 用户的所有文章
GET /users/123/articles/456  # 用户的特定文章

过滤、排序、分页

# 过滤
GET /articles?status=published
GET /articles?author=123&status=published

# 排序
GET /articles?sort=-created_at  # 降序
GET /articles?sort=created_at   # 升序

# 分页
GET /articles?page=2&limit=20

# 字段选择
GET /articles?fields=id,title,created_at

三、状态码规范使用

成功响应

状态码	含义	场景
200 OK	成功	GET、PUT、PATCH
201 Created	已创建	POST 成功
204 No Content	无内容	DELETE 成功

客户端错误

状态码	含义	场景
400 Bad Request	请求错误	参数验证失败
401 Unauthorized	未授权	未登录
403 Forbidden	禁止访问	权限不足
404 Not Found	资源不存在	URL 错误
409 Conflict	冲突	资源已存在
422 Unprocessable Entity	语义错误	数据验证失败
429 Too Many Requests	请求过多	触发限流

服务端错误

状态码	含义
500 Internal Server Error	服务器内部错误
502 Bad Gateway	网关错误
503 Service Unavailable	服务不可用

四、响应格式规范

成功响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 123,
    "title": "文章标题",
    "content": "文章内容",
    "created_at": "2026-03-20T10:00:00Z"
  }
}

列表响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "total_pages": 5
    }
  }
}

错误响应

{
  "code": 40001,
  "msg": "参数验证失败",
  "errors": [
    {
      "field": "email",
      "message": "邮箱格式不正确"
    },
    {
      "field": "password",
      "message": "密码长度至少 8 位"
    }
  ]
}

五、版本控制

URL 版本化（推荐）

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

请求头版本化

GET /users
Accept: application/vnd.myapi.v1+json

六、安全最佳实践

1. 始终使用 HTTPS

server {
    listen 443 ssl;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
}

2. 认证机制

• JWT Token：适合无状态 API
• OAuth 2.0：适合第三方授权
• API Key：适合服务间调用

3. 速率限制

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1679313600

4. 输入验证

// 使用验证库
const schema = Joi.object({
  email: Joi.string().email().required(),
  password: Joi.string().min(8).required()
});

七、文档化

使用 OpenAPI/Swagger

openapi: 3.0.0
info:
  title: 博客 API
  version: 1.0.0
paths:
  /articles:
    get:
      summary: 获取文章列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: 成功

总结

优秀的 RESTful API 设计：

• ✅ 资源导向的 URL
• ✅ 正确的 HTTP 方法
• ✅ 规范的状态码
• ✅ 一致的响应格式
• ✅ 完善的文档
• ✅ 严格的安全措施

记住：好的 API 是产品，不是副产品！