《RESTful Web Clients：基於超媒體的可復用客戶端》
REST大師新作：攻克HATEOAS|客戶端與服務端分離 全局方案：服務端Best Practice|多格式支持|超媒體類型|版本化|微服務
【美】Mike Amundsen（邁克·阿蒙森） 著
曾著 徐必濤 譯
ISBN 978-7-121-33758-1
2018年8月出版
定價：99.00元
356頁
16開
基本介紹
- 書名：RESTful Web Clients：基於超媒體的可復用客戶端
- 作者：【美】Mike Amundsen（邁克·阿蒙森）
- 譯者：曾著、徐必濤
- ISBN：978-7-121-33758-1
- 頁數：356頁
- 定價：99.00元
- 出版社：電子工業出版社
- 出版時間：2018年8月
- 裝幀：平裝
- 開本：16開
編輯推薦
強大的基於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 Web Clients：基於超媒體的可復用客戶端》則著重研究RESTful客戶端，介紹了如何把一個的針對服務端規約硬編碼的定製客戶端，重構為一個支持HATEOAS的通用客戶端，並提供了多格式支持、超媒體類型、版本化、微服務等相關問題的全面指導。《RESTful Web Clients：基於超媒體的可復用客戶端》附有所有樣例代碼的GitHub地址，方便讀者快速理解和實踐。《RESTful Web Clients：基於超媒體的可復用客戶端》適合Web套用開發者，尤其適合希望Web應用程式的服務端與客戶端能夠獨立演化的Web架構師。
目錄
前言 .................................................................................................................................... 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 API.........................................................................................18
評價 ...............................................................................................................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
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
作者簡介
原著作者簡介：作為國際知名的作家和演說家，Mike Amundsen在全球各地諮詢和研討網路架構、Web開發和其他議題。而作為CA Technologies API學院的架構總監，他與公司致力於提供Web API方面的洞見，以便可以最大限度地利用面向消費者和企業的Web API的機會。
作譯者簡介：曾著，畢業於北京大學，互愛（北京）科技股份有限公司技術副總裁。徐必濤，霓風網路科技有限公司軟體架構師，曾任ThoughtWorks高級軟體工程師、DevOps諮詢師。
前言
“始階段是工作中最重要的部分。”
——柏拉圖（Plato）
基於Web 的REST 和超媒體服務正日趨普遍，但卻鮮有客戶端可以利用這些API 的強大功能。這主要是因為缺乏創建成功的超媒體客戶端的技術和模式——長期以來它們一直被忽視。然而，如果可以採取恰當的方式，基於超媒體的客戶端套用將會比典型的一次性客戶端具有更強的穩定性和靈活性。
本書旨在為讀者提供一個堅實的背景知識和一些可工作的示例源碼，這些示例為如何處理超媒體API 提供了明確的建議。本書的主要思想之一是客戶端應用程式應該依賴於Request、Parse 和Wait 所構成的循環，我簡稱其為RPW 循環。這是所有電腦遊戲採用的實現方式，也是所有事件驅動接口從視窗式工作站（windowing-style workstation）到回響式機器接口（reactive machine interface）的工作方式。
有人告訴我，一些前端的開發人員可能會認為RPW 模式比較生僻，甚至也有人認為我的建議比較“激進”。對於這些觀點，我都能理解。當下，眾多的前端開發庫和實踐都在致力於設計用於專門構建的一次性用戶界面，這些界面難以修改，並且很難在運行時對服務提供的新信息做出反應。不過，在閱讀本書的例子後，我希望前端開發人員（他們中的大多數都比我的經驗更豐富）能夠在目前初步工作的基礎上創造出更豐富的最佳實踐、工具和可重用的庫，為越來越多的超媒體API 打造高質量的用戶體驗，力爭在不需要頻繁升級的情況下滿足高質量的用戶體驗需求，以及不斷發展的服務接口自適應客戶端的需求。
本書講了什麼
本書將帶領讀者開啟一段從個性化定製實現到強大的通用客戶端套用的旅程，同時向你展示如何利用那些支撐全球資訊網良好運行的基本原則。本書包括以代碼為中心的章節信息和對相關重要主題的探索，比如表述器模式、人機互動模型和Web API 在版本控制上的挑戰等。當然，其中也少不了大量的代碼（我為本書創建了20 多個GitHub 倉庫），包括一些小的代碼片段。不過，這些片段單獨看可能不易理解。因此，我會為讀者指出完整的線上代碼庫的位置，你可以在相關代碼庫中找到本書所涵蓋的全部功能實例。
各章內容
本書探討了通用超媒體風格客戶端的世界，包括它們的外觀、與典型JSON 對象客戶端的區別，以及客戶端和服務端開發者如何構建更易於支持和適應的系統。本書包含了一些專項討論所選格式（如HTML、純JSON、HAL、Siren 和Collection+JSON）的章節，以及所有Web 開發人員需要熟悉的理論和實踐的章節，包括服務端對訊息格式的支持、人機互動模型、版本控制，以及一個在同時與多個獨立的後端服務進行互動時可以支持多種超媒體格式的解決方案。
本書的大多數章節都可以獨立成章，在閱讀時可以不講究先後順序。不過，為了更充分地理解和吸收本書的內容，我鼓勵你將本書看成一次單程旅行，按照順序從頭讀到尾。這裡簡單介紹一下本次旅程的路徑。
第1 章，從HTML 到簡單Web API
本章向我們介紹了一個經典的純HTML 客戶端。我們將通過它來了解瀏覽器的基本工作原理，以及它們是如何影響人們看待Web 中那些超媒體格式的。此外，本章還介紹了將純HTML 服務轉換為一個原始的純JSON 服務的過程。該服務將是我們為本書構建的所有其他客戶端應用程式的基礎。
第2 章，JSON 客戶端
大多數的客戶端Web 開發人員都會構建JSON 客戶端，它會記住所有的URL，處理靜態對象，並通過固定的工作路徑來導航。構建JSON 客戶端是一個很好的開始，不過時間卻證明它是一個糟糕的工作方式。在本章中，我們將討論如何克服在維護純JSON 風格客戶端應用程式時的挑戰。
第3 章，表述器模式
表述器模式是處理伺服器輸出的一種簡單而重要的方式，也是將內部對象模型轉換為外部訊息模型的過程。我們將在本章中審視該模式（及其源頭），並介紹如何使用伺服器上的Web 服務遷移語言（WeSTL）和瀏覽器客戶端上的HTML DOM 將該模式套用於API 提供方。
第4 章，HAL 客戶端
HAL 媒體類型是目前較為流行的超媒體格式之一。比如在Amazon 的Web 服務團隊中，至少有兩個API 使用了HAL。對於所有Web 客戶端都需要處理的三個重要元素，HAL 負責處理其中之一： ADDRESS 挑戰。我們將看到如何將HAL 作為訊息格式來構建一個通用客戶端，以及如何通過HAL-FORMS 擴展來提高HAL 的處理能力。
第5 章，可重用客戶端套用的挑戰
你會注意到，我們所構建的多數客戶端看起來都很類似。從本質上講，我們正在建立能夠在探索周圍世界（以某種有限的方式）的過程中發展自己的“探險者”。這些客戶端都採用了Request—Parse—Wait 循環，即RPW 模式。該模式基於我們如何與世界互動這一命題下的幾個經典概念，我們將在本章中探討它們。
第6 章，Siren 客戶端
Siren 內容類型是另一種強大的超媒體類型。Siren 目前被用作Zetta IoT 平台的一部分，旨在處理Web 客戶端的三個關鍵任務中的兩個：ADDRESS 和ACTION。我們將看到使用Siren 作為訊息格式來構建一個通用客戶端，也會通過探索Siren 拓展（Profile for Object Display，即POD）來增強它在UI 上顯示元數據的能力。
第7 章，版本化與Web
當你開始將超媒體類型作為客戶端Web 應用程式的基礎時，API 版本的概念會發生什麼變化？本章將討論管理隨時間變化的各種嘗試，以及如何依賴基於訊息的超媒體風格的API 來減少當接口特性發生變更時也要變更接口契約的問題。
第8 章，Collection+JSON 客戶端
在本章中我們將探討另外一種超媒體格式：Collection+JSON，或稱為Cj。Cj 能夠處理Web 客戶端中的所有元素：OBJECT、ADDRESS 和ACTION。我們將看到如何將Collection+JSON 作為訊息格式來構建一個通用客戶端，並學習如何擴展Cj 的數據顯示和驗證程式。
第9 章，超媒體與微服務
創建一個可以無縫調用多個服務的通用超媒體客戶端需要什麼？如果這些服務使用的超媒體類型各不相同，又需要什麼呢？當我們談論訊息格式時，該怎樣製作一個可以“說”多種語言的客戶端套用？這一切將在最後一章中揭曉。
