RESTful Web Clients：基于超媒体的可复用客户端

强大的基于Web的REST和超媒体风格的API变得日益普遍，但很多开发者却依赖定制的客户端代码，并没有将相同的技术和模式应用到超媒体客户端中。通过这本实践性很强的指导书，你将学到如何将一次性的（客户端）实现转化为具有稳定性、灵活性和可重用性的通用客户端应用。为了阐述如何构建有效的基于超媒体的客户端应用，作者Mike Amundsen提供了许多背景广泛且容易理解的例子、生动的对话和清晰的建议。沿着这条路径，你将学到如何有效利用构成Web基础的基本原则。
* 将仅含HTML的Web应用转换为JSON API服务
* 克服维护普通JSON风格客户端应用的挑战
* 使用表述器模式将输出格式与内部对象模型解耦
* 探索使用HAL（超文本应用语言）构建的客户端应用
* 用请求、解析、等待循环（RPW）模式解决可重用客户端问题
* 理解使用Siren内容类型构建客户端应用的利弊
* 通过采用一种与时俱进的设计美学来处理API的版本化
* 比较JSON、HAL、Siren和Collection JSON客户端对“对象/地址/动作”挑战的处理方式
* 打造可以消费多个服务的单一客户端应用

 

Web开发领域的REST运动已经进行了很多年了，在REST的Richardson成熟度模型提出后，第3级——HATEOAS的应用——仍然没有得到广泛应用。事实上，其中一个难点在于客户端如何支持HATEOAS。之前很多REST相关书籍聚焦于如何打造服务端的RESTful API，本书则着重研究RESTful客户端，介绍了如何把一个针对服务端规约硬编码的定制客户端重构为一个支持HATEOAS的通用客户端，并提供了多格式支持、超媒体类型、版本化、微服务等相关问题的全面指导。本书附有所有样例代码的GitHub地址，方便读者快速理解和实践。本书适合Web应用开发者，尤其适合希望Web应用程序的服务端与客户端能够独立演化的Web架构师。

作为国际知名的作家和演说家，Mike Amundsen在全球各地咨询和研讨网络架构、Web开发和其他议题。而作为CA Technologies API学院的架构总监，他与公司致力于提供Web API方面的洞见，以便可以最大限度地利用面向消费者和企业的Web API的机会。

前言  xx

开场：嗯，那是一次有趣的旅行，不是吗  xxviii

Bob、Carol 和BigCo 公司  xxx

 

第1 章 从HTML 到简单Web API 1

任务处理系统（TPS）Web 应用 4

来自服务器的HTML 5

将通用Web 浏览器作为客户端 9

评价 9

Task 服务Web API 10

Web API 的常规实践 10

设计TPS Web API 11

实现TPS Web API18

评价 24

总结 25

参考资料 26

 

第2 章 JSON 客户端 29

JSON Web API 客户端 30

Objects 31

Addresses 34

Actions 35

小结 38

JSON 单页面客户端38

HTML 容器 38

顶层解析循环 40

Objects、Addresses 和Actions 41

小结 47

应对变化 47

添加字段和过滤器 48

编写一个新客户端 52

总结 54

参考资料 57

 

第3 章 表述器模式 59

XML 还是JSON ：选一个吧62

新的分支：超媒体格式 63

“唯一正确”的谬误 65

重建（reframe）问题 66

表述器（Representor）模式 68

从功能中分离格式 69

选择算法 69

适配和翻译 71

服务端模型 74

处理HTTP Accept 头部参数 74

实现消息翻译器模式 74

通用表述器模块 76

WeSTL 格式 76

表述器的范例 81

总结 84

参考资料 86

 

第4 章 HAL 客户端 89

HAL 格式 91

Links 93

Objects 和Properties 94

内嵌Links 和Objects 95

小结 97

HAL 表述器 97

Links 98

Properties 99

内嵌内容  100

HAL 表述器构建TPS 输出示例  102

HAL SPA 客户端 104

HTML 容器  105

顶层解析循环  106

Links  107

内嵌内容  109

Properties  113

为HAL 处理Action  114

小结  116

应对变化  117

添加ACTION  117

HAL-FORMS 扩展  121

规范  121

请求HAL-FORMS 文档  123

实现  124

总结  125

参考资料  128

 

第5 章 可重用客户端应用的挑战 131

你在解决什么问题  133

设计的双钻石模型  134

闭合方案 vs 开放方案  134

交互建模  136

Maldonado 的机制  137

Verplank 的人类视角  139

超媒体交互循环  141

RPW 循环  141

用代码实现RPW 143

处理Verplank 的KNOW 步骤  144

总结  148

参考资料  150

 

第6 章 Siren 客户端 153

Siren 格式  155

Entities  157

Class  158

Properties  158

Links  159

Actions  159

SubEntities  160

小结  162

Siren 表述器  162

顶层循环  163

Class  164

Properties  164

Entities  165

Actions  166

Links  168

TPS 通过Siren 表述器输出示例  169

Siren SPA 客户端  172

HTML 容器  173

顶层解析循环  173

Links  174

Entities  176

Properties  178

Actions  181

小结  184

应对变化  184

添加邮箱字段和过滤器  185

测试邮箱字段  187

Profile 对象描述（POD）扩展  190

POD 规范  191

实现  192

在Siren 中使用POD 展示对象  194

小结  195

总结  196

参考资料  198

 

第7 章 版本化与Web 199

互联网中的版本化  201

TCP/IP 的健壮性原则  202

HTTP 中的MUST IGNORE  203

HTML 的向后兼容性  205

非破坏性变更指南  206

API 设计者  206

服务端实现者  209

客户端实现者  215

总结  223

参考资料  225

 

第8 章 Collection JSON 客户端 227

Collection JSON 格式  229

Links  232

Items  233

Queries  234

Template  235

Error  237

小结  237

xviii ｜ 目录

Collection JSON 表述器  238

顶层处理循环  238

Links  239

Items  240

Queries  243

Template  244

Error  245

Collection JSON SPA 客户端  246

HTML 容器  246

顶层解析循环  248

Links  249

Items  250

Queries  253

Template  255

Error  257

小结  258

处理变更  258

在TPS API 中添加Note 对象  259

Cj 和OAA 挑战  265

小结  266

扩展Collection JSON  266

用Cj-Types 支持改善的输入  267

Cj-Suggest 扩展  271

小结  275

总结  275

参考资料  279

 

第9 章 超媒体与微服务 281

UNIX 哲学  284

BigCo 的TPS 微服务  285

Task 服务与Collection JSON  286

User 服务与Siren  290

Note 服务与HAL  293

一个客户端，统领全局  296

Home 服务 297

多格式客户端SPA 容器  298

可以切换格式的客户端UI  301

 

总结  308

参考资料  312

 

结语：拥抱你的未来 313

附录A　项目清单 315

附录B　工具与资源 319

推荐序：一场与超媒体的未了情缘
在2007 年，当我初次翻译Roy Fielding 关于REST 的博士论文（中文名为《架构风格与基于网络应用软件的架构设计》）时，自己对Web 的整体架构是毫无概念的。无知者无畏，当时我仅仅是出于求知欲就开始了翻译工作。后来我发现这个挑战严重超出了我的能力范围，Fielding 的博士论文是我翻译过的专业技术著作中难度最高的。后来我在2013 年重新翻译了这篇博士论文，力求把初次翻译时的大量问题和留下的遗憾都弥补上，而不至于误人子弟。
这篇博士论文是一座内涵丰富的宝藏，可以说是2000 年前Web 架构相关论文中的集大成者，其重要性不亚于Tim Berners-Lee 爵士的论文。文中系统地阐述了HTTP 1.1 协议背后的设计原理——REST。绝大多数不理解REST 思想的Web 开发者都会陷入两个误区之中：一个是将HTTP 简单看作是一种传输协议（而不是应用协议），另一个是完全忽视超媒体的重要性。在2005 年REST 思想随着Web 2.0 的兴起和迅速发展而逐渐普及之后，脱离第一个误区的Web 开发者越来越多，但是能脱离第二个误区的Web 开发者还是极少数。Fielding 博士其实从最初就认为REST 和超媒体是不可分割的，而HTTP 1.1 最重要的设计目标就是更好地支持超媒体。在当时的语境中，这个超媒体自然就是HTML。因为关于超媒体的误解如此之多，所以Fielding 博士在2008 年写了一篇博客文章RESTAPIs Must be Hypertext-driven（《REST API 必须是超文本驱动的》）。
这篇博客引起了Web 开发社区的广泛讨论和反思，随后RESTful Web Services 一书的作者Leonard Richardson 提出了一个Richardson 成熟度模型。这个模型将RESTful API 划分成了3 个等级，把能够熟练应用超媒体的RESTful API 列为了最高等级——第3 级。然而很多年过去了，在普通Web 开发者看来，这似乎仍然是一个乌托邦式的目标。有些RPC 铁杆粉丝总是会拿这个来讥讽REST 爱好者，把他们说成是中看不中用的API 设计美学爱好者。这些传统的观点过于强大，以至于REST 爱好者对于在API 设计中使用超媒体也视为畏途。
当然，我们都是工程派，而不是学院派，随便给别人乱扣学院派的大帽子是一种不尊重人的行为，也是不求甚解的体现。包括REST 思想的创造者Roy Fielding 也是“如假包换”的工程派。他早年为很多开源项目贡献过大量代码，还指导了大量HTTP 客户端/ 服务器端开发团队，他的实战能力肯定在绝大多数开发者之上。REST 当然并不是一种API设计美学，它更像是中庸之道，包含了设计Web 应用的各种架构权衡。虽然Fielding 在设计HTTP 1.1 和撰写博士论文时，超媒体主要指的是HTML，但是REST 是通用的理论，能支持的超媒体类别远不止HTML 一种。在Fielding 发表2008 年博客文章之后，Web开发社区与超媒体相关的研究和开发实战非常活跃，出现了大量新型的超媒体，而且越
新出现的超媒体，越是基于JSON 而非XML 的。一直很支持REST 设计开发的O’Reilly出版社，也不失时机地出版了很多REST 开发相关的图书，这些图书目前已经形成了一个强大的系列，包括：
y RESTful Web Services
y RESTful Web Services Cookboo（k 中文版为《RESTful Web Services Cookbook中文版》）
y REST in Practice（中文版为《REST 实战》）
y RESTful Web APIs（中文版为《RESTful Web APIs 中文版》）
y RESTful Web Clients（中文版为《RESTful Web Clients：基于超媒体的可复用客户端 》，即
本书）
另外还有很多针对某个开发平台的REST 开发图书，例如：
y RESTful .NET
y Building Hypermedia APIs with HTML5 and Node（中文版为《使用 HTML5 和 Node
构建超媒体API》）
y PHP Web Services: APIs for the Modern Web
在这些优秀的REST 开发图书之中，涉及了超媒体的图书中最有代表性的是如下3 本：
y REST in Practice（中文版为《REST 实战》）
y RESTful Web APIs（中文版为《RESTful Web APIs 中文版》）
y RESTful Web Clients（中文版为《RESTful Web Clients：基于超媒体的可复用客户端 》，
即本书）
我有幸作为REST in Practice 一书的翻译负责人，赵震一负责翻译RESTful Web APIs，曾著负责翻译RESTful Web Clients。我们就像是一个接力赛的团队一样，在7 年的时间里，把接力棒传递下去，希望能通过这3 本书向国内的Web 开发者全面展示RESTful API 和超媒体的独特魅力。
这3 本书由浅入深，逐步揭开了支持超媒体的第3 级RESTful API（也就是所谓的Web API）的神秘面纱。尤其是第3 本书RESTful Web Clients，令人信服地展示了使用超媒体之后，对于API 客户端代码的复用性和松耦合起到的巨大作用。除此之外，这本书最重要的贡献是让超媒体变得如此平易近人，要达到这个目标其实是非常困难的。作者Mike Amundsen 虽然功力深厚，但为了保证本书的质量，原著足足推迟了一年时间才上市。结果不负众望，Mike 为读者奉献了一本高质量的图书。连Roy Fielding 在Twitter 上也承认Mike Amundsen 对于超媒体如何使用的理解，与REST 博士论文是最接近的。相信认真阅读完本书的Web 开发者对在API 设计中适当使用超媒体不再会那么犹豫。其实在API 设计中适当使用超媒体，就应该像我们平时写代码时要写单元测试一样习以为常，并且熟能生巧，不断探索在API 设计中使用超媒体的乐趣。
另外我还建议读者在读完RESTful Web Clients 之后，再去认真读一下Mike Amundsen 的上一本书RESTful Web APIs，因为这两本书有很强的关联性。RESTful Web APIs 虽然很棒，但是偏重于概念阐述，实战性不足，RESTful Web Clients 弥补了RESTful Web APIs 在实战性方面的缺憾。思想的发展是有传承性的，没有几年前的RESTful Web APIs 就不会有RESTful Web Clients。对于API 来说，服务器端是皮，客户端是毛，皮之不存，毛将焉附？
顺便说一下，虽然现在HTTP 1.1 已经升级到了HTTP 2，不过REST 和超媒体的思想是完全适用的。如果熟悉HTTP 2，你会发现，其实HTTP 2 的设计还是为了更好地支持超媒体（特别是HTML5），HTTP 2 仍然是与超媒体紧密相关的。这再次证实了Fielding在REST 博士论文中所阐述的思想，REST 是Web 自身的架构风格，REST 就是一切优秀Web 应用的灵魂，而REST 自身的灵魂就是超媒体。超媒体是计算机软件领域最伟大的思想之一，它是Web 应用取之不竭的力量源泉。
开卷有益，最后我代表国内的Web 开发者感谢本书的两位译者曾著、徐必涛的辛勤工作。
也感谢博文视点张春雨老师，他10 年来坚持不懈地支持REST 开发图书的出版。

Web 架构师　李锟
2018 年3 月4 日于上海
译者序
2017 年年末，就职小米的一位前同事送了我一枚F 码，我用它抢购到一枚小爱音箱。我满怀期待地装上“小爱同学”，希望能够通过她用语音控制所有小米产品。但我失望地发现，早先我购买的YeeLight 床头灯并不能接受“小爱同学”的指挥——YeeLight 床头灯的客户端只能适配其出厂时的服务端所提供的功能，在服务端扩展新的功能，比如接入智能语音控制之后，已经发布的客户端却无法跟上，无法获得新功能。
随着互联网尤其是物联网的发展，跨企业、跨行业的互联需求越来越多，上述遗憾会频繁发生，无疑会造成巨大的浪费，也阻碍了物联网的发展。我们迫切需要服务端和客户端相互独立演化的能力，这正是RESTful 服务端与客户端的用武之地，也是本书的主要目的。
本质上，服务端和客户端独立演化的能力取决于双方的实现细节的解耦程度。首先，如果服务端与客户端紧密耦合，服务端变更就很可能造成客户端失效。例如，服务端和客户端通过RPC 的IDL 来约定服务接口，那么当服务端的变更引起过程名、参数或返回值的变更时，客户端就很难不受其影响。又例如，服务端的Web Service 遵循一套URL template 规约，客户端根据服务端提供的规约文档编码，如果服务端改变了资源名称或资源之间的关联关系，也会导致客户端失效。其次，与服务端紧密耦合的客户端显然也无法正常接纳服务端推出的新功能。
REST 解决的思路就是将可能变化的部分抽象出来，融入服务端响应的消息体中，如果客户端拥有解读这些变化的能力，也就使双方都获得了独立演化的能力。
在过去我们非常熟悉的“通用浏览器 服务端渲染逻辑（CGI、JSP、ASP、PHP 等） HTML”方案中，服务端输出了整个HTML 文档，自然也包含了服务端所有可能变化的部分。从理论上说，客户端和服务端的确获得了相互独立演化的能力——浏览器是通用的，不需要应用程序员编写任何客户端代码，也并不因为服务端改变了JSP 脚本或增加一个功能，就需要升级浏