REST API 设计最佳实践:资源建模、幂等性与版本管理

API 是产品,不是数据库的镜像

把每张表直接暴露成 CRUD 端点,会得到一堆 /getUsers、/createOrder、/updateUserStatus。它能跑,但每接一个客户端就多一份适配逻辑,改一次表结构就要通知所有调用方。

REST 的价值不在「看起来规范」,而在于不读文档也能猜对——这从资源建模开始。

一、资源建模:URL 按名词组织

用名词,不用动词

URL 描述资源,HTTP 方法描述动作。动词写进 URL,等于丢掉 HTTP 已经提供的语义层。

反例 正例 说明
GET /getUsers GET /users 动作已由 GET 表达
POST /createOrder POST /orders 创建由 POST 表达
POST /deleteUser/123 DELETE /users/123 否则中间层无法判断安全性
GET /getUserOrders?uid=1 GET /users/1/orders 层级关系放进路径

层级表达关系,但别超过两层

/users/1/orders/2/items/3 合法,却把客户端锁死在一条遍历路径上,每层还要校验父资源是否存在。规则:

  • 关系唯一且强归属时用层级:/users/1/orders;
  • 超过两层就扁平化,用查询参数过滤:/orders?userId=1&status=paid;
  • 资源有全局唯一 id 时允许顶层访问:/orders/2,不必强制从父资源进入。

命名一致性

  • 集合用复数:/orders、/users;
  • 全小写。URL 部分区间大小写敏感,/orderItems 与 /orderitems 在不同层可能被当成两个资源;
  • 多词用连字符:/order-items,无需转义;
  • 末尾不加斜杠。部分框架把 /orders 与 /orders/ 当成两条路由。

非 CRUD 动作怎么放

「发布」「取消」「批量重算」映射不到 CRUD,三种方案按优先级:

  1. 建模成资源:POST /orders/1/cancellations——取消变成创建一条取消记录,可追溯;
  2. 建模成状态字段:PATCH /orders/1 带 { status: cancelled };
  3. 动词后缀兜底:POST /orders/1:publish,可接受,但要在文档里标明它不是资源。

二、HTTP 方法:先定重试语义

方法 语义 安全(无副作用) 幂等 典型响应
GET 读取资源 是 是 200 + 资源
HEAD 只要响应头 是 是 200 无 body
POST 创建或从属操作 否 否 201 + Location
PUT 完整替换(可创建) 否 是 200 / 201 / 204
PATCH 局部更新 否 默认否 200 / 204
DELETE 删除 否 是 204 / 200
OPTIONS 询问支持的方法 是 是 200 + Allow

完整语义与副作用对照见 HTTP 方法速查表。

幂等性:哪些方法必须幂等

幂等 = 同一请求执行 N 次,服务端状态与执行 1 次相同。

规范层面:GET/HEAD 安全且幂等,PUT/DELETE 必须幂等,POST 不幂等,PATCH 取决于载荷。这不是学术洁癖——重试一定会发生:移动网络切换、网关超时重放、消息队列至少一次投递、用户双击。

各类方法在重试下的实际后果:

方法 重试后发生什么 必须做的防护
POST /orders 生成第二笔订单 客户端带 Idempotency-Key,服务端按 key 去重
PATCH { balanceDelta: -100 } 扣两次钱 改为提交绝对值 { balance: 900 }
PUT /orders/1 结果与第一次相同 无(天然幂等)
DELETE /orders/1 第二次返回 404 无(状态仍与执行一次相同)
GET /report?refresh=1 若带副作用则重复触发 有副作用就别用 GET

Idempotency-Key 的落地细节:key 由客户端按「一次业务操作」生成,而不是每次 HTTP 尝试都换(换 key 等于没做);服务端保存 key → 首次的响应状态与 body,原样回放;同一 key 配不同请求体应返回冲突(409),否则一个 key 会掩盖两次不同的写操作;保留期按业务定,原文做法是 24 小时。生成 key 用 UUID 生成器 即可。创建成功返回 201 Created 并在 Location 带新资源 URL;异步入队返回 202 Accepted 加状态查询地址,不要用 200 假装已完成。

三、状态码:分层,而不是一切 200

「一切皆 200,错误码放 body」会让监控失效、让网关缓存误判、让客户端必须解析 body 才知道成败。

类别 语义 常用码
2xx 成功 200 OK / 201 Created / 202 Accepted / 204 No Content
3xx 重定向与缓存 301 / 302 / 304 Not Modified
4xx 客户端错误,重试无意义 400 / 401 / 403 / 404 / 409 / 422 / 429
5xx 服务端错误,可重试 500 / 502 / 503 / 504

完整清单与常见误用见 HTTP 状态码参考。容易判错的边界:

  • 400 vs 422:语法合法但语义校验失败(结束日期早于开始日期)用 422,格式错误用 400;
  • 401 vs 403:401 是「不知道你是谁」,403 是「知道你是谁但不行」,已登录但无权限必须 403;
  • 404 vs 403:不想暴露资源是否存在时,用 404 掩盖 403 是合理的安全实践;
  • 409 Conflict:状态冲突(重复提交、版本不匹配、库存不足),明确告诉客户端「先改状态,重试没用」;
  • 429:必须带 Retry-After,否则客户端盲目重试,把限流放大成雪崩。

四、统一错误格式

用 RFC 7807 的 application/problem+json 作为统一信封:

{
  "type": "https://api.example.com/errors/order-already-paid",
  "title": "Order already paid",
  "status": 409,
  "detail": "Order 9f3c has already been paid and cannot be modified.",
  "instance": "/orders/9f3c",
  "code": "ORDER_ALREADY_PAID",
  "errors": [
    { "field": "quantity", "reason": "must be greater than 0" }
  ]
}

四点决定这套格式是否可用:

  1. type 是稳定契约,客户端按它分支,绝不按 detail 文案分支——文案会改,URI 不该改;
  2. code 是自定义扩展,用于国际化与日志聚合,同一个 code 可直接 group by;
  3. errors 承载字段级明细,表单类接口缺了它基本没法用;
  4. 不回显内部信息:堆栈、SQL、内部主机名、用户输入原文都不该出现在错误体里。

契约要固化时,用 JSON Schema 生成工具 从真实响应反推 schema,比手写文档更不容易漂移。

五、分页:offset 与 cursor 的失效边界

维度 offset 分页 cursor 分页
语法 ?offset=100&limit=20 ?cursor=eyJpZCI6MTAwMH0&limit=20
深翻页 随 offset 线性劣化(要扫描并丢弃前 N 行) 恒定,索引直接定位
并发插入/删除 重复或漏读 免疫(基于排序键定位)
随机跳页 支持 不支持
返回总数 容易 需额外计数
适用 后台管理、报表 信息流、时间线、导出

offset 的失效边界:翻页期间有写入时,窗口会整体平移——第 2 页可能重复出现第 1 页的末条,也可能跳过一条;offset 越深越慢,因为数据库要先扫掉前 N 行。

cursor 的失效边界:cursor 依赖「唯一且稳定」的排序键。按 created_at 排序而时间戳可能重复时,必须加 id 组成复合游标,否则同一时间戳的记录会被跳过或重复;按可变的 updated_at 排序,记录被修改后会跳到游标之外;基于「上一页最后一条的 id」查下一批,遇到该行被删除就会断,应改成比较式查询 WHERE (created_at, id) > (…)。游标还应当是不透明字符串并做校验,不能直接拼进 SQL。

过滤与排序统一约定,别每个端点各写一套:

?status=paid&created_after=2026-01-01
?sort=-created_at,amount          # 减号表示降序
?fields=id,status,total           # 明确它对缓存键的影响
?count=true                       # total 是最贵的一次 COUNT(*),别默认返回

改版对比两版响应差异,JSON Diff 比肉眼逐字段对更可靠。

六、版本管理

方案 示例 优点 缺点 适用
URL 前缀 /v1/orders 直观、可分享、日志可见 版本侵入资源标识 公开 API
请求头 Accept: application/vnd.app.v1+json URL 干净、符合内容协商 隐藏版本、缓存配置复杂 内部服务
查询参数 ?version=1 实现简单 污染查询空间、易被忽略 不推荐

能不升版本就不升。 向后兼容、无需新版本号的变更:新增可选请求字段、新增响应字段(前提是客户端忽略未知字段)、新增端点、新增 Link 头或错误 type、新增枚举值(前提是客户端容忍未知值)。

必须升版本或灰度的破坏性变更:删除或重命名字段、收紧校验规则、改变字段类型或单位、改变错误语义。判断标准是「旧客户端不升级会不会坏」——会坏就是破坏性。

七、缓存与条件请求

头 方向 作用
Cache-Control 响应 缓存策略(max-age、no-store、private)
ETag 响应 资源版本指纹
If-None-Match 请求 带上上次 ETag,未变更返回 304
Last-Modified / If-Modified-Since 双向 基于时间的弱校验
Vary 响应 按哪些请求头区分缓存(如 Accept-Encoding)
Retry-After 响应 429/503 时告知何时可重试

逐项核对可用 HTTP 头速查表。三条实践要点:GET 默认可缓存,所以绝不能用 GET 做有副作用的操作(爬虫与预取会替你触发);写操作显式声明 no-store;认证后的个性化响应必须带 Cache-Control: private,否则共享缓存可能把 A 的数据发给 B。

八、认证的最小共识

  • 强制 HTTPS,明文 HTTP 直接 301;证书与 TLS 细节见 HTTPS 证书指南。
  • 不自研认证协议:OAuth 2.1 / OIDC 或成熟会话方案,Token 见 JWT 安全最佳实践;密码用 bcrypt / Argon2 / scrypt 哈希,见 密码哈希指南。
  • 授权在服务端,前端隐藏按钮不是权限控制;限流按身份而非 IP,否则 NAT 后的用户互相误伤。

上线检查清单

  1. URL 名词复数、全小写、连字符、无动词,层级不超过两层;
  2. 方法与语义/安全性/幂等性对应;每个写接口能回答「重试会发生什么」,非幂等接口带 Idempotency-Key(同 key 不同 body 冲突);
  3. 状态码分层,429 与 503 都带 Retry-After;
  4. 错误统一 application/problem+json,含稳定 type、业务 code 与字段级明细;
  5. 深分页用 cursor,游标基于唯一且稳定的复合排序键;
  6. 兼容变更不升版本,破坏性变更升版本并灰度;
  7. GET 可安全缓存、写操作 no-store、个性化响应 private,全站 HTTPS,限流按身份。

常见问题

PUT 和 PATCH 到底该用哪个?

PUT 用完整替换,PATCH 用局部更新。PUT 要求客户端提交资源的完整表示,缺失字段按删除处理,且天然幂等——同样的请求体发一百次,结果完全一致。PATCH 只提交要改的字段,语义更省带宽,但默认不幂等:{ op: add, value: 1 } 这种自增操作发两次结果就不同。实践建议:优先用 PUT 表达「设置成这个状态」,用 PATCH 表达「改这几个字段」;如果 PATCH 也要保证幂等,就只允许客户端提交绝对值而非相对增量。判断标准是重试安全性——只要这个接口可能被网关或客户端自动重试,就必须幂等。

API 版本号应该放在 URL 里还是请求头里?

没有唯一正确答案,但有明确的决策依据。 URL 前缀(/v1/orders)最直观、可在浏览器直接访问、日志和监控里一眼可见、调试成本最低,代价是版本号侵入了资源标识。请求头版本(Accept: application/vnd.myapp.v1+json)保持 URL 干净、符合内容协商的 HTTP 语义,代价是隐藏了版本、分享链接会失效、网关缓存配置更麻烦。务实建议:面向外部开发者的公开 API 用 URL 前缀(可发现性优先),内部服务用请求头(演化优先)。更重要的原则是——能不升版本就别升。向后兼容的变更(新增可选字段、新增枚举值、新增端点)永远不需要新版本号,只有破坏性变更才升。把 v1 到 v2 当成一次昂贵的产品决策,而不是随手一个数字。

分页用 offset 还是 cursor?深翻页为什么越来越慢?

浅分页用 offset,深分页或数据会变的场景用 cursor。 ?offset=100000&limit=20 的问题是数据库必须先扫描并丢弃前十万行才能返回,页数越深越慢;更糟的是,如果翻页期间插入了新数据,offset 会导致记录重复或漏读。cursor(游标)方案基于上一页最后一条的排序键(通常是自增 id 或时间戳)取下一批:?cursor=eyJpZCI6MTAwMH0&limit=20,配合索引直接定位,复杂度恒定且与深度无关,同时天然免疫插入导致的漂移。代价是游标无法随机跳页(不能直接跳到第 500 页)。混合策略最常见:后台管理系统用 offset(需要跳页和总数),面向 C 端的信息流用 cursor(只需要「加载更多」)。

错误响应用什么格式?直接返回 HTTP 状态码不够吗?

不够。状态码只表达了错误的「类别」,客户端还需要一个稳定的机器可读「原因」。 只用 400 而不给细节,客户端只能把原文弹给用户看——而后端文案往往不是面向终端用户的。推荐 RFC 7807(problem+json)作为统一信封,它规定了 type、title、status、detail、instance 五个字段,且 application/problem+json 已被主流框架原生支持。实践要点:① type 用稳定 URI 表达错误类别,客户端按它分支,不按文案分支;② 增加一个自定义扩展字段承载业务错误码(如 code: ORDER_ALREADY_PAID),方便国际化与监控聚合;③ 校验类错误务必带上字段级明细,否则表单体验极差;④ 绝不要在错误体里回显堆栈、SQL 或内部主机名。

← 返回博客首页