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,三种方案按优先级:
- 建模成资源:
POST /orders/1/cancellations——取消变成创建一条取消记录,可追溯; - 建模成状态字段:
PATCH /orders/1带{ status: cancelled }; - 动词后缀兜底:
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" }
]
}
四点决定这套格式是否可用:
type是稳定契约,客户端按它分支,绝不按detail文案分支——文案会改,URI 不该改;code是自定义扩展,用于国际化与日志聚合,同一个 code 可直接 group by;errors承载字段级明细,表单类接口缺了它基本没法用;- 不回显内部信息:堆栈、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 后的用户互相误伤。
上线检查清单
- URL 名词复数、全小写、连字符、无动词,层级不超过两层;
- 方法与语义/安全性/幂等性对应;每个写接口能回答「重试会发生什么」,非幂等接口带
Idempotency-Key(同 key 不同 body 冲突); - 状态码分层,429 与 503 都带
Retry-After; - 错误统一
application/problem+json,含稳定type、业务code与字段级明细; - 深分页用 cursor,游标基于唯一且稳定的复合排序键;
- 兼容变更不升版本,破坏性变更升版本并灰度;
- GET 可安全缓存、写操作
no-store、个性化响应private,全站 HTTPS,限流按身份。