RESTful API 设计

是什么，为什么存在

REST（Representational State Transfer，表述性状态转移）是一种网络应用架构风格，不是 JSON 格式、路由命名规范或特定框架。RESTful API 将可寻址的领域对象或能力建模为 资源（resource） ，客户端与服务端通过统一接口交换资源的 表示（representation） 。一个订单是资源，订单列表也是资源；JSON 只是它们可能采用的一种表示。

这种设计解决的是客户端与服务端之间的长期协作问题。HTTP 已经定义了方法、状态码、缓存、内容协商和条件请求的通用语义；API 若复用这些语义，客户端、代理和监控工具就不必为每个端点重新猜测协议。好的资源模型还把公开契约与数据库表、控制器名称和内部工作流分开。

你会在浏览器应用、移动客户端、合作伙伴集成和服务间 HTTP 接口中遇到 RESTful API。它适合以资源读取和状态转换为主、需要利用 HTTP 基础设施的系统。若领域主要是低延迟远程调用、双向流或严格类型化命令，gRPC 或其他 RPC 形式可能更直接；选择 REST 不意味着所有系统都必须采用它。

严格的 REST 还要求统一接口包含超媒体驱动的状态转换。工程实践常把「使用资源 URI、HTTP 方法和状态码的 JSON API」也称为 RESTful，即使客户端仍预先知道全部路由。评审时应说明团队采用了哪些约束，不要让一个标签代替可测试的契约。

工作原理

REST 把客户端、服务端和中间组件放进同一个交互模型。客户端发送一条自描述请求，服务端返回资源表示或结果状态；请求之间不依赖服务端保存的会话上下文。认证凭据、目标资源、前置条件和处理请求所需的其他上下文必须随请求传递，但服务端当然仍会保存资源、授权策略和业务数据。

六项架构约束

REST 的约束共同决定系统行为，而不是一份路由风格清单：

1. 客户端与服务端分离，各自可以在公开接口不变时独立演进。
2. 请求无状态，每条请求都携带服务端理解它所需的上下文。
3. 响应明确是否可缓存，使客户端和中间缓存能够安全复用表示。
4. 统一接口通过资源标识、表示、自描述消息和超媒体约束交互方式。
5. 分层系统允许代理、网关和缓存位于客户端与源服务之间，而客户端无需了解每一层。
6. 按需代码允许服务端可选地传输可执行代码来扩展客户端，这不是普通 JSON API 的必备能力。

无状态不等于「服务端没有状态」，也不禁止登录。它要求每次请求都能独立解释，例如携带会话令牌，而不是依赖某台实例记住此前请求的隐含步骤。这样负载均衡器才能把后续请求交给另一台实例，但令牌本身仍要经过认证、授权和过期检查。

资源、URI 与方法

URI 标识资源，HTTP 方法表达对该资源的操作。集合和成员通常形成 /orders 与 /orders/{orderId} 这样的关系；查询参数用于筛选、排序、分页或选择表示，而不是隐藏另一套方法系统。路径采用复数还是单数属于团队约定，一致性比把某种拼写宣称为 REST 定律更重要。

并非所有动词路径都错误。诸如取消订单这类有独立审计记录和生命周期的动作，可以建模为从属资源，例如 POST /orders/ord-7/cancellations。关键是先找出客户端可观察、可标识的状态，而不是把控制器函数名直接暴露为 /cancelOrderNow。

安全方法的语义是客户端没有请求改变服务端状态；日志、计费统计等附带记录仍可能发生。 幂等性（idempotency） 表示重复相同请求的预期服务端效果与一次请求相同，不表示每次响应完全一样。因此，第一次 DELETE 返回 204、第二次返回 404，仍不违背方法的幂等语义。

状态码与表示元数据

状态码描述这次 HTTP 操作的结果，响应体补充机器可读细节。200 适合带表示的成功响应，201 表示创建了资源，并通常配合 Location 指向新资源；202 只表示工作已接受，因而还需要可查询的任务状态；204 不能带响应体。客户端错误与服务端错误不能都包装成 200，否则缓存、重试和监控会得到错误信号。

Content-Type 说明当前消息体的媒体类型，Accept 表达客户端可接受的响应媒体类型。缓存相关响应还要正确发送 Cache-Control、ETag、Last-Modified 和必要的 Vary。这些响应头属于契约，不是部署以后随手添加的装饰。

条件更新流程

两个客户端先后读取同一资源时，无条件写入会产生丢失更新。实体标签（entity tag）让客户端把读到的表示版本作为写入前置条件，服务端则在同一次原子写入中比较版本并修改资源。

比较与更新必须共享一个原子边界。若应用先读取版本，再用另一条无条件语句保存，两个请求仍可能同时通过检查。数据库版本列、比较后交换操作或带版本条件的单条更新，才把 HTTP 前置条件落实到持久层。

示例

下面三个示例使用 Node 24 的纯 JavaScript 模拟 HTTP 边界。它们依次建立资源路由、条件更新和可重试创建；真实服务还必须在适配器中加入输入解析、认证、资源级授权与持久化事务。

建立资源操作

第一个处理器把集合 URI 与成员 URI 分开，并让方法决定操作。创建成功返回 201 和 Location，不受支持的方法返回 405 和 Allow。

这个内存处理器只演示可观察的 HTTP 决策，不是生产服务器。真实实现要验证 sku 与 quantity，根据已认证主体检查创建权限，并避免把数据库记录直接当响应表示。Allow 还应根据实际资源能力生成，而不是散落在多个分支中。

用 If-Match 防止丢失更新

两个读取结果都带同一个 实体标签（entity tag） 。第一次替换推进资源版本，第二个客户端再提交旧标签时得到 412，而不是覆盖已提交状态。

let order = { id: "ord-7", status: "pending", version: 4 };

function currentTag() {
  return `"order-${order.version}"`;
}

function readOrder() {
  return { status: 200, headers: { ETag: currentTag() }, body: { ...order } };
}

function replaceOrder(ifMatch, replacement) {
  if (ifMatch !== currentTag()) {
    return { status: 412, headers: { ETag: currentTag() }, body: { ...order } };
  }

  order = {
    id: order.id,
    status: replacement.status,
    version: order.version + 1,
  };
  return { status: 200, headers: { ETag: currentTag() }, body: { ...order } };
}

const clientA = readOrder();
const clientB = readOrder();
const firstWrite = replaceOrder(clientA.headers.ETag, { status: "shipped" });
const staleWrite = replaceOrder(clientB.headers.ETag, { status: "cancelled" });

console.log(`read ${clientA.headers.ETag}`);
console.log(`first write ${firstWrite.status} ${firstWrite.headers.ETag} ${firstWrite.body.status}`);
console.log(`stale write ${staleWrite.status} ${staleWrite.headers.ETag} ${staleWrite.body.status}`);

read "order-4"
first write 200 "order-5" shipped
stale write 412 "order-5" shipped

标签是不透明验证器，客户端不应解析 order-4 的内部格式。示例使用版本号生成强标签；生产服务必须保证同一个强标签对应逐字节相同的选定表示，并把条件比较与更新放入同一事务。冲突响应还可以返回当前标签或当前表示，帮助客户端重新读取并决定是否合并。

让创建请求可以安全重试

POST 在 HTTP 规范中不保证幂等，但应用可以通过 幂等键（idempotency key） 识别同一次业务尝试。服务端还要保存请求指纹；同一个键若配上不同输入，应被拒绝，而不是静默返回第一次操作的结果。

const attempts = new Map();
let sequence = 40;

function createPayment(tenantId, key, input) {
  const scopedKey = `${tenantId}:${key}`;
  const fingerprint = JSON.stringify(input);
  const previous = attempts.get(scopedKey);

  if (previous) {
    if (previous.fingerprint !== fingerprint) {
      return { status: 409, replayed: false, error: "idempotency key reused with different input" };
    }
    return { ...previous.response, replayed: true };
  }

  const payment = {
    id: `pay-${++sequence}`,
    amount: input.amount,
    currency: input.currency,
  };
  const response = { status: 201, payment };
  attempts.set(scopedKey, { fingerprint, response });
  return { ...response, replayed: false };
}

const first = createPayment("tenant-a", "attempt-9", { amount: 2500, currency: "EUR" });
const retry = createPayment("tenant-a", "attempt-9", { amount: 2500, currency: "EUR" });
const conflict = createPayment("tenant-a", "attempt-9", { amount: 9900, currency: "EUR" });

console.log(`${first.status} ${first.replayed} ${first.payment.id}`);
console.log(`${retry.status} ${retry.replayed} ${retry.payment.id}`);
console.log(`${conflict.status} ${conflict.replayed} ${conflict.error}`);

201 false pay-41
201 true pay-41
409 false idempotency key reused with different input

内存 Map 只适合说明算法，进程重启或多实例部署都会使它失效。生产实现要按调用方或租户限定键的作用域，在持久存储中原子写入键、规范化请求指纹、操作状态和最终响应，并定义并发中的「正在处理」状态及保留期限。业务写入成功但幂等记录失败，仍可能产生重复副作用，因此两者必须共享事务或等价的一致性机制。

陷阱

把路径命名当作完整设计

修复方法： 为每项操作记录方法、目标资源、前置条件、成功和失败状态、响应头、表示模式、授权以及重试行为。路径风格只是这份契约的一小部分。

误解 PUT、PATCH 与幂等性

修复方法： 明确 PUT 接受的完整表示和缺失字段语义，并为 PATCH 声明支持的补丁媒体类型。用重复请求测试最终资源效果，不要只比较两次响应体。

无条件覆盖并发写入

修复方法： 用 ETag 与 If-Match 暴露前置条件，并让持久层在同一条条件更新或事务中比较版本。条件失败时返回 412，让客户端基于新表示作出明确决定。

直接展开数据库对象

修复方法： 为请求和响应分别定义允许字段，显式构造表示，并在读取目标资源后执行对象级授权。用契约测试断言敏感字段不存在，而不只断言期望字段存在。

用进程内缓存实现幂等键

修复方法： 把幂等记录与业务效果原子持久化，按认证主体限定键，比较规范化请求指纹，并保存处理中、成功和失败策略。明确保留时间以及过期键重新出现时的行为。

让分页顺序漂移

修复方法： 定义包含唯一决胜字段的全序，例如 (createdAt, id)，并把全部排序值编码进不透明游标。说明筛选条件是否绑定到游标，以及分页读取采用实时视图还是一致性快照。

延伸阅读

• RFC 9110：HTTP 语义
• RFC 9111：HTTP 缓存
• RFC 5789：HTTP PATCH 方法
• RFC 9457：HTTP API 问题详情
• OpenAPI 规范
• REST 架构风格：博士论文原文