REST

Representational State Transfer

REST 是一种基于 HTTP 语义的 API 设计风格——把系统抽象为资源，用 URL 定位资源、用 HTTP 方法表示操作、用 HTTP 状态码表示结果。是公开 API 的默认选择，生态和基础设施最成熟。

REST 的五个层次

Leonard Richardson 提出的成熟度模型（RMM）：

资源与 URL

核心思想：URL 是名词（资源），HTTP 方法是动词。

✅ GET    /users              获取用户列表
✅ GET    /users/1            获取单个用户
✅ POST   /users              创建用户
✅ PUT    /users/1            整体替换用户
✅ PATCH  /users/1            局部更新
✅ DELETE /users/1            删除用户
✅ GET    /users/1/orders     用户的订单（嵌套资源）

❌ GET  /getUserList          动词塞 URL
❌ POST /deleteUser?id=1      POST 当万能方法

HTTP 方法的语义

状态码的常见用法

用有语义的状态码，让代理、监控、客户端能正确理解响应。

分页、排序、过滤

URL 的 query string 是事实标准。

GET /users?page=2&pageSize=20                 分页
GET /users?sort=-createdAt                    排序（前缀 - 表示降序）
GET /users?filter[status]=active              过滤
GET /users?fields=id,name                     字段筛选（可选）
GET /users?cursor=xxx&limit=20                游标分页（大数据集）

缓存

REST 的核心优势，GraphQL / tRPC / gRPC 都没有的能力。

客户端 / CDN 缓存

Cache-Control: public, max-age=3600           共享缓存可存 1 小时
Cache-Control: private, max-age=60            仅浏览器缓存
Cache-Control: no-store                       禁止任何缓存

条件请求（ETag / Last-Modified）

响应：
  ETag: "abc123"
  Last-Modified: Sat, 12 Apr 2025 10:00:00 GMT

下次请求：
  If-None-Match: "abc123"
  If-Modified-Since: Sat, 12 Apr 2025 10:00:00 GMT

→ 未变化时服务端返回 304 Not Modified（无响应体，省带宽）

类型安全：OpenAPI

REST 本身没有类型系统，需要用 OpenAPI（Swagger）弥补。

paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      required: [id, name]
      properties:
        id: { type: string }
        name: { type: string }
        email: { type: string, format: email }

基于 OpenAPI Schema 可以：

• codegen：openapi-typescript / openapi-generator 生成前后端类型
• 文档：Swagger UI / Redoc 自动渲染交互式 API 文档
• 校验：ajv 等库运行时校验请求 / 响应

CORS

浏览器对跨源请求有同源策略，REST 作为公开 API 必须配置 CORS 才能被第三方 Web 客户端调用。

错误响应建议

统一错误结构方便客户端处理。RFC 7807 的 Problem Details 是常见选择：

{
  "type": "https://example.com/errors/insufficient-balance",
  "title": "Insufficient balance",
  "status": 422,
  "detail": "Your balance is 10 but 50 is required.",
  "instance": "/orders/9"
}

自研格式至少包含：HTTP 状态码（在响应头里）、业务 code（可选）、message、traceId（方便排查）。

与其他方案的对比

详细对比见：

• REST vs GraphQL
• REST vs tRPC（tRPC 特点部分）
• REST vs gRPC

选型概览：

最小示例（Node.js + Express）

import express from "express";

const app = express();
app.use(express.json());

const users = new Map();

app.get("/users", (req, res) => {
  res.json([...users.values()]);
});

app.get("/users/:id", (req, res) => {
  const user = users.get(req.params.id);
  if (!user) return res.status(404).json({ error: "User not found" });
  res.json(user);
});

app.post("/users", (req, res) => {
  const id = crypto.randomUUID();
  const user = { id, ...req.body };
  users.set(id, user);
  res.status(201).location(`/users/${id}`).json(user);
});

app.delete("/users/:id", (req, res) => {
  if (!users.delete(req.params.id)) {
    return res.status(404).json({ error: "User not found" });
  }
  res.status(204).end();
});

app.listen(3000);

回到 API 通信总览