RESTful API Design Principles — 全书拆解
RESTful API Design Principles — 全书拆解
30 秒导读: 这是一本 2026 年的实务教材,回答一个问题:怎么设计一个要给陌生人用很多年的 API(Application Programming Interface,两个程序隔着网络、按约定格式对话的那种约定)? 它的讲法是先讲历史(为什么 REST 赢了),再拆四个概念(怎么起名、怎么用 HTTP 方法、怎么组织返回的数据、怎么让调用方自己找到下一步), 最后补安全和性能两章生产必修课。真正的价值不在「最佳实践清单」——那种清单网上到处都是——而在每个做法背后的因果链: 这个决定防的是什么错、错的时候系统会变成什么样。
本组文档是我们重写的完整拆解,八章。读完不必看原书。
1. 这是谁在什么时候写的
| 作者 | Alex Rodriguez——软件架构师,UCLA 出身,从 90 年代 Web 早期入行;曾在 IBM 领导「数百个 Java EE 服务迁移到微服务」的平台现代化项目,后来加入眼科医疗器械公司 Alcon 做医疗设备与云的集成软件1 |
| 成书时间 | 2026 年,BPB Online 出版2 |
| 体裁 | 带结构说明、学习目标、章末选择题的教材,但例子全部取自真实世界(GitHub、Stripe、PagerDuty 的 API) |
| 利益相关 | 无。作者不卖框架、不卖网关,是纯粹的从业者视角 |
一个必须知道的转码瑕疵: 这本书的 EPUB 导航把第 1–7 章的文件名段全部错标成 "Introduction",真正的章名(Breaking Points、Resource Identification……)只在各章正文里。所以原书结构要按正文标题走,出处锚按 text/08–text/14 这些文件走,本组文档每章的脚注都给了文件和行号。
2. 全书一条主线(读完这一节,你就懂了这本书)
这本书是一条从头贯到尾的因果链——每一步都是被上一步逼出来的。下面把这条链完整走一遍——只看这一节,你也能把这本书讲给别人听。
① 先回答「为什么偏偏是 REST」:三十年里每个前任都撞了一堵墙
1990 年代的 CGI 让 Web 服务器(应请求、回数据的程序)能调外部程序,但每个请求 fork 出一个新进程(fork:复制出一个新进程)——当年的服务器只有 8–64 MB 内存、25–66 MHz 的单核 CPU,几百个进程同时抢这一台机器就把它压垮,管理僵尸进程成了系统管理员的日常3。 Java RMI 让对象跨网络像本地一样调用,但它只会说 Java;EJB 用规格换来企业级能力,却被容器重量拖垮;SOAP 用 XML 换来跨语言,却在巨头的战略收购里长成了臃肿的帝国——而 Web 的草根社区要的是简单、中立、开放4。 REST 赢的原因一句话:它没有发明新的对话规则,它就是 Web 本身的架构——Web 页面怎么用网址寻址、服务器怎么不记对话内容、响应怎么存下来下次直接复用,它对程序要求同样一套。所以天然跨语言、能穿过防火墙、巨头也锁不住它。
② 赢家的第一块基石:每个资源都有一个稳定的名字
REST 对外的表面是一张名词的地图,不是一串动作的清单。这里的资源是指 API 暴露给外面的东西——一个用户、一本书、一张订单;/books/{id} 是它的地址,动作全部交给 HTTP 方法。
名字要用名词、集合用复数(/users 一眼是一组用户)、复合词用连字符,层级关系写进 URI(浏览器地址栏里那种地址)的路径里——URI 我们当「资源的街道地址」用5。
而且API 一定会变——所以从一开始就要选一种版本策略(URL 里放 /v1、放进自定义头、放进媒体类型、放进查询参数——URL 问号后面那串「名字=值」),选哪种是权衡,不选是灾难。
③ 第二块基石:五个方法各有不可混用的分工
GET 只观察不改数据,所以它的响应能存下来下次直接用、能安全重试;POST 创建,重复一次就创建两份,绝不可存;PUT 整体替换(幂等,但载荷必须是完整资源)。
PATCH 只改指定的字段(字段,数据里的一项),载荷小四分之三,但可能不幂等;DELETE 抹除,幂等——删两次和删一次结果一样:都不存在6。
选错方法不是风格问题:把该用 PUT 的写成 POST,重试就会重复下单;GET 里藏副作用,存下来的响应会把副作用放大。两个调用方同时改一个资源时,只有 ETag + If-Match 的条件请求能拦住「最后写入赢」。
④ 第三块基石:返回的数据本身要长成「能直接用」的样子
一个资源表述的好坏可以逐级检查、逐级改好:键值从乱码改成人读得懂(可消费),再嵌套起来、用链接连上邻居(可组合),最后参数化到同时服务 Web 和手机(可适配)7。原书拿同一个资源连改四版给你看,每版解决上一版的哪个具体毛病——这是全书最有「手感」的一段。
⑤ 第四块基石:响应里带上「下一步的地图」(HATEOAS)
上面三层做完,客户端(调用你 API 的那一方)还是要知道每个端点的地址。HATEOAS 把这件事倒过来:服务器在响应里附上当前状态下合法的下一步链接——订单还是 pending 就给你 cancel 和 confirm 的链接,已发货就只给 track。客户端只认链接不认地址,服务器改了路径客户端也不坏8。这是 REST 理论里最纯也最常被跳过的约束,原书单独给它一章,连错误恢复链接、按时间和地区出现的有条件链接都讲了。
⑥ REST 的四条约束不管安全:把分层当第五条约束
认证(你是谁:Basic 换 Bearer/JWT)、授权(你能做什么:RBAC、ABAC 那几种权限分工)、加密(路上别人看不看得懂:TLS、mTLS)、日志(系统逐条记下的行为记录,出事能不能回放),这四件事靠分层系统里的中间件来做——网关挡在前面,业务代码不用重写9。
OAuth(一套授权标准)补上了「第三方程序替用户办事」的场景。
在这种标准里,用户点头后,第三方拿到一枚令牌,即访问通行证。
书里有一句实话:让 API 扩得动的那些性质(服务器不记对话、对外规则统一、响应可存下来复用),恰恰也让它成了最有诱惑力的攻击面。
⑦ 最后:性能是省出来的,规模是分出来的
单个请求要快:响应体用 Gzip 压掉大半(书里拿一个 15 个字的小例子,把压缩办法的每一步算给你看),只返回客户端点名的字段,集合拆成一页一页往回送(按位置翻页会错位,按书签翻页就稳)10。 系统要扛得住涨:先给一台机器加配置,很快,但越加越不划算,而且这台机器一崩全崩;再改成加机器数量,增长接近翻倍翻倍地涨,但运维的麻烦陡增。同一个 JWT 服务(一种带签名的电子通行证,第 06 章细讲),书里的演示数字从 2 核扛不住 100 个客户端,到 10 台实例稳定 6,000 RPS(每秒请求数)——这组对照表是全章的骨架11。单体和微服务则是这条线上的最后一站:不是优劣,是取舍。
⑧ 一句话收尾
设计 API 不是列端点,而是设计一份要和陌生人共处很多年的契约:名字要稳(标识)、动作要准(方法)、数据要能用(表述)、变化要能消化(版本与超媒体)、防线要分层(安全)、开销要抠(性能)、增长要分(规模)。八个拆解章,一章管其中一件事。
3. 章节地图
这张表不用记任何术语——每章名字后面,写的是「读完你能回答什么问题」。
| 章 | 读完你就能回答 |
|---|---|
| 01 断裂点:REST 是怎么赢的 | 为什么 CGI/RMI/EJB/SOAP 都退场了?REST 的六大约束到底约束了什么? |
| 02 资源标识:给资源起名字 | /users 和 /user 差在哪?API 改版时怎么让旧客户端不断? |
| 03 资源操作:五个 HTTP 方法 | 重复发同一个请求会发生什么?两个人同时编辑谁赢?PATCH 和 PUT 到底差在哪? |
| 04 资源表述:返回的数据长什么样 | 为什么有的 API 返回一看就能用、有的要对着文档猜?改一版坏数据分几步? |
| 05 资源状态管理:HATEOAS | 什么叫「超媒体驱动」?客户端不记 URL 怎么找到下一步?出错时谁来指路? |
| 06 API 安全 | Base64 为什么不算加密?JWT 凭什么不用查数据库?令牌丢了怎么办? |
| 07 性能与规模 | Gzip 凭什么能压掉一大半?为什么越加配置越不划算?什么时候该拆微服务? |
| 08 延伸阅读清单 | 想继续深入,原书推荐读哪些书、各补哪一块? |
推荐顺序: 01 → 02 → 03 → 04 → 05 → 06 → 07,这是原书的展开顺序;做过 Web 开发、只想查某个决定怎么定的,直接跳对应章,每章都自包含。08 是原书的书单章,我们给了取舍建议,可以最后读。
4. 这本书覆盖什么、不覆盖什么
覆盖(而且讲得比多数材料清楚)——读完你能回答:
- 为什么 REST 赢了:不是因为它先进,而是因为前任们各自撞死的墙是什么;
- 给资源命名和版本化的具体规则,以及每条规则防的是什么歧义;
- 五个 HTTP 方法的分工,以及幂等性(同样的请求重复发,结果和发一次一样)、缓存、冲突解决这些「选错方法就会爆」的机制。缓存,即响应存下来下次直接复用;
- 一个坏返回怎么逐级改成好返回(可消费/可组合/可适配三级台阶);
- HATEOAS 的机制与落地:标准格式、错误链接、条件链接、带版本号的链接约定;
- 安全的四个支柱(认证/授权/加密/日志)各自解决什么、各自的坑;
- Gzip 的内部原理(逐位演示)、字段过滤(客户端点名要哪些字段)、分页(一次只回一小段),以及纵向 vs 横向扩容的实测对照。
不覆盖(别指望在这本里找):
| 缺什么 | 说明 |
|---|---|
| REST 之外的世界 | gRPC、GraphQL、WebSocket 一个字没提;HTTP/2、HTTP/3 只出现在延伸阅读的书单里 |
| 攻防实战 | 安全章是概念巡览:OWASP API Top 10 只在书单里出现,注入、越权访问、限流没展开 |
| 工程化 | 契约测试、mock、OpenAPI 文档自动生成、CI/CD(自动化构建与部署)中的 API 环节都没讲 |
| 可复现的基准 | 第 7 章的压测表是教学演示数据(原书自己也这么定位),别拿去当容量规划的依据 |
| 平台向运维 | 多租户、配额计费、灰度发布、网关产品选型不在射程内 |
5. 我们的判断
判断(我们的,不是书里的): 这本书在这个书库里的正确定位是**「Web 后端/API」这条线的词汇表与判据库**。 它最值得带走的是两样东西:一是每个设计决定背后的防错对象(版本策略防的是「一次改动弄断所有客户端」,条件请求防的是「最后写入赢」), 二是第 1 章那种用「撞墙史」讲架构的方法——比直接背六大约束好记得多。 如果错,会错在: 如果读者的目标是把 API 跑起来而不是搞懂为什么这么设计,这本书的历史章和机制章会显得绕; 而且对已经有多年实战的人,第 6、7 章的深度可能不够(安全没有攻防、性能没有真实基准)。
判断(我们的,不是书里的): 书中所有演示数字(性能表、载荷大小、流量占比)都应按教学示意读,不要按测量结果读—— 比如「PATCH 比 PUT 省 75%」这类数,来自原书构造的单一样例,真实系统里能省多少,取决于字段的大小和数量。 如果错,会错在: 如果那些数字其实来自作者真实项目,我们把它当示意就低估了它们的参考价值——但书中没有任何交代出处的痕迹。
判断(我们的,不是书里的): 这本书 2026 年还在出,本身说明 REST 并没有像某些人预言的那样被 gRPC/GraphQL 取代; 书里「REST 是 Web 本身的架构」这个论点,是理解「为什么它生命力这么长」的最好入口。 如果错,会错在: 如果行业里「REST 已死」的进程其实正在加速(比如新兴的人工智能程序普遍绕过 REST、直接按固定格式调用内部功能),这本书的历史章就需要补一段新故事——但那是翻新时的活,不是现在。
6. 许诺兑现表
这份拆解里每一处「第 N 章讲」,都在这里记一行、逐行核过。
| 许诺在哪 | 许诺了什么 | 应兑现在哪 | 核过了吗 |
|---|---|---|---|
| 本页 §2 ① | 前任们各自撞死的墙是什么 | 01 §3 各节(CGI/RMI/EJB/SOAP 各一段) | ✓ |
| 本页 §2 ① | 六大约束到底约束了什么 | 01 §3「REST:六条约束」 | ✓ |
| 本页 §2 ② | 版本策略选哪种的权衡 | 02 §4 四种策略逐一对照 | ✓ |
| 本页 §2 ③ | ETag + If-Match 怎么拦住「最后写入赢」 | 03 §4「冲突:ETag 与 If-Match」全程演示 | ✓ |
| 本页 §2 ④ | 同一个资源连改四版的演示 | 04 §2–§4 三条滑动标尺 | ✓ |
| 本页 §2 ⑤ | 错误恢复链接、按时间地区出现的有条件链接 | 05 §5、§7 | ✓ |
| 本页 §2 ⑥ | 中间件挡在前面、业务代码不重写 | 06 §1「机场类比」与 §2–§5 | ✓ |
| 本页 §2 ⑦ | LZ77 + Huffman 逐位演示 | 07 §2「Gzip 两个阶段」 | ✓ |
| 本页 §2 ⑦ | JWT 服务的扩容对照表 | 07 §5 三张实测表 | ✓ |
01 §6 | 标识、操作、表述三章怎么接力 | 02、03、04 各章 §1 | ✓ |
02 §5 | PATCH 什么时候登场 | 03 §5 | ✓ |
03 §7 | 缓存规则在 HATEOAS 里怎么延续 | 05 §8、§9 | ✓ |
04 §6 | 链接在响应里放哪、怎么设计 | 05 §3–§4 | ✓ |
05 §9 | 性能与安全防线的具体做法 | 06 全章、07 §3–§5 | ✓ |
06 §6 | Gzip、分页这些性能工具的具体机制 | 07 §2–§4 | ✓ |
07 §7 | 原书书单里哪些值得优先读 | 08 全章 | ✓ |
拆解写于 2026-10-19,依据 2026 年英文版(BPB Online)。原始书籍文件不入库,本组文档是我们自己的重写;
每条引用都可用 node scripts/book-verify.mjs restful-api-design 回核。
Footnotes
-
出处:「About the Author」第 10 段(
text/02-fm-about-the-author.txt:10,搜「University of California, Los Angeles」)。原文交代了 UCLA 教育背景、90 年代本科入行、IBM 平台现代化项目与现任 Alcon。 ↩ -
出处:书卡元数据与
library/restful-api-design/chapters.json(publisher 为 BPB Online LLP,date 为 2026,ISBN 978-93-65891-409)。 ↩ -
出处:「CHAPTER 1 Breaking Points」
text/08-fm-introduction.txt:212(搜「8 and 64 MB of memory」),原文给了当时服务器的内存与 CPU 档位、典型配置 256–1024 个进程的上限,以及僵尸进程拖垮 CPU 的机制;:209(搜「CPU starvation」)讲了上下文切换与饿死。 ↩ -
出处:「CHAPTER 1 Breaking Points」
text/08-fm-introduction.txt:459(搜「did not play well with non-Java systems」)写 RMI 的互操作死穴;:486(搜「over-engineered」)写 EJB 被批过度设计;:812(搜「corporate interests」)写 SOAP 与 Web 草根气质的冲突;:902(搜「REST vs. SOAP」)写移动应用要求轻量无状态接口助推了 REST。 ↩ -
出处:「CHAPTER 2 Resource Identification」
text/09-fm-introduction.txt:67(搜「5 key naming conventions」),五条命名约定;:376(搜「/v1/resource」)起是四种版本策略。 ↩ -
出处:「CHAPTER 3 Resource Manipulation」
text/10-fm-introduction.txt:73(搜「impartial observer」,GET 如科学仪器、幂等)、:166(搜「While GET observes, POST creates」)、:465(搜「replacement re-defines」)、:752(搜「surgical precision」)、:1157(搜「goes poof」,DELETE 幂等、删两次结果相同)。 ↩ -
出处:「CHAPTER 4 Resource Representation」
text/11-fm-introduction.txt:64(搜「sliding scale」),原书明确说把资源沿一条质量滑动标尺逐级改进;三个品质的结构见:48–:56。 ↩ -
出处:「CHAPTER 5 Resource State Management」
text/12-fm-introduction.txt:70(搜「no prior knowledge beyond an initial URI」),Fielding 的要求:除初始 URI 外不得有任何先验知识,状态转移全靠响应里的选择。 ↩ -
出处:「CHAPTER 6 API Security」
text/13-fm-introduction.txt:35(搜「a fifth REST constraint called layering」),作者明确把分层称为第五条约束,让中间件做认证、授权、加密、监控;机场类比见:38。 ↩ -
出处:「CHAPTER 7 Performance and Scale」
text/14-fm-introduction.txt:79(搜「Original: HelloHelloWorld」)起是 LZ77 + Huffman 的逐位演示;:539(搜「over-fetching」)、:560(搜「offset」)、:593(搜「cursor」)是过滤与分页。 ↩ -
出处:「CHAPTER 7 Performance and Scale」
text/14-fm-introduction.txt:722(搜「2-core CPU」)、:823(4 核)、:924(8 核)、:1120(2 实例)、:1193(4 实例)、:1266(10 实例)六张对照表。 ↩