后端-01-HTTP与RESTfulAPI设计
这篇笔记讲什么
后端接口是「别人(前端、App、第三方)调用你」的唯一契约。这篇笔记从后端的视角重看 HTTP:报文结构、方法语义、状态码、REST 约束、资源命名、版本化、分页、错误结构、OpenAPI 文档、限流。
读完你应该能:给一个新业务设计出一套自洽的 REST 接口,并说清每个状态码为什么是它而不是别的。
一、后端在系统里的位置与职责
一个典型的 Web 系统分成三层,后端是唯一同时理解业务规则和数据结构的一层:
浏览器 / App / 第三方服务 ← 客户端(Client)
│ HTTP 请求(JSON)
▼
反向代理 Nginx → 后端应用 ← 路由、鉴权、业务规则、参数校验
│ SQL / 命令
▼
数据库 / 缓存 / 消息队列 ← 持久化与异步
后端的职责可以归纳成五件事:
| 职责 | 具体内容 | 出错后的后果 |
|---|---|---|
| 暴露接口 | 定义 URL、方法、请求体、响应体 | 前端无法对接,返工 |
| 鉴权与授权 | 你是谁、你能做什么 | 越权读写,安全事故 |
| 参数校验 | 类型、范围、必填、格式 | 脏数据入库,后续清洗成本极高 |
| 业务逻辑 | 状态机、计算、事务 | 数据不一致 |
| 持久化 | 读写数据库、缓存、队列 | 数据丢失 |
一句话定位
后端 = 把数据库的「表」翻译成业务世界的「资源」,并对每一次访问做鉴权与校验。
这个翻译得好不好,直接决定 API 是否好懂、好用、好演进。
二、为什么需要「设计」API 而不是「写出来」就行
随便写一个接口,让前端能拿到数据,一天就能完成。但接口是会被调用很多年的东西:
- 移动端 App 发布后,旧版本会长期存在于用户手机上,你无法强制所有人升级;
- 第三方集成方可能半年才更新一次;
- 前端重构时,如果接口语义混乱(比如用
GET /deleteUser?id=1),重构者必须读后端源码才知道行为。
没有设计规范的接口,通常会出现这些问题:
| 症状 | 后果 |
|---|---|
URL 里混动词(/getUser、/createOrder) | 接口数量爆炸,/getUserList、/listUser、/user/search 三套并存 |
| 状态码一律返回 200,错误放在响应体 | 网关、监控、重试中间件全部失效 |
分页参数每页一套(page / pageNum / p) | 前端要写三套封装 |
| 无版本化 | 一次破坏性变更直接打挂所有客户端 |
判断标准
一个好的 API:不看文档也能猜出 70% 的用法,剩下的 30% 在文档里一眼能找到。
三、HTTP 回顾:后端视角
3.1 请求报文结构
POST /api/v1/articles HTTP/1.1 ← 请求行:方法 + 目标 + 版本
Host: api.example.com ← 以下全是请求头(Header)
Content-Type: application/json
Content-Length: 58
Authorization: Bearer eyJhbGciOi...
{"title":"HTTP 笔记","body":"..."} ← 消息体(Body),可为空
3.2 响应报文结构
HTTP/1.1 201 Created ← 状态行:版本 + 状态码 + 原因短语
Location: /api/v1/articles/42 ← 响应头
Content-Type: application/json
{"id":42,"title":"HTTP 笔记"} ← 响应体
3.3 常用请求头(后端必须处理的)
| 请求头 | 作用 | 后端要做什么 |
|---|---|---|
Host | 目标主机(虚拟主机路由依据) | 多租户/多域名时用它区分站点 |
Content-Type | 请求体的媒体类型 | 不是 application/json 就该回 415 |
Accept | 客户端期望的响应类型 | 不支持时回 406 |
Authorization | 凭证(Bearer Token / Basic) | 解析并鉴权,失败回 401 |
If-None-Match | 条件请求,带上次的 ETag | 内容未变返回 304(无响应体) |
If-Match | 乐观并发控制 | 版本不匹配返回 412 |
Idempotency-Key | 幂等键(自定义头) | 同一键重复提交返回首次结果 |
X-Request-Id | 链路追踪 ID | 写进日志,原样回显 |
Accept-Language | 期望语言 | 多语言文案切换 |
3.4 常用响应头(后端必须设置的)
| 响应头 | 作用 | 典型值 |
|---|---|---|
Content-Type | 响应体类型 | application/json; charset=utf-8 |
Location | 新资源地址 | 201 与 3xx 搭配使用 |
ETag | 资源版本指纹 | "33a64df5"(必须带双引号) |
Cache-Control | 缓存策略 | no-store(敏感数据)/ max-age=60 |
Retry-After | 何时可重试 | 429、503 搭配,单位秒或 HTTP 日期 |
Allow | 该资源允许的方法 | 405 必须带,如 GET, PUT, DELETE |
X-RateLimit-Limit / -Remaining / -Reset | 限流额度 | 自定义约定,非标准头 |
Vary | 缓存区分维度 | Accept-Encoding, Authorization |
Access-Control-Allow-Origin | 跨域许可 | 只允许具体源,不要无脑 * 配凭证 |
3.5 无状态(Stateless)的含义与代价
含义:服务器不保存「上一次请求」的记忆,每个请求必须自带完成处理所需的全部信息。会话状态放在客户端(Token)或共享存储(Redis)里。
好处:
- 任意一台机器都能处理任意请求 → 水平扩容简单,加机器即可;
- 进程重启不丢会话;
- 反向代理可以做无脑轮询(round-robin)。
代价:
- 每个请求都要重复传凭证,报文变大;
- Token 无法即时失效(签出去的 JWT 在过期前一直有效),需要黑名单或短过期 + 刷新令牌补偿;
- 服务端要额外维护共享会话存储(Redis),其实把状态挪了个地方;
- 「无状态」不等于「不能用 Session」,只要求状态不在单机内存里(详见 后端-06-认证与授权)。
四、HTTP 方法语义(Method Semantics)
4.1 安全性、幂等性与缓存性对照表
- 安全(Safe):不改变服务器状态,只读;
- 幂等(Idempotent):执行 1 次和执行 N 次,服务端最终状态相同(响应可以不同)。
| 方法 | 安全性 | 幂等性 | 可缓存 | 有无请求体 | 典型用途 |
|---|---|---|---|---|---|
GET | ✅ 安全 | ✅ 幂等 | ✅ 可缓存 | 不应有(语义上被忽略) | 查询资源 |
HEAD | ✅ 安全 | ✅ 幂等 | ✅ 可缓存 | 不应有 | 只取响应头:探活、查大小、查是否存在 |
OPTIONS | ✅ 安全 | ✅ 幂等 | ❌ | 可有 | 查询允许的方法;CORS 预检 |
POST | ❌ 不安全 | ❌ 非幂等 | ⚠️ 仅当显式声明 | ✅ 有 | 创建资源、执行动作 |
PUT | ❌ 不安全 | ✅ 幂等 | ❌ | ✅ 有 | 整体替换资源 |
PATCH | ❌ 不安全 | ❌ 通常非幂等 | ❌ | ✅ 有 | 局部更新 |
DELETE | ❌ 不安全 | ✅ 幂等 | ❌ | 可有 | 删除资源 |
幂等 ≠ 每次返回一样
DELETE /articles/42第一次返回204,第二次返回404——响应不同,但服务端状态相同,所以它仍然是幂等的。幂等的真正价值:网络超时后可以安全重试。
4.2 为什么不该用 GET 做写操作
GET /api/v1/articles/42/delete ← 绝对不要这样设计
四个具体后果:
- 可被预取:浏览器、搜索引擎爬虫、微信/钉钉等 IM 的消息预览都会主动抓取链接,用户没点也可能触发删除;
- 可被重放:GET 是幂等的、可缓存的,中间代理和 CDN 可能把响应缓存下来,甚至命中缓存导致「以为删了其实没删」;
- 泄漏到日志与 Referer:URL 会被完整记录在 Nginx access log、浏览器历史、
Referer头里。GET /transfer?to=xxx&amount=1000等于把操作参数公开; - CSRF 风险放大:一个
<img src="https://bank.com/transfer?to=evil&amount=10000">就能让已登录用户中招——因为 GET 携带 Cookie 且不需要用户确认。
正确写法:
DELETE /api/v1/articles/42
顺带一个真实坑
部分老网关和浏览器对 URL 长度有限制(IE 约 2083 字符,Nginx 默认
large_client_header_buffers限制请求行),所以GET也不适合传大参数——这又是一个「不要用 GET 传操作数据」的理由。
五、状态码的正确用法
5.1 五大分类
| 类别 | 含义 | 后端职责 |
|---|---|---|
| 1xx 信息性 | 请求已收到,继续处理 | 少见:100 Continue(上传大文件前确认)、101 Switching Protocols(升级 WebSocket) |
| 2xx 成功 | 请求被成功处理 | 用 200/201/204 精确区分语义 |
| 3xx 重定向 | 需要进一步动作 | 301/302/304;注意 301 会被浏览器永久缓存 |
| 4xx 客户端错误 | 调用方的问题 | 错误信息要可读、可定位,别只说「参数错误」 |
| 5xx 服务端错误 | 服务方的问题 | 必须告警;不要把用户输入错误算成 5xx |
5.2 重点状态码速查
| 状态码 | 名称 | 什么时候返回 | 关键细节 |
|---|---|---|---|
200 | OK | 通用成功:查询、更新后返回新对象 | 幂等与一次性操作都可用 |
201 | Created | POST 成功创建资源 | 必须带 Location 头,响应体可含新资源 |
202 | Accepted | 已接受但异步处理 | 返回任务 ID 供轮询 |
204 | No Content | 成功但无响应体:DELETE、PUT 无内容返回 | 不能有响应体,也别设 Content-Type |
206 | Partial Content | 断点续传/音视频拖动 | 与 Range/Content-Range 配合 |
301 | Moved Permanently | 域名或路径永久迁移 | 浏览器会长期缓存,测试期慎用 |
302 | Found | 临时跳转(如未登录跳登录页) | 历史上部分客户端会把 POST 改 GET |
303 | See Other | POST 后跳转到结果页(PRG 模式) | 明确要求用 GET 访问新地址 |
304 | Not Modified | 条件请求命中,内容未变 | 不能有响应体;配合 ETag/Last-Modified 省流量 |
400 | Bad Request | 请求报文本身坏了:JSON 语法错、缺必填字段 | 泛化的客户端错误 |
401 | Unauthorized | 未认证:没带或带了无效凭证 | 必须带 WWW-Authenticate 头 |
403 | Forbidden | 已认证但无权限 | 重试无用,别再登录 |
404 | Not Found | 资源不存在,或故意对无权限者隐藏存在性 | 路径正确但对象不存在 |
405 | Method Not Allowed | 路径存在但不支持该方法 | 必须带 Allow 头 |
406 | Not Acceptable | Accept 要求的类型都不支持 | 少见,但正确 |
409 | Conflict | 与当前资源状态冲突:唯一键重复、乐观锁版本不符 | 业务冲突首选 |
412 | Precondition Failed | If-Match/If-Unmodified-Since 失败 | HTTP 层的乐观锁 |
415 | Unsupported Media Type | Content-Type 不支持(如要求 JSON 却发 text/xml) | 与 406 是一对 |
422 | Unprocessable Content | 报文语法正确但语义不合法 | 校验失败的最佳选择 |
428 | Precondition Required | 要求带 If-Match 才允许修改 | 强制乐观并发 |
429 | Too Many Requests | 触发限流 | 必须带 Retry-After |
500 | Internal Server Error | 未捕获异常、空指针、SQL 报错 | 绝不能把堆栈返回给客户端 |
502 | Bad Gateway | 反向代理连不上/收到无效响应 | 后端进程崩了或端口不对 |
503 | Service Unavailable | 主动拒绝:过载保护、停机维护 | 带 Retry-After,配合健康检查摘流量 |
504 | Gateway Timeout | 代理等后端超时 | 通常需要排查慢查询/慢依赖 |
5.3 401 与 403 的区别
| 对比项 | 401 Unauthorized | 403 Forbidden |
|---|---|---|
| 含义 | 你没有证明身份 | 身份已知,但不被允许 |
| 触发场景 | 无 Authorization 头、Token 过期、签名错 | 普通用户访问 /admin、越权访问他人订单 |
| 客户端该做什么 | 去登录 / 刷新 Token 后重试 | 不要重试,提示「无权访问」 |
| 必备响应头 | WWW-Authenticate: Bearer realm="api" | 无强制要求 |
| 常见错误 | 权限不足返回 401 → 前端陷入「刷新 Token → 再失败 → 再刷新」死循环 | 未登录返回 403 → 用户不知道要登录 |
记忆法
401 = 你是谁?403 = 我知道你是谁,但你不能进。
5.4 400 与 422 的区别
| 对比项 | 400 Bad Request | 422 Unprocessable Content |
|---|---|---|
| 问题层次 | 语法层:JSON 解析失败、缺必填字段、类型不对 | 语义层:语法完整,但业务规则不通过 |
| 例子 | {"age": "abc"}(要整数给了字符串) | {"start_date":"2026-10-01","end_date":"2026-09-01"}(结束早于开始) |
| 例子 | 请求体不是合法 JSON | 邮箱格式合法但已被注册(也有人用 409) |
| 谁的问题 | 调用方写错了报文 | 调用方业务数据不合法 |
实践中很多团队统一用 400 加 code 字段,这不算错,但要注意:一旦用 400 表达全部校验错误,监控上就无法区分「SDK 有 bug」和「用户输入错」。
关于 422 的名字
RFC 9110 里它的正式名称是 Unprocessable Content(旧称 Unprocessable Entity),WebDAV 时代定义,现已并入 HTTP 语义标准。
六、REST 的六条约束
REST(Representational State Transfer,表述性状态转移)是 Roy Fielding 在 2000 年博士论文中提出的架构风格,不是协议、不是标准。它由六条约束组成:
| # | 约束 | 含义 | 违反后的后果 |
|---|---|---|---|
| 1 | 客户端-服务器(Client-Server) | 界面与数据存储分离,各自独立演进 | 前后端耦合,改 UI 要动后端 |
| 2 | 无状态(Stateless) | 每个请求自带全部上下文 | 无法水平扩容,会话绑定单机 |
| 3 | 可缓存(Cacheable) | 响应必须声明自己能否缓存 | 重复查询压垮数据库 |
| 4 | 统一接口(Uniform Interface) | 资源标识、通过表述操作资源、自描述消息、HATEOAS | 每个接口一套规则,学习成本爆炸 |
| 5 | 分层系统(Layered System) | 客户端不知道是否连着中间层 | 无法加网关/CDN/负载均衡 |
| 6 | 按需代码(Code-On-Demand) | 可选:服务端下发可执行代码(如 JS) | 唯一可选项,不用也没关系 |
6.1 统一接口的四个子约束
- 资源的标识:每个资源有唯一 URI,
/articles/42; - 通过表述操作资源:客户端拿到的 JSON 是资源的表述(representation),不是资源本身;
- 自描述消息:报文自带
Content-Type、状态码等元数据,不需要额外上下文; - HATEOAS(Hypermedia as the Engine of Application State):响应里带下一步可用的链接。
{
"id": 42,
"title": "HTTP 笔记",
"status": "draft",
"_links": {
"self": { "href": "/api/v1/articles/42" },
"publish":{ "href": "/api/v1/articles/42/publish", "method": "POST" },
"author": { "href": "/api/v1/users/7" }
}
}
关于 HATEOAS 的现实
真正的 HATEOAS 在实践中很少被完整实现——客户端通常直接硬编码 URL 模板。所以「RESTful」在日常语境里往往只是指「用名词 URL + HTTP 方法 + 状态码」。
写文档时最好明确:本项目是 REST-ish(实用主义 REST) 还是严格 REST。别在面试/评审里说「我们有 HATEOAS」而实际没有。
6.2 常见误解
| 误解 | 事实 |
|---|---|
| 「REST = 返回 JSON」 | 格式无关,XML、Protobuf 都可以;关键是约束 |
| 「REST = 用 HTTP」 | 用了 HTTP 但 URL 里全是动词,仍不是 REST 风格 |
| 「必须用 REST,GraphQL/gRPC 是错的」 | 它们是不同取舍:GraphQL 解决过度获取,gRPC 解决内部高性能调用 |
「RESTful 就不能有 /search」 | 可以把搜索本身建模为资源:GET /article-searches?q=xxx,或用 GET /articles?q=xxx |
| 「REST 无状态所以不能用 Session」 | 无状态约束针对服务器不保存会话;状态放 Redis 依然满足 |
七、资源命名规范
7.1 五条规则
- 用名词,不用动词:
GET /articles而不是GET /getArticles - 集合用复数:
/articles、/users、/comments - 层级表示从属关系:
/articles/42/comments(文章 42 的评论) - 用查询参数表达筛选、排序、分页:
/articles?status=published&sort=-created_at&page=2 - 小写 + 连字符:
/article-categories(不要/ArticleCategories或/article_categories;路径大小写敏感,混用必然出事)
7.2 层级嵌套的深度控制
| 场景 | 推荐 | 不推荐 | 原因 |
|---|---|---|---|
| 取某文章的评论 | GET /articles/42/comments | GET /comments?article_id=42 | 从属关系明确,权限校验简单 |
| 取某评论的作者 | GET /comments/99/author | GET /articles/42/comments/99/author | 评论 ID 已全局唯一,无需全路径 |
| 超过 2 层 | GET /comments?article_id=42&author_id=7 | /a/1/b/2/c/3/d/4 | 超过 2 层难维护、难加索引 |
实用判据
资源能否脱离父资源独立存在? 能(评论有独立 ID、能单独查询)→ 扁平化;不能(订单项脱离订单无意义)→ 保留嵌套。
7.3 无法用 CRUD 表达的操作怎么办
有些操作天然是「动作」而非「资源状态变更」:
| 反例 | 方案 A:子资源(推荐) | 方案 B:控制器式路径(务实) |
|---|---|---|
| 发布文章 | POST /articles/42/publication | POST /articles/42/publish |
| 重置密码 | POST /users/42/password-resets | POST /users/42/reset-password |
| 转账 | POST /transfers | POST /accounts/1/transfer |
结论
绝大多数「动作」都能重新建模成名词化的子资源(
publication、password-resets、transfers)。实在别扭时用方案 B 也可接受——一致比纯粹更重要,但要在团队内统一并写进规范。
八、API 版本化策略对比
| 策略 | 示例 | 优点 | 缺点 | 适用 |
|---|---|---|---|---|
| URL 路径 | GET /api/v1/articles | 直观、易调试、易做路由与灰度 | URL 变长;理论上违反「URI 标识资源」(不同 URL 是不同资源) | 最常用,推荐 |
| 请求头 | Accept-Version: v1 或自定义 X-API-Version: 1 | URL 干净;符合内容协商精神 | 浏览器直接打开无法测试;缓存与网关需额外配置 Vary | 内部服务、需严格语义时 |
| 查询参数 | GET /articles?version=1 | 实现最简单 | 污染业务参数;缓存键混乱;容易被误删 | 临时过渡方案 |
| 内容协商 | Accept: application/vnd.example.v1+json | 最「正统」,同一 URL 多表述 | 学习成本高,工具支持差 | 大型公开 API(如 GitHub) |
8.1 版本化的现实建议
GET /api/v1/articles HTTP/1.1 ← 只对「主版本」做路径版本化
- 只对破坏性变更升主版本,加字段、加可选参数不需要新版本;
- 同时支持 N 和 N-1 两个版本,给客户端留迁移窗口(常见 6~12 个月);
- 在响应头里提前通知废弃:
Deprecation: Fri, 01 May 2026 00:00:00 GMT
Sunset: Sat, 01 Aug 2026 00:00:00 GMT
Link: </api/v2/articles>; rel="successor-version"
九、分页设计
9.1 两种主流方案
| 对比项 | 偏移分页(Offset/Limit) | 游标分页(Cursor/Keyset) |
|---|---|---|
| 参数形式 | ?page=3&per_page=20 或 ?offset=40&limit=20 | ?cursor=eyJpZCI6NDJ9&limit=20 |
| 实现 SQL | LIMIT 20 OFFSET 40 | WHERE (created_at, id) < (?, ?) ORDER BY created_at DESC, id DESC LIMIT 20 |
| 跳页 | ✅ 支持「直接跳到第 50 页」 | ❌ 只能上一页/下一页 |
| 总数 | ✅ 容易给出 total | ❌ 需要额外 COUNT(*),通常不提供 |
| 数据变动时 | ❌ 重复/漏项:新增数据导致整体后移 | ✅ 稳定,基于已见位置 |
| 深分页性能 | ❌ 差(见下) | ✅ 恒定 量级 |
| 适用 | 后台管理表格、需要页码 UI | 信息流、无限滚动、公开 API |
9.2 深分页的性能问题(含公式)
数据库执行 LIMIT n OFFSET m 时,必须先定位并丢弃前 行才能返回第 行起的数据。被扫描但被丢弃的行数是:
在索引有序扫描(index scan)下,时间近似为
而在游标分页下,数据库先用索引定位到断点位置,再顺序读 行:
两者比值随页码增长而线性恶化:
举例:n = 20,请求第 5000 页(),扫描行数比是
也就是说,为了返回 20 行,读放大到了 5 万行。如果排序字段没有索引,还叠加一次 的排序,可能直接拖垮数据库。
另外三个 Offset 分页的隐性成本
1.
SELECT COUNT(*)求总页数在大表上本身就是全表/全索引扫描;2. 用户翻页期间若有新数据插入,第 2 页可能出现第 1 页看过的内容(重复项);
3.
OFFSET极大时,MySQL 会报「Got a packet bigger than...」或直接超时,而不是给你一个优雅的错误。
9.3 统一的分页响应体
{
"data": [
{ "id": 120, "title": "HTTP 笔记" },
{ "id": 119, "title": "REST 约束" }
],
"pagination": {
"limit": 20,
"next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0xMVQwOTowMDowMFoiLCJpZCI6MTE5fQ",
"has_more": true,
"total": 1532
}
}
{
"data": [ { "id": 120 } ],
"pagination": { "page": 3, "per_page": 20, "total": 1532, "total_pages": 77 }
}
实践建议
- 默认
limit = 20,强制上限(如limit ≤ 100),否则?limit=1000000就是一次 DoS;- 游标内容用 base64 编码,避免客户端依赖具体结构——你才能随时改索引策略;
-
total用近似值即可(见 数据库原理 的EXPLAIN估算行数),或干脆只在第一页返回。
十、过滤、排序、字段裁剪
10.1 约定表
| 需求 | 参数约定 | 示例 | 说明 |
|---|---|---|---|
| 等值过滤 | 字段名直接作参数 | ?status=published&author_id=7 | 多个参数是 AND 关系 |
| 多值匹配 | 逗号分隔或重复参数 | ?status=draft,published | 要文档化:逗号分隔需 URL 编码 %2C |
| 范围过滤 | 后缀 _gte/_lte 或 min_/max_ | ?created_at_gte=2026-01-01 | 全站统一一种 |
| 模糊搜索 | q | ?q=http%20rest | 语义是「全字段模糊匹配」,与大表要慎用 |
| 排序 | sort,- 表示降序 | ?sort=-created_at,title | 白名单校验字段,防注入 |
| 字段裁剪 | fields | ?fields=id,title,created_at | 减小响应体,但不要省掉必需字段 |
| 关联展开 | include / expand | ?include=author,comments | 避免 N+1 与客户端多次请求 |
10.2 实现要点(Node.js/Express 示例)
// GET /api/v1/articles?status=published&sort=-created_at&fields=id,title&limit=20
const SORTABLE = new Set(['created_at', 'updated_at', 'title', 'id']);
const SELECTABLE = new Set(['id', 'title', 'body', 'status', 'created_at', 'author_id']);
function parseListQuery(req) {
// 1) limit:强制夹紧到 [1, 100],防 ?limit=99999999 拖垮数据库
const limit = Math.min(Math.max(parseInt(req.query.limit ?? '20', 10) || 20, 1), 100);
// 2) sort:只允许白名单字段,'-' 前缀表示降序;拼进 SQL 前必须校验,
// 因为 ORDER BY 不能用占位符参数化,只能白名单
const sort = String(req.query.sort ?? '-created_at')
.split(',')
.map(s => s.trim())
.filter(Boolean)
.map(s => {
const desc = s.startsWith('-');
const col = desc ? s.slice(1) : s;
if (!SORTABLE.has(col)) throw Object.assign(new Error(`不可排序字段: ${col}`), { status: 422 });
return { col, dir: desc ? 'DESC' : 'ASC' };
});
// 3) fields:投影裁剪;id 永远保留,否则客户端无法定位对象
const fields = String(req.query.fields ?? '')
.split(',').map(s => s.trim()).filter(f => SELECTABLE.has(f));
const select = fields.length ? Array.from(new Set(['id', ...fields])) : null;
// 4) q:转义 LIKE 通配符,避免用户输入 % 把全表扫出来
const q = req.query.q ? `%${String(req.query.q).replace(/[%_\\]/g, '\\$&')}%` : null;
return { limit, sort, select, q, status: req.query.status };
}
sort与fields是注入高危点
ORDER BY和列名不能被参数化占位符替代(ORDER BY $1在 PostgreSQL 里是无效或按常量排序)。必须用白名单校验。fields=id,(SELECT password FROM users)这类注入真实存在。
十一、错误响应设计
11.1 统一错误结构
{
"error": {
"code": "ARTICLE_TITLE_TOO_LONG",
"message": "标题长度不能超过 100 个字符",
"details": [
{ "field": "title", "issue": "max_length", "limit": 100, "actual": 137 }
],
"request_id": "7f3c1a2e-9b4d-4c1e-8a77-2f9d0b6c5e11",
"timestamp": "2026-10-11T08:30:00Z",
"doc_url": "https://api.example.com/docs/errors#ARTICLE_TITLE_TOO_LONG"
}
}
11.2 错误码与人类可读消息必须分离
| 字段 | 给谁看 | 稳定性 | 示例 |
|---|---|---|---|
code | 程序判断分支 | 永久稳定,改名即为破坏性变更 | ARTICLE_TITLE_TOO_LONG |
message | 人看日志和提示 | 可随时改文案、可国际化 | "标题长度不能超过 100 个字符" |
details | 前端做字段级高亮 | 结构稳定,内容可变 | 定位到具体字段与原因 |
最常见的错误设计
前端写
if (res.data.msg === '标题太长') {...}—— 一旦你改文案或加句号,前端逻辑全部失效。永远用
code做判断,message只用于展示。
11.3 RFC 7807 / RFC 9457:Problem Details
标准化的错误格式,媒体类型为 application/problem+json,五个标准成员:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
{
"type": "https://api.example.com/problems/validation-error",
"title": "请求参数校验失败",
"status": 422,
"detail": "字段 title 长度 137 超过上限 100",
"instance": "/api/v1/articles",
"errors": [
{ "field": "title", "code": "max_length", "limit": 100 }
]
}
| 成员 | 含义 | 注意 |
|---|---|---|
type | 问题类型的 URI 标识 | 最好指向可读的文档页 |
title | 简短的人类可读摘要 | 同类问题应固定(不要每次不同) |
status | HTTP 状态码 | 与响应行保持一致 |
detail | 本次问题的具体说明 | 可变、可国际化 |
instance | 本次问题对应的具体 URI | 便于日志关联 |
版本提示
该格式最初是 RFC 7807(2016),2023 年被 RFC 9457 取代(把
Unprocessable Entity更名为Unprocessable Content等),媒体类型仍为application/problem+json,两者兼容。扩展成员(如上面的errors)是允许的。以官方最新文档为准。
十二、请求与响应设计细则
| 主题 | 规则 | 反例 |
|---|---|---|
Content-Type | 请求与响应都显式声明;UTF-8 明文写出 | 不声明靠猜、用 text/html 返回 JSON |
| 日期时间 | ISO 8601 + UTC + Z:2026-10-11T08:30:00Z | "2026/10/11 16:30"、本地时间、Unix 秒与毫秒混用 |
| 金额 | 整数最小货币单位(分)或字符串定点数 | 19.99 浮点相加出现 19.989999999999998 |
| ID | 不可枚举值:UUIDv7 / ULID / 雪花 ID;或至少对外暴露非自增 ID | 对外暴露自增 id,被爬虫遍历 /users/1..999999 |
| 布尔 | 用真布尔 true/false | "1" / "Y" / "yes" 混用 |
| 空值 | 未设置用 null,不省略字段或明确文档化省略规则 | 有时省略字段、有时 null,前端要写两套判断 |
| 枚举 | 用稳定字符串,不用序号 | status: 3(谁是 3?) |
| 数组空集合 | 返回 [] 而非 null | 前端 for (x of res.data.items) 崩溃 |
| 字段命名 | 全站统一 snake_case 或 camelCase | 同一响应里 user_id 与 userName 并存 |
| 分页/时间字段 | created_at 一旦发布不改名 | 改名 = 破坏性变更 |
| 敏感字段 | 密码、身份证、Token 永不返回 | 把 password_hash 一起序列化出去 |
时区三大坑
1. 存本地时间(
datetime无时区)→ 跨时区/夏令时直接错乱;2. 前端
new Date("2026-10-11 08:30:00")在 Safari 里可能返回Invalid Date(空格分隔不是标准格式);3. 数据库列用
TIMESTAMP(无时区)还是TIMESTAMPTZ(PostgreSQL 推荐)。统一做法:数据库存 UTC(PostgreSQL 用
timestamptz,MySQL 用DATETIME存 UTC),API 传 ISO 8601 带Z,只在前端展示时转本地时区。
十三、OpenAPI 规范
13.1 为什么需要接口文档
| 没有文档 | 有 OpenAPI 文档 |
|---|---|
| 前端靠问人、试错对接 | 生成 TypeScript 客户端,类型安全 |
| 接口改了没人知道 | CI 里 diff 出破坏性变更 |
| 测试手写请求 | 自动生成 Postman/Swagger 请求集合 |
| 新人 onboarding 靠口口相传 | 打开页面就能自测 |
13.2 最小可用 openapi.yaml
openapi: 3.0.3
info:
title: Blog API
version: 1.0.0
description: 博客系统示例 API
servers:
- url: https://api.example.com/api/v1
paths:
/articles:
get:
summary: 分页查询文章列表
parameters:
- name: status
in: query
schema: { type: string, enum: [draft, published] }
- name: limit
in: query
schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
responses:
'200':
description: 成功
content:
application/json:
schema:
type: object
properties:
data:
type: array
items: { $ref: '#/components/schemas/Article' }
'429':
description: 触发限流
headers:
Retry-After:
schema: { type: integer }
post:
summary: 创建文章
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/ArticleCreate' }
responses:
'201':
description: 已创建
headers:
Location:
schema: { type: string }
content:
application/json:
schema: { $ref: '#/components/schemas/Article' }
'422':
description: 参数语义不合法
content:
application/problem+json:
schema: { $ref: '#/components/schemas/Problem' }
components:
schemas:
Article:
type: object
required: [id, title, status, created_at]
properties:
id: { type: string, format: uuid }
title: { type: string, maxLength: 100 }
body: { type: string }
status: { type: string, enum: [draft, published] }
created_at: { type: string, format: date-time }
ArticleCreate:
type: object
required: [title]
properties:
title: { type: string, maxLength: 100 }
body: { type: string }
Problem:
type: object
properties:
type: { type: string }
title: { type: string }
status: { type: integer }
detail: { type: string }
13.3 Swagger UI 与工具链
| 工具 | 作用 |
|---|---|
| Swagger UI | 把 openapi.yaml 渲染成可交互页面,能直接「Try it out」发请求 |
| Redoc | 更适合阅读的三栏文档站 |
| openapi-typescript / NSwag | 从规范生成客户端类型与 SDK |
| Spectral | 规范 linter,检查命名、必填 description 等 |
# 本地起一个 Swagger UI 预览(Docker 方式,官方镜像)
docker run --rm -p 8080:8080 \
-e SWAGGER_JSON=/spec/openapi.yaml \
-v "$PWD:/spec" \
swaggerapi/swagger-ui
# 打开 http://localhost:8080 即可交互式试用接口
文档即代码
把
openapi.yaml提交到仓库,在 CI 里做两件事:1.
spectral lint openapi.yaml保证规范质量;2. 与上一版本 diff,检测破坏性变更(删字段、加必填、改类型)并在 PR 里评论。
这比「改了代码忘了改文档」可靠得多。
十四、API 演进与兼容性
14.1 什么是破坏性变更
| 变更 | 是否破坏性 | 说明 |
|---|---|---|
| 新增可选请求参数 | ✅ 兼容 | 老客户端不传时行为不变 |
| 新增响应字段 | ✅ 兼容 | 前提:客户端忽略未知字段(要写进规范) |
| 新增枚举值 | ⚠️ 可能破坏 | 客户端 switch 没有 default 就会崩 |
| 删除响应字段 | ❌ 破坏性 | 必须走废弃流程 |
| 字段改名 / 改类型 | ❌ 破坏性 | id: number → string 尤其危险(JS 大整数精度) |
| 把可选参数改为必填 | ❌ 破坏性 | |
收紧校验规则(maxLength: 100 → 50) | ❌ 破坏性 | 老数据可能提交失败 |
| 改变错误码 | ❌ 破坏性 | 客户端按 code 分支判断 |
| 改变默认分页大小 | ⚠️ 可能破坏 | 影响客户端分页逻辑 |
14.2 优雅废弃字段的流程
{
"id": "uuid-1",
"user_name": "alice",
"username": "alice",
"_deprecated": {
"user_name": {
"removed_in": "v3",
"sunset": "2027-01-01",
"replacement": "username",
"doc": "https://api.example.com/docs/migrations#user_name"
}
}
}
四步走:
- 双写双读:新字段与旧字段同时返回,值保持一致;
- 文档 + 响应头标注:
Deprecation、Sunset、Link rel="successor-version"; - 监控使用率:按客户端(
User-Agent/ API Key)统计旧字段调用量,接近 0 才动手; - 到期删除:删除前发公告,并给至少一个发布周期的缓冲。
不要靠「发个通知」就删字段
你需要数据证明没人用。很多团队的废弃失败都源于「以为没人用了」,结果上线当天某个内部报表脚本崩了。
14.3 Idempotency-Key:处理重复提交
问题:用户点击「支付」后网络超时,客户端重试 → 服务端处理了两次 → 重复扣款。
方案:客户端为同一次业务意图生成一个唯一键,重复提交带同一个键:
POST /api/v1/payments HTTP/1.1
Idempotency-Key: 8f14e45f-ea8a-4b1c-9f4d-1c0b7b3b9d21
Content-Type: application/json
{"order_id":"order-77","amount_cents":1999,"currency":"CNY"}
服务端逻辑(Redis 伪代码 + SQL):
# 服务端幂等处理(Python 伪代码,逻辑与语言无关)
def create_payment(idem_key: str, body: dict):
if not idem_key:
raise ApiError(428, "PRECONDITION_REQUIRED", "缺少 Idempotency-Key")
# 1) 先占坑:SET NX 保证并发下只有一个请求能进入业务逻辑
# value 先放 "PROCESSING",标记为进行中
acquired = redis.set(f"idem:{idem_key}", "PROCESSING", nx=True, ex=86400)
if not acquired:
cached = redis.get(f"idem:{idem_key}")
if cached == "PROCESSING":
# 2) 同一键正在处理中,让客户端稍后重试(避免重复执行 + 给出一致语义)
raise ApiError(409, "REQUEST_IN_PROGRESS", "相同请求正在处理,请稍后重试")
# 3) 已完成:直接回放首次的结果(状态码与响应体都保存过)
return json.loads(cached)
try:
# 4) 业务写入:靠数据库唯一约束兜底,不只是靠 Redis
payment_id = db.execute(
"""INSERT INTO payments (id, order_id, amount_cents, currency, idem_key)
VALUES (gen_random_uuid(), %s, %s, %s, %s)
ON CONFLICT (idem_key) DO NOTHING
RETURNING id""",
(body["order_id"], body["amount_cents"], body["currency"], idem_key),
)
result = {"id": payment_id, "status": "created"}
redis.set(f"idem:{idem_key}", json.dumps(result), ex=86400) # 保存结果供回放
return result
except Exception:
redis.delete(f"idem:{idem_key}") # 失败要释放占坑,否则重试永远拿到 409
raise
幂等键的三个设计要点
1. 键由客户端生成(UUID v4),服务端只负责去重;
2. 必须设置过期时间(24 小时量级),否则存储无限增长;
3. 数据库唯一索引兜底:
UNIQUE (idem_key)。Redis 会丢数据,唯一约束不会。
十五、限流与配额
15.1 为什么必须限流
| 风险 | 说明 |
|---|---|
| 恶意刷接口 | 撞库、爬虫、短信轰炸(直接烧钱) |
| 客户端 bug | while(true) 重试把数据库打满 |
| 热点事件 | 秒杀、发布会,流量瞬时涨 100 倍 |
| 公平性 | 单个租户占满资源,其他租户饿死 |
15.2 令牌桶与漏桶
令牌桶(Token Bucket):以固定速率 往容量为 的桶里放令牌,请求消耗 1 个令牌,桶空则拒绝。
特点:允许突发(只要桶里有积攒的令牌,短时高并发能通过),是绝大多数 API 网关的实现方式。
漏桶(Leaky Bucket):请求先入队列,以恒定速率流出。
特点:输出恒定平滑,不允许突发,超出队列容量即拒绝。适合保护能力固定的下游(如第三方短信接口)。
| 对比项 | 令牌桶 | 漏桶 |
|---|---|---|
| 突发流量 | ✅ 允许(有上限) | ❌ 不允许 |
| 输出速率 | 可变,平均受限于 | 恒定 |
| 实现复杂度 | 低(记 tokens 与 last_refill) | 需队列 |
| 典型用途 | 对外 API 限流 | 流量整形、保护下游 |
import time
class TokenBucket:
"""令牌桶限流器:单实例内存版,多实例需换成 Redis + Lua 保证原子性"""
def __init__(self, rate: float, capacity: int):
self.rate = rate # 每秒补充的令牌数
self.capacity = capacity # 桶容量,即允许的突发上限
self.tokens = float(capacity)
self.last = time.monotonic() # 用单调时钟,避免系统时间被调整时出错
def allow(self, cost: int = 1) -> bool:
now = time.monotonic()
# 惰性补充:不用定时器,请求到来时按流逝时间算应补多少令牌
self.tokens = min(self.capacity, self.tokens + (now - self.last) * self.rate)
self.last = now
if self.tokens >= cost:
self.tokens -= cost
return True
return False
bucket = TokenBucket(rate=10, capacity=30) # 平均 10 rps,允许瞬时 30 次
print([bucket.allow() for _ in range(35)].count(True)) # 30:桶被一次抽干
time.sleep(3.0) # 等 3 秒
print([bucket.allow() for _ in range(35)].count(True)) # 30:补满后再抽干
15.3 429 与相关响应头
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1760000000
Content-Type: application/problem+json
{
"type": "https://api.example.com/problems/rate-limited",
"title": "请求过于频繁",
"status": 429,
"detail": "每分钟最多 1000 次请求,请在 30 秒后重试"
}
| 头 | 含义 | 注意事项 |
|---|---|---|
Retry-After | 多少秒或 HTTP 日期后可重试 | 标准头,429/503 应带上;客户端据此退避 |
X-RateLimit-Limit | 窗口内总配额 | 自定义约定,非 RFC 标准 |
X-RateLimit-Remaining | 剩余可用次数 | 前端可据此提前提示 |
X-RateLimit-Reset | 窗口重置时间 | 用 Unix 秒还是 HTTP 日期要文档化 |
限流的三条实践建议
1. 限流维度要选对:按 API Key / 用户 ID / IP + 端点组合。纯按 IP 会误伤 NAT 后的整个公司;
2. 区分「限流」和「配额」:限流是每秒速率(防瞬时打爆),配额是每月总量(商业套餐)。两者应分别返回不同的
code;3. 客户端必须实现指数退避 + 抖动,否则所有客户端在同一毫秒重试,形成「惊群」:
其中 是 的随机抖动。
十六、完整示例:博客系统 REST API 设计
16.1 资源与端点全表
| 资源 | 方法 | 路径 | 成功码 | 错误码 | 说明 |
|---|---|---|---|---|---|
| 文章集合 | GET | /api/v1/articles | 200 | 400(参数非法) | 支持 status/author_id/q/sort/fields/limit/cursor |
| 文章集合 | POST | /api/v1/articles | 201 + Location | 400·401·403·422·429 | 需 Idempotency-Key |
| 单篇文章 | GET | /api/v1/articles/{id} | 200 | 404 | 草稿仅作者可见,他人得 404(不泄漏存在性) |
| 单篇文章 | PUT | /api/v1/articles/{id} | 200 | 401·403·404·409·412·422 | 整体替换;带 If-Match 做乐观锁 |
| 单篇文章 | PATCH | /api/v1/articles/{id} | 200 | 400·404·409·415 | 局部更新,媒体类型用 application/merge-patch+json |
| 单篇文章 | DELETE | /api/v1/articles/{id} | 204 | 403·404 | 幂等:重复删除返回 404,状态一致 |
| 单篇文章 | HEAD | /api/v1/articles/{id} | 200 | 404 | 探活/查是否存在,无响应体 |
| 文章集合 | OPTIONS | /api/v1/articles | 204 + Allow | — | 返回 Allow: GET, POST, OPTIONS |
| 发布动作 | POST | /api/v1/articles/{id}/publication | 202 | 403·404·409(已发布) | 异步:返回任务 ID |
| 评论集合 | GET | /api/v1/articles/{id}/comments | 200 | 404 | 文章不存在时 404 |
| 评论集合 | POST | /api/v1/articles/{id}/comments | 201 + Location | 401·404·422·429 | |
| 单条评论 | DELETE | /api/v1/comments/{id} | 204 | 403·404 | 作者或管理员可删 |
| 当前用户 | GET | /api/v1/me | 200 | 401 | 从 Token 解析,不用传 ID |
| 健康检查 | GET | /healthz | 200 | 503 | 不带版本前缀,供负载均衡探活 |
16.2 状态码与错误码对照(错误响应全表)
| HTTP | error.code | 触发场景 | 客户端应做什么 |
|---|---|---|---|
400 | MALFORMED_JSON | 请求体不是合法 JSON | 修 bug,不要重试 |
400 | INVALID_QUERY_PARAM | limit=abc、sort=secret_col | 修正参数 |
401 | MISSING_CREDENTIALS | 缺 Authorization 头 | 跳转登录 |
401 | TOKEN_EXPIRED | Token 过期 | 用 refresh token 换新 |
403 | INSUFFICIENT_SCOPE | Token 有效但缺 articles:write 权限 | 提示无权限 |
404 | ARTICLE_NOT_FOUND | ID 不存在,或对无权限者隐藏 | 提示不存在 |
405 | METHOD_NOT_ALLOWED | 对 /articles/{id} 用了 POST | 修正方法(响应带 Allow) |
409 | ARTICLE_ALREADY_PUBLISHED | 重复发布 | 刷新状态 |
409 | REQUEST_IN_PROGRESS | 相同 Idempotency-Key 正在处理 | 稍后重试 |
412 | VERSION_MISMATCH | If-Match 与当前 ETag 不符 | 重新拉取后合并 |
415 | UNSUPPORTED_MEDIA_TYPE | 发 text/xml 却只接受 JSON | 改 Content-Type |
422 | TITLE_TOO_LONG | 标题超过 100 字 | 提示用户修改 |
422 | DATE_RANGE_INVALID | end_date < start_date | 提示用户修改 |
429 | RATE_LIMITED | 超过速率限制 | 按 Retry-After 退避重试 |
500 | INTERNAL_ERROR | 未捕获异常 | 可重试一次,带上 request_id 报障 |
503 | SERVICE_UNAVAILABLE | 维护/过载 | 按 Retry-After 重试 |
16.3 端到端 cURL 演示(可直接执行)
BASE=https://api.example.com/api/v1
TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example
# 1) 查询已发布文章,只要必要字段,按创建时间倒序
curl -sS -G "$BASE/articles" \
--data-urlencode "status=published" \
--data-urlencode "sort=-created_at" \
--data-urlencode "fields=id,title,created_at" \
--data-urlencode "limit=20" \
-H "Accept: application/json" | jq .
# 2) 创建文章(带幂等键,超时重试也不会重复创建)
curl -sS -X POST "$BASE/articles" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"title":"HTTP 笔记","body":"正文...","status":"draft"}' \
-D - -o /tmp/created.json # -D - 打印响应头,确认 Location 与 ETag
cat /tmp/created.json | jq .
# 3) 乐观锁更新:把上一步返回的 ETag 填进来;若期间被别人改过会得到 412
ETAG='"33a64df5"'
curl -sS -X PATCH "$BASE/articles/42" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/merge-patch+json" \
-H "If-Match: $ETAG" \
-d '{"status":"published"}' | jq .
# 4) 条件请求省流量:内容没变时服务端返回 304,无响应体
curl -sS -o /dev/null -w "%{http_code}\n" "$BASE/articles/42" \
-H "If-None-Match: $ETAG"
# 5) 删除(幂等:再删一次得到 404,但服务端状态一致)
curl -sS -X DELETE "$BASE/articles/42" \
-H "Authorization: Bearer $TOKEN" -o /dev/null -w "%{http_code}\n"
16.4 一个最小的实现骨架(Node.js + Express)
// 说明:为聚焦 HTTP 语义,数据存在内存里;生产环境换成数据库即可
import express from 'express';
import { randomUUID } from 'node:crypto';
const app = express();
app.use(express.json({ limit: '1mb' })); // 限制体积,防止超大 JSON 打爆内存
const articles = new Map(); // id -> { id, title, status, etag, created_at }
const parseETag = req => req.get('If-Match');
app.get('/api/v1/articles', (req, res) => {
const limit = Math.min(Math.max(parseInt(req.query.limit ?? '20', 10) || 20, 1), 100);
const all = [...articles.values()]
.filter(a => !req.query.status || a.status === req.query.status)
.slice(0, limit);
res.json({ data: all, pagination: { limit, has_more: articles.size > limit } });
});
app.post('/api/v1/articles', (req, res) => {
const { title, body = '', status = 'draft' } = req.body ?? {};
// 语法层问题 → 400
if (typeof title !== 'string') {
return res.status(400).json({ error: { code: 'MALFORMED_JSON', message: 'title 必须是字符串' } });
}
// 语义层问题 → 422
if (title.length === 0 || title.length > 100) {
return res.status(422).json({
error: {
code: 'TITLE_TOO_LONG',
message: '标题长度必须在 1~100 个字符之间',
details: [{ field: 'title', actual: title.length, limit: 100 }],
},
});
}
const id = randomUUID(); // 不可枚举 ID,避免被遍历
const doc = { id, title, body, status, etag: `"${randomUUID().slice(0, 8)}"`,
created_at: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z') };
articles.set(id, doc);
res.status(201) // 201 必须带 Location
.location(`/api/v1/articles/${id}`)
.set('ETag', doc.etag)
.json(doc);
});
app.patch('/api/v1/articles/:id', (req, res) => {
const doc = articles.get(req.params.id);
if (!doc) return res.status(404).json({ error: { code: 'ARTICLE_NOT_FOUND', message: '文章不存在' } });
// 乐观锁:客户端带 If-Match 且与当前版本不符 → 412
const ifMatch = parseETag(req);
if (ifMatch && ifMatch !== doc.etag) {
return res.status(412).json({ error: { code: 'VERSION_MISMATCH', message: '资源已被修改,请重新获取' } });
}
Object.assign(doc, req.body ?? {});
doc.etag = `"${randomUUID().slice(0, 8)}"`; // 每次修改换新 ETag
res.set('ETag', doc.etag).json(doc);
});
app.delete('/api/v1/articles/:id', (req, res) => {
// 幂等:删除不存在或已删除的资源都返回 404,服务端状态一致
if (!articles.delete(req.params.id)) {
return res.status(404).json({ error: { code: 'ARTICLE_NOT_FOUND', message: '文章不存在' } });
}
res.status(204).end(); // 204 不能有响应体
});
// 统一兜底:任何未匹配路径 → 404;未捕获异常 → 500(不泄漏堆栈)
app.use((req, res) => res.status(404).json({ error: { code: 'ROUTE_NOT_FOUND', message: '接口不存在' } }));
app.use((err, req, res, _next) => {
console.error(err); // 服务端记完整堆栈
res.status(500).json({ error: { code: 'INTERNAL_ERROR', message: '服务器内部错误',
request_id: req.get('X-Request-Id') ?? null } });
});
app.listen(3000, () => console.log('http://localhost:3000/api/v1/articles'));
# 运行(需 Node.js 18+,package.json 里加 "type": "module")
npm i express
node server.js
curl -sS -X POST localhost:3000/api/v1/articles \
-H 'Content-Type: application/json' \
-d '{"title":"第一篇"}' -D - | head -5
十七、常见坑
十个高频错误
1. 一律返回
200,错误塞在响应体里 → 网关重试策略、监控告警、CDN 缓存全部失灵。2.
401与403混用 → 前端陷入无限刷新 Token,或用户不知道要登录。3.
201不带Location→ 客户端只能靠响应体猜新资源地址。4.
204带了响应体 → 部分客户端/代理会挂起等待,或直接报协议错误。5.
DELETE第二次返回500→ 应该是404;调用方无法区分「已删除」与「服务器炸了」。6. 把 ID 自增暴露给外部 → 竞品通过
/users/1..999999遍历出全部用户量与增长曲线。7. 金额用浮点 →
0.1 + 0.2 !== 0.3,对账永远差一分钱。用整数分。8. 分页
limit无上限 →?limit=99999999一次性 OOM。9.
sort/fields直接拼 SQL → 注入。必须白名单。10. 返回过于详细的错误 →
"column 'password_hash' does not exist"直接暴露表结构。生产环境只回code + request_id。
自检清单(上线前过一遍)
- [ ] 每个端点的成功码、错误码都在 OpenAPI 里写清楚了吗?
- [ ] 时间字段都是 ISO 8601 UTC 带
Z吗?- [ ] 金额是整数最小单位吗?
- [ ] 集合类响应空结果返回
[]而不是null吗?- [ ] 写操作支持
Idempotency-Key吗(至少支付/下单类必须支持)?- [ ] 限流阈值、
429、Retry-After都实现了吗?- [ ] 错误信息里没有堆栈、SQL、内网 IP、主机名吧?
十八、练习题
- 基础题:为一个「图书借阅系统」设计 URL 与 HTTP 方法。至少包含:图书列表(支持按分类筛选、按书名搜索)、单本图书详情、创建借阅记录、归还图书、查询某用户的借阅历史。写出每个端点的完整方法 + 路径 + 成功状态码 + 主要错误状态码。
- 基础题:判断下列写法的状态码,并说明原因:(a) 用错误密码登录;(b) 已登录的普通用户访问
/admin/users;(c)POST /articles时title为空字符串;(d)PUT /articles/999(不存在);(e) 客户端以 200 QPS 请求一个限额 50 QPS 的接口。 - 进阶题:某表有 800 万行,
created_at上有索引。现有查询
SELECT * FROM articles ORDER BY created_at DESC LIMIT 20 OFFSET 400000;
请用本笔记的公式计算扫描行数与读放大倍数;给出改写为游标分页的 SQL(结果必须稳定,假设 created_at 可能重复),并说明为什么必须同时按 (created_at, id) 排序。
- 进阶题:设计一个「转账」接口。要求:(a) 网络超时重试不会重复扣款;(b) 两个并发请求同时转出超过余额的金额时,只能成功一个;(c) 说明你会用
Idempotency-Key、数据库唯一约束、以及什么锁机制,并解释各自的职责边界。 - 思考题:你的团队要把
POST /articles/{id}/publish改成「资源化」的POST /articles/{id}/publication。这算破坏性变更吗?如果算,如何在不打断现有客户端的前提下完成迁移?请给出至少两种技术方案及其代价。
十九、FAQ
Q1:一定要用 REST 吗?GraphQL 和 gRPC 什么时候更合适?
A:不是必须。判断依据是消费方和瓶颈在哪:
| 场景 | 更合适的选择 | 原因 |
|---|---|---|
| 公开 API、第三方集成 | REST | 通用、工具链成熟、缓存友好 |
| 前端页面字段需求多变,移动端流量敏感 | GraphQL | 一次请求取所需字段,避免过度获取与多次往返 |
| 内部微服务间高频调用 | gRPC | HTTP/2 + Protobuf,序列化开销低、强类型契约 |
| 简单 CRUD、后台管理 | REST | 学习与维护成本最低 |
实践中常见组合:对外 REST + 内部 gRPC + BFF 层聚合。
Q2:PUT 和 PATCH 到底怎么选?
A:PUT 是整体替换语义——没传的字段应被置为 null/默认值;PATCH 是局部修改——只改传了的字段。常见错误是用 PUT 却只更新部分字段,导致客户端以为的「替换」与服务端的「合并」语义不一致。
PATCH 的标准媒体类型是 application/merge-patch+json(RFC 7386,JSON Merge Patch)。若需要显式删除字段,可考虑 application/json-patch+json(RFC 6902)。用 PATCH 时的推荐做法:
PATCH /api/v1/articles/42 HTTP/1.1
Content-Type: application/merge-patch+json
If-Match: "33a64df5"
Q3:分页到底该选 offset 还是 cursor?能都提供吗?
A:按场景选:后台表格用 offset/page(需要跳页、需要总数);信息流、公开 API 用 cursor(性能和一致性都好)。可以都提供,但必须二选一互斥,同时在响应里明确回显用了哪种,否则客户端会拼出 ?offset=40&cursor=xxx 这种未定义行为。
小数据量(< 10 万行)用 offset 完全没问题,不必过度设计。
Q4:怎么判断我的 API 设计「足够好」?
A:四个可操作的自检:
- 盲猜测试:把 API 列表给没参与设计的同事,让他猜每个端点做什么——正确率应 > 80%;
- 状态码测试:随机抽 5 个端点,说出「失败时会返回哪些状态码」,你能不查文档答出来吗;
- 版本化测试:如果明天要改一个字段类型,你的迁移计划是什么(双写?新版本?);
- 错误可定位性:只给一个
request_id,你能在日志里定位到是哪个请求、哪个参数的问题吗。
相关笔记
- 计算机网络——HTTP 协议本身(报文、TCP、TLS)的底层原理
- 前端-04-浏览器与HTTP——从调用方视角看缓存、跨域与 Cookie
- 后端-06-认证与授权——
401/403、JWT、OAuth 2.0 的完整实现 - 后端-09-后端安全与性能——注入、XSS、限流与缓存的工程实践
- 后端-02-Nodejs与Express——用 Express 落地本文的路由与中间件设计
参考来源
- MDN Web Docs(中文):HTTP 请求方法、HTTP 响应状态码、HTTP 标头
- RFC 9110《HTTP Semantics》(方法、状态码、条件请求的权威定义):<https://www.rfc-editor.org/rfc/rfc9110.html>
- RFC 9111《HTTP Caching》(缓存与
Vary):<https://www.rfc-editor.org/rfc/rfc9111.html> - RFC 9112《HTTP/1.1》(报文格式):<https://www.rfc-editor.org/rfc/rfc9112.html>
- RFC 9457《Problem Details for HTTP APIs》(取代 RFC 7807):<https://www.rfc-editor.org/rfc/rfc9457.html>
- RFC 3339《Date and Time on the Internet: Timestamps》(ISO 8601 时间格式):<https://www.rfc-editor.org/rfc/rfc3339.html>
- RFC 7386《JSON Merge Patch》:<https://www.rfc-editor.org/rfc/rfc7386.html>
- OpenAPI Specification 3.0.3:<https://spec.openapis.org/oas/v3.0.3.html>
- 说明:
swagger.io与dev.mysql.com等站点从中国大陆访问可能不稳定;规范文本以上面的spec.openapis.org与 IETF RFC 页面为准。版本敏感内容(OpenAPI 版本号、各框架行为)请以官方最新文档为准。