這篇最佳實(shí)踐文章面向?qū)?chuàng)建 RESTful Web 服務(wù)感興趣的開(kāi)發(fā)人員，這些服務(wù)提供跨多個(gè)服務(wù)套件的高可靠性和一致性;遵循這些準(zhǔn)則;服務(wù)定位于內(nèi)部和外部客戶快速、廣泛、公開(kāi)采用。

這是一個(gè)完整的圖表，可以輕松理解 REST API 的原理、方法和最佳實(shí)踐。

現(xiàn)在，讓我們從每個(gè)盒子的原理開(kāi)始詳細(xì)說(shuō)明它。

六項(xiàng)原則/約束

客戶端-服務(wù)器：關(guān)注點(diǎn)分離是客戶端-服務(wù)器約束背后的原則。通過(guò)將用戶界面問(wèn)題與數(shù)據(jù)存儲(chǔ)問(wèn)題分開(kāi)，我們提高了用戶界面跨多個(gè)平臺(tái)的可移植性，并通過(guò)簡(jiǎn)化服務(wù)器組件提高了可擴(kuò)展性。

無(wú)狀態(tài)：通信必須是無(wú)狀態(tài)的，如客戶端-無(wú)狀態(tài)-服務(wù)器 (CSS) 風(fēng)格。從客戶端到服務(wù)器的每個(gè)請(qǐng)求都必須包含理解請(qǐng)求所需的所有信息。因此，會(huì)話狀態(tài)完全保留在客戶端上。

可緩存：為了提高網(wǎng)絡(luò)效率，我們添加了緩存約束以形成客戶端-緩存-無(wú)狀態(tài)-服務(wù)器風(fēng)格。緩存約束要求數(shù)據(jù)響應(yīng)帶有隱式或顯式標(biāo)簽為可緩存或不可緩存的請(qǐng)求。如果響應(yīng)是可緩存的，則客戶端緩存有權(quán)為以后的等效請(qǐng)求重用該響應(yīng)數(shù)據(jù)。

分層系統(tǒng)：客戶端通常無(wú)法判斷它是直接連接到終端服務(wù)器還是沿途的中介。中間服務(wù)器可以通過(guò)啟用負(fù)載平衡和提供共享緩存來(lái)提高系統(tǒng)可擴(kuò)展性。層也可以強(qiáng)制執(zhí)行安全策略。

按需代碼：REST 允許通過(guò)下載和執(zhí)行小程序或腳本形式的代碼來(lái)擴(kuò)展客戶端功能。通過(guò)減少需要預(yù)先實(shí)現(xiàn)的功能數(shù)量來(lái)簡(jiǎn)化客戶端。它允許在部署后下載功能，提高了系統(tǒng)的可擴(kuò)展性。

統(tǒng)一接口：通過(guò)將通用性的軟件工程原理應(yīng)用于組件接口，簡(jiǎn)化了整個(gè)系統(tǒng)架構(gòu)，提高了交互的可見(jiàn)性。實(shí)現(xiàn)與它們提供的服務(wù)分離，這鼓勵(lì)了獨(dú)立的可進(jìn)化性。REST 定義了四個(gè)接口約束：資源的識(shí)別、通過(guò)表示的資源操作、自描述消息和作為應(yīng)用程序狀態(tài)引擎的超媒體。

• 自描述消息：每條消息都包含足夠的信息來(lái)描述如何處理消息。
• 基于資源：在請(qǐng)求中使用 URI 作為資源標(biāo)識(shí)符來(lái)標(biāo)識(shí)單個(gè)資源。資源本身在概念上與返回給客戶端的表示分開(kāi)。
• 通過(guò)表示操作資源：當(dāng)客戶端表示資源(包括附加的任何元數(shù)據(jù))時(shí)，它有足夠的信息來(lái)修改或刪除服務(wù)器上的資源，前提是它有這樣做的權(quán)限。
• 超媒體作為應(yīng)用程序狀態(tài)引擎 (HATEOAS)：客戶端通過(guò)正文內(nèi)容、查詢字符串參數(shù)、請(qǐng)求標(biāo)頭和請(qǐng)求的 URI(資源名稱)傳遞狀態(tài)。服務(wù)通過(guò)正文內(nèi)容、響應(yīng)代碼和響應(yīng)頭向客戶端提供狀態(tài)。

最佳實(shí)踐

現(xiàn)在，讓我們換個(gè)角度來(lái)了解 REST 的基本最佳實(shí)踐，這是每個(gè)工程師都應(yīng)該知道的。

• 保持簡(jiǎn)單和細(xì)粒度：創(chuàng)建模擬系統(tǒng)底層應(yīng)用程序域或系統(tǒng)數(shù)據(jù)庫(kù)架構(gòu)的 API。最終，您將需要聚合服務(wù)——利用多種底層資源來(lái)減少閑聊的服務(wù)。
• 過(guò)濾和排序：對(duì)于大型數(shù)據(jù)集，從帶寬的角度來(lái)看，限制返回的數(shù)據(jù)量至關(guān)重要。此外，我們可能希望指定要包含在響應(yīng)中的資源的字段或?qū)傩裕瑥亩拗品祷氐臄?shù)據(jù)量。我們最終想要查詢特定值并對(duì)返回的數(shù)據(jù)進(jìn)行排序。
• 版本控制：有很多方法可以破壞合同并對(duì) API 開(kāi)發(fā)中的客戶產(chǎn)生負(fù)面影響。如果您不確定更改的后果，最好謹(jǐn)慎行事并考慮版本控制。在決定新版本是否合適或?qū)ΜF(xiàn)有表示的修改是否充分和可接受時(shí)，需要考慮幾個(gè)因素。由于維護(hù)多個(gè)版本變得繁瑣、復(fù)雜、容易出錯(cuò)且成本高昂，因此對(duì)于任何給定資源，您應(yīng)該支持不超過(guò)兩個(gè)版本。
• 緩存：緩存通過(guò)啟用系統(tǒng)中的層來(lái)消除檢索請(qǐng)求數(shù)據(jù)的遠(yuǎn)程調(diào)用來(lái)增強(qiáng)可擴(kuò)展性。服務(wù)通過(guò)在響應(yīng)(如 Cache-Control、Expires、Pragma、Last-Modified 等)上設(shè)置標(biāo)頭來(lái)提高緩存能力
• 分頁(yè)：REST 的原則之一是連通性——通過(guò)超媒體鏈接。同時(shí)，沒(méi)有它們，服務(wù)仍然有用。當(dāng)鏈接在響應(yīng)中返回時(shí)，API 變得更具自我描述性。對(duì)于支持分頁(yè)的響應(yīng)中返回的集合，“first”、“l(fā)ast”、“next”和“prev”鏈接至少是有益的。
• 資源命名：當(dāng)資源命名正確時(shí)，API 是直觀且易于使用的。做得不好，同樣的 API 會(huì)讓人感覺(jué)很笨拙，并且難以使用和理解。RESTful API 適用于消費(fèi)者。URI 的名稱和結(jié)構(gòu)應(yīng)該向這些消費(fèi)者傳達(dá)含義。通常很難知道數(shù)據(jù)邊界應(yīng)該是什么，但是通過(guò)了解您的數(shù)據(jù)，您很可能有能力進(jìn)行嘗試，并將什么作為代表返回給您的客戶是有意義的。為您的客戶設(shè)計(jì)，而不是為您的數(shù)據(jù)設(shè)計(jì)。
• - 復(fù)數(shù)：普遍接受的做法是始終在節(jié)點(diǎn)名稱中使用復(fù)數(shù)形式，以保持您的 API URI 在所有 HTTP 方法中保持一致。原因是“客戶”是服務(wù)套件中的一個(gè)集合，而 ID(例如 33245)指的是集合中的這些客戶之一。
• 監(jiān)控：確保添加各種監(jiān)控以提高 API 的質(zhì)量或性能。數(shù)據(jù)點(diǎn)可以是響應(yīng)時(shí)間(P50、p90、P99)、狀態(tài)代碼(5XX、4XX 等)、網(wǎng)絡(luò)帶寬等等。
• 安全：

• - 授權(quán)/認(rèn)證：對(duì)服務(wù)的授權(quán)與對(duì)任何應(yīng)用程序的授權(quán)沒(méi)有什么不同。問(wèn)這個(gè)問(wèn)題，“這個(gè)主體對(duì)給定資源是否有請(qǐng)求的權(quán)限?”
• - CORS：在服務(wù)器上實(shí)現(xiàn) CORS 就像在響應(yīng)中發(fā)送額外的 HTTP 標(biāo)頭一樣簡(jiǎn)單，例如 Access-Control-Allow-Origin、Access-Control-Allow-Credentials 等
• - TLS：所有身份驗(yàn)證都應(yīng)使用 SSL。OAuth2 需要授權(quán)服務(wù)器和訪問(wèn)令牌憑據(jù)才能使用 TLS。
• - 冪等性：如果執(zhí)行一次或多次，將產(chǎn)生相同結(jié)果的操作。根據(jù)其適用的上下文，它可能具有不同的含義。例如，在具有副作用的方法或子程序調(diào)用的情況下，這意味著修改后的狀態(tài)在第一次調(diào)用后保持不變。
• - 輸入驗(yàn)證：驗(yàn)證服務(wù)器上的所有輸入。接受“已知”好的輸入并拒絕錯(cuò)誤的輸入，防止 SQL 和 NoSQL 注入，將消息大小限制為字段的確切長(zhǎng)度，服務(wù)應(yīng)僅顯示一般錯(cuò)誤消息等等。
• - 限速：是一種限制網(wǎng)絡(luò)流量的策略。它限制了某人在特定時(shí)間范圍內(nèi)重復(fù)操作的頻率 - 例如，嘗試登錄帳戶。
• - 記錄：確保您不會(huì)意外記錄任何個(gè)人身份信息 (PII)。

至此，我結(jié)束了這次學(xué)習(xí)，我希望你今天學(xué)到了一些新東西。

本文轉(zhuǎn)載自微信公眾號(hào)「超級(jí)架構(gòu)師」，可以通過(guò)以下二維碼關(guān)注。轉(zhuǎn)載本文請(qǐng)聯(lián)系超級(jí)架構(gòu)師公眾號(hào)。