w wyl123ly 的博客
MD

后端-01-HTTP与RESTfulAPI设计

57 KB 2026.10.11 原文件

后端-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        ← 绝对不要这样设计

四个具体后果:

  1. 可被预取:浏览器、搜索引擎爬虫、微信/钉钉等 IM 的消息预览都会主动抓取链接,用户没点也可能触发删除;
  2. 可被重放:GET 是幂等的、可缓存的,中间代理和 CDN 可能把响应缓存下来,甚至命中缓存导致「以为删了其实没删」;
  3. 泄漏到日志与 Referer:URL 会被完整记录在 Nginx access log、浏览器历史、Referer 头里。GET /transfer?to=xxx&amount=1000 等于把操作参数公开;
  4. 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 重点状态码速查

状态码名称什么时候返回关键细节
200OK通用成功:查询、更新后返回新对象幂等与一次性操作都可用
201CreatedPOST 成功创建资源必须带 Location 头,响应体可含新资源
202Accepted已接受但异步处理返回任务 ID 供轮询
204No Content成功但无响应体:DELETE、PUT 无内容返回不能有响应体,也别设 Content-Type
206Partial Content断点续传/音视频拖动与 Range/Content-Range 配合
301Moved Permanently域名或路径永久迁移浏览器会长期缓存,测试期慎用
302Found临时跳转(如未登录跳登录页)历史上部分客户端会把 POST 改 GET
303See OtherPOST 后跳转到结果页(PRG 模式)明确要求用 GET 访问新地址
304Not Modified条件请求命中,内容未变不能有响应体;配合 ETag/Last-Modified 省流量
400Bad Request请求报文本身坏了:JSON 语法错、缺必填字段泛化的客户端错误
401Unauthorized未认证:没带或带了无效凭证必须带 WWW-Authenticate 头
403Forbidden已认证但无权限重试无用,别再登录
404Not Found资源不存在,或故意对无权限者隐藏存在性路径正确但对象不存在
405Method Not Allowed路径存在但不支持该方法必须带 Allow 头
406Not AcceptableAccept 要求的类型都不支持少见,但正确
409Conflict与当前资源状态冲突:唯一键重复、乐观锁版本不符业务冲突首选
412Precondition FailedIf-Match/If-Unmodified-Since 失败HTTP 层的乐观锁
415Unsupported Media TypeContent-Type 不支持(如要求 JSON 却发 text/xml)与 406 是一对
422Unprocessable Content报文语法正确但语义不合法校验失败的最佳选择
428Precondition Required要求带 If-Match 才允许修改强制乐观并发
429Too Many Requests触发限流必须带 Retry-After
500Internal Server Error未捕获异常、空指针、SQL 报错绝不能把堆栈返回给客户端
502Bad Gateway反向代理连不上/收到无效响应后端进程崩了或端口不对
503Service Unavailable主动拒绝:过载保护、停机维护带 Retry-After,配合健康检查摘流量
504Gateway Timeout代理等后端超时通常需要排查慢查询/慢依赖

5.3 401 与 403 的区别

对比项401 Unauthorized403 Forbidden
含义你没有证明身份身份已知,但不被允许
触发场景无 Authorization 头、Token 过期、签名错普通用户访问 /admin、越权访问他人订单
客户端该做什么去登录 / 刷新 Token 后重试不要重试,提示「无权访问」
必备响应头WWW-Authenticate: Bearer realm="api"无强制要求
常见错误权限不足返回 401 → 前端陷入「刷新 Token → 再失败 → 再刷新」死循环未登录返回 403 → 用户不知道要登录

记忆法

401 = 你是谁?403 = 我知道你是谁,但你不能进。

5.4 400 与 422 的区别

对比项400 Bad Request422 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 统一接口的四个子约束

  1. 资源的标识:每个资源有唯一 URI,/articles/42;
  2. 通过表述操作资源:客户端拿到的 JSON 是资源的表述(representation),不是资源本身;
  3. 自描述消息:报文自带 Content-Type、状态码等元数据,不需要额外上下文;
  4. 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 五条规则

  1. 用名词,不用动词:GET /articles 而不是 GET /getArticles
  2. 集合用复数:/articles、/users、/comments
  3. 层级表示从属关系:/articles/42/comments(文章 42 的评论)
  4. 用查询参数表达筛选、排序、分页:/articles?status=published&sort=-created_at&page=2
  5. 小写 + 连字符:/article-categories(不要 /ArticleCategories 或 /article_categories;路径大小写敏感,混用必然出事)

7.2 层级嵌套的深度控制

场景推荐不推荐原因
取某文章的评论GET /articles/42/commentsGET /comments?article_id=42从属关系明确,权限校验简单
取某评论的作者GET /comments/99/authorGET /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/publicationPOST /articles/42/publish
重置密码POST /users/42/password-resetsPOST /users/42/reset-password
转账POST /transfersPOST /accounts/1/transfer

结论

绝大多数「动作」都能重新建模成名词化的子资源(publication、password-resets、transfers)。实在别扭时用方案 B 也可接受——一致比纯粹更重要,但要在团队内统一并写进规范。


八、API 版本化策略对比

策略示例优点缺点适用
URL 路径GET /api/v1/articles直观、易调试、易做路由与灰度URL 变长;理论上违反「URI 标识资源」(不同 URL 是不同资源)最常用,推荐
请求头Accept-Version: v1 或自定义 X-API-Version: 1URL 干净;符合内容协商精神浏览器直接打开无法测试;缓存与网关需额外配置 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
实现 SQLLIMIT 20 OFFSET 40WHERE (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简短的人类可读摘要同类问题应固定(不要每次不同)
statusHTTP 状态码与响应行保持一致
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"
    }
  }
}

四步走:

  1. 双写双读:新字段与旧字段同时返回,值保持一致;
  2. 文档 + 响应头标注:Deprecation、Sunset、Link rel="successor-version";
  3. 监控使用率:按客户端(User-Agent / API Key)统计旧字段调用量,接近 0 才动手;
  4. 到期删除:删除前发公告,并给至少一个发布周期的缓冲。

不要靠「发个通知」就删字段

你需要数据证明没人用。很多团队的废弃失败都源于「以为没人用了」,结果上线当天某个内部报表脚本崩了。

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 为什么必须限流

风险说明
恶意刷接口撞库、爬虫、短信轰炸(直接烧钱)
客户端 bugwhile(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/articles200400(参数非法)支持 status/author_id/q/sort/fields/limit/cursor
文章集合POST/api/v1/articles201 + Location400·401·403·422·429需 Idempotency-Key
单篇文章GET/api/v1/articles/{id}200404草稿仅作者可见,他人得 404(不泄漏存在性)
单篇文章PUT/api/v1/articles/{id}200401·403·404·409·412·422整体替换;带 If-Match 做乐观锁
单篇文章PATCH/api/v1/articles/{id}200400·404·409·415局部更新,媒体类型用 application/merge-patch+json
单篇文章DELETE/api/v1/articles/{id}204403·404幂等:重复删除返回 404,状态一致
单篇文章HEAD/api/v1/articles/{id}200404探活/查是否存在,无响应体
文章集合OPTIONS/api/v1/articles204 + Allow—返回 Allow: GET, POST, OPTIONS
发布动作POST/api/v1/articles/{id}/publication202403·404·409(已发布)异步:返回任务 ID
评论集合GET/api/v1/articles/{id}/comments200404文章不存在时 404
评论集合POST/api/v1/articles/{id}/comments201 + Location401·404·422·429
单条评论DELETE/api/v1/comments/{id}204403·404作者或管理员可删
当前用户GET/api/v1/me200401从 Token 解析,不用传 ID
健康检查GET/healthz200503不带版本前缀,供负载均衡探活

16.2 状态码与错误码对照(错误响应全表)

HTTPerror.code触发场景客户端应做什么
400MALFORMED_JSON请求体不是合法 JSON修 bug,不要重试
400INVALID_QUERY_PARAMlimit=abc、sort=secret_col修正参数
401MISSING_CREDENTIALS缺 Authorization 头跳转登录
401TOKEN_EXPIREDToken 过期用 refresh token 换新
403INSUFFICIENT_SCOPEToken 有效但缺 articles:write 权限提示无权限
404ARTICLE_NOT_FOUNDID 不存在,或对无权限者隐藏提示不存在
405METHOD_NOT_ALLOWED对 /articles/{id} 用了 POST修正方法(响应带 Allow)
409ARTICLE_ALREADY_PUBLISHED重复发布刷新状态
409REQUEST_IN_PROGRESS相同 Idempotency-Key 正在处理稍后重试
412VERSION_MISMATCHIf-Match 与当前 ETag 不符重新拉取后合并
415UNSUPPORTED_MEDIA_TYPE发 text/xml 却只接受 JSON改 Content-Type
422TITLE_TOO_LONG标题超过 100 字提示用户修改
422DATE_RANGE_INVALIDend_date < start_date提示用户修改
429RATE_LIMITED超过速率限制按 Retry-After 退避重试
500INTERNAL_ERROR未捕获异常可重试一次,带上 request_id 报障
503SERVICE_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、主机名吧?


十八、练习题

  1. 基础题:为一个「图书借阅系统」设计 URL 与 HTTP 方法。至少包含:图书列表(支持按分类筛选、按书名搜索)、单本图书详情、创建借阅记录、归还图书、查询某用户的借阅历史。写出每个端点的完整方法 + 路径 + 成功状态码 + 主要错误状态码。
  2. 基础题:判断下列写法的状态码,并说明原因:(a) 用错误密码登录;(b) 已登录的普通用户访问 /admin/users;(c) POST /articles 时 title 为空字符串;(d) PUT /articles/999(不存在);(e) 客户端以 200 QPS 请求一个限额 50 QPS 的接口。
  3. 进阶题:某表有 800 万行,created_at 上有索引。现有查询

SELECT * FROM articles ORDER BY created_at DESC LIMIT 20 OFFSET 400000;

请用本笔记的公式计算扫描行数与读放大倍数;给出改写为游标分页的 SQL(结果必须稳定,假设 created_at 可能重复),并说明为什么必须同时按 (created_at, id) 排序。

  1. 进阶题:设计一个「转账」接口。要求:(a) 网络超时重试不会重复扣款;(b) 两个并发请求同时转出超过余额的金额时,只能成功一个;(c) 说明你会用 Idempotency-Key、数据库唯一约束、以及什么锁机制,并解释各自的职责边界。
  2. 思考题:你的团队要把 POST /articles/{id}/publish 改成「资源化」的 POST /articles/{id}/publication。这算破坏性变更吗?如果算,如何在不打断现有客户端的前提下完成迁移?请给出至少两种技术方案及其代价。

十九、FAQ

Q1:一定要用 REST 吗?GraphQL 和 gRPC 什么时候更合适?

A:不是必须。判断依据是消费方和瓶颈在哪:

场景更合适的选择原因
公开 API、第三方集成REST通用、工具链成熟、缓存友好
前端页面字段需求多变,移动端流量敏感GraphQL一次请求取所需字段,避免过度获取与多次往返
内部微服务间高频调用gRPCHTTP/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:四个可操作的自检:

  1. 盲猜测试:把 API 列表给没参与设计的同事,让他猜每个端点做什么——正确率应 > 80%;
  2. 状态码测试:随机抽 5 个端点,说出「失败时会返回哪些状态码」,你能不查文档答出来吗;
  3. 版本化测试:如果明天要改一个字段类型,你的迁移计划是什么(双写?新版本?);
  4. 错误可定位性:只给一个 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 版本号、各框架行为)请以官方最新文档为准。