Web API設(shè)計(jì)原則通過API和微服務(wù)實(shí)現(xiàn)價(jià)值交付

第 一部分 Web API設(shè)計(jì)簡(jiǎn)介
第 1章 API設(shè)計(jì)原則　3
1.1 Web API設(shè)計(jì)要素　4
1.1.1 業(yè)務(wù)功能　4
1.1.2 產(chǎn)品思維　4
1.1.3 開發(fā)者體驗(yàn)　5
1.2 API設(shè)計(jì)即溝通　6
1.3 審查軟件設(shè)計(jì)的原則　7
1.3.1 模塊化　7
1.3.2 封裝　8
1.3.3 高內(nèi)聚和松耦合　8
1.4 基于資源的API設(shè)計(jì)　9
1.5 資源不是對(duì)象或領(lǐng)域模型　11
1.6 基于資源的API交換消息　11
1.7 Web API設(shè)計(jì)原則　13
1.8 小結(jié)　13
第 2章 協(xié)作式API設(shè)計(jì)　15
2.1 為什么需要API設(shè)計(jì)流程？　15
2.2 API設(shè)計(jì)流程反模式　17
2.2.1 泄露抽象反模式　17
2.2.2 下一個(gè)版本設(shè)計(jì)修復(fù)反模式　18
2.2.3 英雄設(shè)計(jì)工作反模式　18
2.2.4 未使用的API反模式　19
2.3 API設(shè)計(jì)優(yōu)先的方法　19
2.4 API設(shè)計(jì)優(yōu)先并保持敏捷　20
2.4.1 重新審視敏捷宣言　21
2.4.2 API設(shè)計(jì)優(yōu)先的敏捷性　21
2.5 對(duì)齊-定義-設(shè)計(jì)-優(yōu)化流程　22
2.6 DDD在API設(shè)計(jì)中的作用　24
2.7 API設(shè)計(jì)涉及每一個(gè)人　25
2.8 有效應(yīng)用ADDR流程　26
2.9 小結(jié)　26
第二部分 對(duì)齊API的結(jié)果
第3章 明確數(shù)字功能　29
3.1 確保利益相關(guān)者思路對(duì)齊　30
3.2 什么是數(shù)字功能？　31
3.3 專注于要完成的工作　32
3.4 什么是任務(wù)用例？　33
3.5 任務(wù)用例的組成部分　33
3.6 為API編寫任務(wù)用例　34
3.6.1 方法1：當(dāng)問題已知時(shí)　35
3.6.2 方法2：當(dāng)期望的結(jié)果已知時(shí)　35
3.6.3 方法3：當(dāng)數(shù)字功能已確定時(shí)　35
3.7 克服任務(wù)用例的挑戰(zhàn)　36
3.7.1 挑戰(zhàn)1：任務(wù)用例過于詳細(xì)　36
3.7.2 挑戰(zhàn)2：任務(wù)用例以功能為中心　36
3.7.3 挑戰(zhàn)3：任務(wù)用例需要額外的用戶上下文　37
3.8 收集任務(wù)用例的技巧　37
3.9 現(xiàn)實(shí)世界中的API設(shè)計(jì)項(xiàng)目　38
3.10 任務(wù)用例示例　39
3.11 小結(jié)　39
第4章 收集操作和步驟　41
4.1 將任務(wù)用例擴(kuò)展為操作及其對(duì)應(yīng)的步驟　42
4.1.1 確定每個(gè)任務(wù)用例的操作　43
4.1.2 將每個(gè)操作分解為若干步驟　43
4.1.3 如果需求不明確，怎么辦？　44
4.2 通過事件風(fēng)暴實(shí)現(xiàn)協(xié)作式 理解　44
4.3 事件風(fēng)暴的工作方式　46
4.3.1 步驟1：明確領(lǐng)域事件　46
4.3.2 步驟2：創(chuàng)建事件描述　47
4.3.3 步驟3：查看描述并確定差距　48
4.3.4 步驟4：擴(kuò)展領(lǐng)域理解力　49
4.3.5 步驟5：查看最終描述　50
4.4 事件風(fēng)暴的好處　52
4.5 主持事件風(fēng)暴會(huì)議　53
4.5.1 準(zhǔn)備：收集必要的材料 用品　54
4.5.2 分享：溝通事件風(fēng)暴會(huì)議　55
4.5.3 主持：進(jìn)行事件風(fēng)暴會(huì)議　56
4.5.4 總結(jié)：收集操作和步驟　56
4.5.5 跟進(jìn)：會(huì)后建議　57
4.5.6 定制流程　57
4.6 小結(jié)　58
第三部分 定義候選API
第5章 明確API邊界　61
5.1 避免API邊界反模式　62
5.1.1 大型一體化API反模式　62
5.1.2 過載API反模式　62
5.1.3 輔助API反模式　63
5.2 有界上下文、子域和API　63
5.3 使用事件風(fēng)暴探索API邊界　64
5.4 通過操作找到API邊界　67
5.5 為API命名并確定其范圍　68
5.6 小結(jié)　69
第6章 API建模　71
6.1 什么是API建模？　72
6.2 API建模流程　74
6.2.1 步驟1：收集API配置文件摘要　74
6.2.2 步驟2：確定資源　75
6.2.3 步驟3：定義API分類法　77
6.2.4 步驟4：添加操作事件　79
6.2.5 步驟5：擴(kuò)展操作的詳細(xì)信息　80
6.3 用序列圖驗(yàn)證API模型　81
6.4 評(píng)估API的優(yōu)先級(jí)和重用性　83
6.5 小結(jié)　84
第四部分 設(shè)計(jì)API
第7章 基于REST的API設(shè)計(jì)　87
7.1 什么是基于REST的API？　88
7.1.1 REST是客戶-服務(wù)器體系結(jié)構(gòu)　90
7.1.2 REST是以資源為中心的　90
7.1.3 REST是基于消息的　91
7.1.4 REST支持分層架構(gòu)　91
7.1.5 REST支持按需編碼　93
7.1.6 超媒體控制　93
7.1.7 什么時(shí)候選擇REST　96
7.2 REST API設(shè)計(jì)流程　97
7.2.1 步驟1：設(shè)計(jì)資源URL路徑　97
7.2.2 步驟2：將API操作映射到HTTP方法上　99
7.2.3 步驟3：分配響應(yīng)代碼　100
7.2.4 步驟4：記錄REST API設(shè)計(jì)　102
7.2.5 步驟5：分享并收集反饋　106
7.3 選擇一種表征格式　106
7.3.1 資源序列化　107
7.3.2 超媒體序列化　108
7.3.3 超媒體消息傳遞　109
7.3.4 語義超媒體消息傳遞　110
7.4 常見的REST設(shè)計(jì)模式　113
7.4.1 創(chuàng)建-讀取-更新-刪除　113
7.4.2 擴(kuò)展資源生命周期支持　113
7.4.3 單例資源　114
7.4.4 后臺(tái)（隊(duì)列）作業(yè)　115
7.4.5 REST中的長(zhǎng)期運(yùn)行事務(wù)支持　116
7.5 小結(jié)　117
第8章 RPC和基于查詢的API設(shè)計(jì)　119
8.1 什么是基于RPC的API？　120
8.1.1 gRPC　121
8.1.2 使用RPC時(shí)應(yīng)該考慮的因素　122
8.2 RPC API設(shè)計(jì)流程　123
8.2.1 步驟1：確定RPC操作　123
8.2.2 步驟2：細(xì)化RPC操作　124
8.2.3 步驟3：記錄API設(shè)計(jì)　125
8.3 什么是基于查詢的API？　126
8.3.1 了解OData　127
8.3.2 探索GraphQL　128
8.4 基于查詢的API設(shè)計(jì)流程　130
8.4.1 步驟1：設(shè)計(jì)資源和圖結(jié)構(gòu)　130
8.4.2 步驟2：設(shè)計(jì)查詢和突變操作　131
8.4.3 步驟3：記錄API設(shè)計(jì)　132
8.5 小結(jié)　134
第9章 用于事件和流的異步API　135
9.1 API輪詢的問題　136
9.2 異步API創(chuàng)造新的可能性　137
9.3 回顧消息傳遞的基礎(chǔ)知識(shí)　138
9.3.1 消息傳遞的樣式和位置　139
9.3.2 消息的要素　140
9.3.3 了解消息代理　141
9.3.4 點(diǎn)對(duì)點(diǎn)消息分發(fā)（隊(duì)列）　142
9.3.5 扇出消息分發(fā)（主題）　143
9.3.6 消息流基礎(chǔ)知識(shí)　144
9.4 異步API樣式　145
9.4.1 使用Webhooks的服務(wù)器通知　146
9.4.2 使用服務(wù)器發(fā)送事件的服務(wù)器推送　147
9.4.3 通過WebSocket的雙向通知　148
9.4.4 gRPC流　149
9.4.5 選擇異步API樣式　151
9.5 設(shè)計(jì)異步API　151
9.5.1 命令消息　152
9.5.2 事件通知　152
9.5.3 事件承載的狀態(tài)轉(zhuǎn)移事件　153
9.5.4 事件批處理　155
9.5.5 事件排序　156
9.6 記錄異步API　156
9.7 小結(jié)　158
第五部分 優(yōu)化API設(shè)計(jì)
第 10章 從API到微服務(wù)　161
10.1 什么是微服務(wù)？　162
10.2 微服務(wù)降低協(xié)調(diào)成本　164
10.3 API產(chǎn)品和微服務(wù)之間的區(qū)別　165
10.4 權(quán)衡微服務(wù)的復(fù)雜性　165
10.4.1 自助服務(wù)基礎(chǔ)設(shè)施　166
10.4.2 獨(dú)立的發(fā)布周期　166
10.4.3 轉(zhuǎn)向單一團(tuán)隊(duì)的所有權(quán)　166
10.4.4 組織結(jié)構(gòu)和文化影響　166
10.4.5 數(shù)據(jù)所有權(quán)的轉(zhuǎn)移　167
10.4.6 分布式數(shù)據(jù)管理和治理　167
10.4.7 分布式系統(tǒng)的挑戰(zhàn)　168
10.4.8 彈性、故障轉(zhuǎn)移和分布式事務(wù)　168
10.4.9 重構(gòu)和共享代碼帶來的挑戰(zhàn)　169
10.5 同步和異步的微服務(wù)　169
10.6 微服務(wù)架構(gòu)的樣式　171
10.6.1 直接服務(wù)通信　171
10.6.2 基于API的編排　172
10.6.3 基于單元的架構(gòu)　172
10.7 合理調(diào)整微服務(wù)的規(guī)?！?73
10.8 API分解為微服務(wù)　174
10.8.1 步驟1：明確候選微服務(wù)　174
10.8.2 步驟2：將微服務(wù)添加到API序列圖中　176
10.8.3 步驟3：使用微服務(wù)設(shè)計(jì)畫布，以收集設(shè)計(jì)細(xì)節(jié)　177
10.8.4 其他微服務(wù)設(shè)計(jì)注意事項(xiàng)　178
10.9 過渡到微服務(wù)時(shí)的注意事項(xiàng)　179
10.10 小結(jié)　180
第 11章 改善開發(fā)者體驗(yàn)　181
11.1 創(chuàng)建一個(gè)API模擬實(shí)現(xiàn)　182
11.1.1 API靜態(tài)模擬　183
11.1.2 API原型模擬　184
11.1.3 基于README的模擬　185
11.2 提供輔助庫(kù)和SDK　187
11.2.1 提供輔助庫(kù)的選項(xiàng)　187
11.2.2 對(duì)輔助庫(kù)版本化　188
11.2.3 輔助庫(kù)文檔和測(cè)試　188
11.3 為API提供CLI　189
11.4 小結(jié)　191
第 12章 API測(cè)試策略　193
12.1 驗(yàn)收測(cè)試　194
12.2 自動(dòng)化安全測(cè)試　194
12.3 運(yùn)維監(jiān)控　195
12.4 API契約測(cè)試　195
12.5 選擇工具，以加快測(cè)試速度　197
12.6 API測(cè)試的挑戰(zhàn)　197
12.7 讓API測(cè)試不可或缺　198
12.8 小結(jié)　199
第 13章 為API設(shè)計(jì)制作文檔　201
13.1 API文檔的重要性　202
13.2 API描述格式　202
13.2.1 OpenAPI規(guī)范　203
13.2.2 API Blueprint　205
13.2.3 RAML　207
13.2.4 JSON Schema　211
13.2.5 使用ALPS的API配置文件　212
13.2.6 使用APIs.json改進(jìn)API發(fā)現(xiàn)功能　213
13.3 使用代碼示例擴(kuò)展文檔　215
13.3.1 先寫好入門代碼示例　215
13.3.2 使用工作流示例擴(kuò)展文檔　216
13.3.3 錯(cuò)誤案例和生產(chǎn)就緒的示例　217
13.4 從參考文檔到開發(fā)者門戶網(wǎng)站　217
13.4.1 通過開發(fā)者門戶網(wǎng)站提高API采用率　218
13.4.2 優(yōu)秀的開發(fā)者門戶網(wǎng)站的要素　218
13.5 有效的API文檔　219
13.5.1 問題1：你的API如何解決我的問題？　220
13.5.2 問題2：每個(gè)API操作都支持什么功能？　220
13.5.3 問題3：我如何開始使用API？　220
13.5.4 技術(shù)文檔撰寫人在API文檔中的角色　221
13.6 最小可行的門戶　222
13.6.1 第 1個(gè)階段：最小可行的門戶　222
13.6.2 第 2個(gè)階段：改進(jìn)　223
13.6.3 第3個(gè)階段：專注于增長(zhǎng)　224
13.7 用來制作開發(fā)者門戶網(wǎng)站的工具和框架　224
13.8 小結(jié)　225
第 14章 為變更而設(shè)計(jì)　227
14.1 變更對(duì)現(xiàn)有API的影響　227
14.1.1 進(jìn)行API設(shè)計(jì)差距分析　228
14.1.2 確定什么最適合API消費(fèi)者　228
14.1.3 變更策略　229
14.1.4 變更管理是建立在信任之上的　230
14.2 API版本控制策略　230
14.2.1 常見的非破壞性變更　231
14.2.2 不兼容的變更　231
14.2.3 API版本和修訂版本　232
14.2.4 API版本控制方法　233
14.2.5 API版本的商業(yè)考慮因素　234
14.3 棄用API　234
14.3.1 制訂棄用策略　235
14.3.2 宣布棄用　235
14.4 創(chuàng)建一個(gè)API穩(wěn)定性契約　236
14.5 小結(jié)　237
第 15章 保護(hù)API　239
15.1 危害API的潛在因素　239
15.2 基本的API保護(hù)實(shí)踐　240
15.3 API保護(hù)的組件　242
15.3.1 API網(wǎng)關(guān)　242
15.3.2 APIM層　242
15.3.3 服務(wù)網(wǎng)格　243
15.3.4 WAF　244
15.3.5 內(nèi)容分發(fā)網(wǎng)絡(luò)　244
15.3.6 智能API保護(hù)　244
15.4 API網(wǎng)關(guān)拓?fù)浣Y(jié)構(gòu)　245
15.4.1 APIM托管選項(xiàng)　245
15.4.2 API網(wǎng)絡(luò)流量注意事項(xiàng)　248
15.4.3 拓?fù)浣Y(jié)構(gòu)1：API網(wǎng)關(guān)直連到API服務(wù)器　248
15.4.4 拓?fù)浣Y(jié)構(gòu)2：API網(wǎng)關(guān)路由到服務(wù)　249
15.4.5 拓?fù)浣Y(jié)構(gòu)3：多個(gè)API網(wǎng)關(guān)實(shí)例　250
15.5 身份和訪問管理　251
15.5.1 密碼和API密鑰　251
15.5.2 API令牌　251
15.5.3 引用傳遞與值傳遞的API令牌　253
15.5.4 OAuth 2.0和OpenID Connect　253
15.6 構(gòu)建內(nèi)部API網(wǎng)關(guān)之前的注意事項(xiàng)　255
15.6.1 原因1：API安全性是一個(gè)不斷變化的目標(biāo)　255
15.6.2 原因2：需要的時(shí)間比預(yù)期的更長(zhǎng)　255
15.6.3 原因3：預(yù)期的表現(xiàn)需要時(shí)間　256
15.6.4 輔助庫(kù)怎么樣？　256
15.7 小結(jié)　257
第 16章 繼續(xù)API設(shè)計(jì)旅程　259
16.1 建立API樣式指南　259
16.1.1 鼓勵(lì)遵守樣式指南的方法　260
16.1.2 選擇樣式指南的“基調(diào)”　261
16.1.3 啟動(dòng)API樣式指南的入門技巧　261
16.1.4 支持多種API樣式　262
16.2 進(jìn)行API設(shè)計(jì)審查　262
16.2.1 從文檔審查開始　263
16.2.2 檢查標(biāo)準(zhǔn)和設(shè)計(jì)是否對(duì)齊　264
16.2.3 審查測(cè)試覆蓋率　264
16.2.4 添加試用支持　265
16.3 鼓勵(lì)重用文化　265
16.4 旅程才剛剛開始　266
附錄A HTTP入門知識(shí)　267
A.1 HTTP概述　267
A.2 統(tǒng)一資源定位符　268
A.3 HTTP請(qǐng)求　269
A.4 HTTP響應(yīng)　270
A.5 常見HTTP方法　271
A.6 HTTP響應(yīng)代碼　272
A.7 內(nèi)容協(xié)商　273
A.8 緩存控制　275
A.9 條件性請(qǐng)求　276
A.10 HTTP中的并發(fā)控制　278
A.11 小結(jié)　280