1. 使用ASP.NET Core 3.x 構建 RESTful API - 1.準備工作

什麼是REST 

REST一詞最早是在2000年，由Roy Fielding在他的博士論文《Architectural Styles and the Design of Network-based Software Architecture》中提出的。他在本文中創造了REST這個術語。這篇論文的地址是：https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm。 

REST的全稱是 Representational State Transfer（狀態表述轉換）。這個詞錶面看起來可能不太好理解。但其實REST就是勾畫出了這樣一幅景象，它描述了Web應用到底怎麼樣設計才算是優良的。這裡定義了以下三點： 

• 一組網頁的網路（一個虛擬狀態機）； 

• 在這些網頁上，用戶可以通過點擊鏈接來前進（狀態轉換）； 

• 點擊鏈接的結果就是下一個網頁（表示程式的下一個狀態）被傳輸到用戶那裡，並渲染好給用戶使用。 

論文中還提到，REST是一種為分散式超媒體系統所用的架構風格，也就是說，REST定義了一種架構風格來幫助創建和組織出更好的分散式系統。這裡的關鍵詞是架構風格。 

概括的說： 

• REST是一種架構風格，而不是規範或標準； 

• REST需要使用一些規範、協議或標準來實現這種架構風格； 

• REST與協議無關。JSON並不是REST強制的，甚至HTTP都不是REST強制使用的，但這也僅僅是從理論上來看。 

REST背後的主要思想就是：採用RESTful架構風格進行組織的分散式系統，將在以下幾個方面得到改善： 

• 性能。REST的通信風格應該是簡單並且高效的，採用它的系統性能應該得以提升。 

• 組件交互的可擴展性。其實任何分散式系統都允許這種擴展性，而REST所提出的簡單交互方式更是如此。 

• 組件的可修改性。分散式系統的分散式本質和REST提出的關註點分離，使得組件得以以最小的成本和最低的風險彼此獨立的進行修改。 

• 可移植性。REST與技術和語言無關，所以使用任何技術都可以實現REST。 

• 可靠性。REST所提出的無狀態約束允許在系統發生故障後輕鬆的恢復系統。 

• 可視性。REST所提出的無狀態約束為所述請求添加了完整的狀態（一會再解釋）。 

從上面這個列表，我們可以看出，一個以組件為中心設計的系統非常容易出錯，如果一個組件出現了故障而不影響整個系統的穩定性，那這樣對任何系統都是極有好處的。對組件進行互聯是非常簡單的，但是需要在添加新特性或擴大縮小規模時將風險降至最低。憑藉REST的可移植性，使用REST思想進行設計的系統可以為更廣泛的受眾使用。通過通用的介面，系統可以被更廣泛的開發者所使用。為了實現這些屬性和好處，REST使用一組約束來幫助定義統一的介面。 

REST的約束 

為了定義REST架構，首先要定義出一個空無的狀態，也就是一個沒有任何約束的系統。在這裡，組件之間的差異就是個迷，然後我們再一個挨一個的往裡面添加約束並保證這些約束可以互不幹擾、融洽相處。這些約束都定義了實現REST API的框架應該如何被構建和設計。下麵就介紹一些這六個約束： 

• 客戶端-伺服器：關註點分離是這個約束的核心主題。整個Web系統是一個基於客戶端-服務端的系統，客戶端和服務端彼此獨立（獨立實現和部署等），並扮演著不同的角色。它們可以使用不同的語言、技術或平臺，並可以獨自進化，只要它們都遵從Web的統一介面即可。 

• 無狀態：無狀態表示Web伺服器不被要求記住客戶端程式的狀態，因為這個原因，客戶端在發送請求的時候必須包含所有可能需要的相關信息，也就是說狀態需要被包含在請求里，同時也說明客戶端需要維護自己的狀態。由於維護狀態的工作由客戶端自己來完成了，所以伺服器就節省了很多伺服器資源，這樣伺服器就可以為更多的客戶端服務。 

• 統一的資源介面/界面：Web組件之間的交互就意味著客戶端、服務端以及基於網路的中介程式都依賴於它們介面的統一性（API和API的消費者之間共用相同標準的一套介面）。Web組件可以在統一介面的四個約束條件下一致的進行互操作。這四個約束是： 

  • 資源的標識：針對RESTful Web API而言，就是指URI，只有得到這個資源標識，才有可能找到該資源並對該資源進行操作。但是從概念上來講，資源和它的表述是分開的。例如，我們通過一個URI找到了服務端的Company這個資源，但是我們得到的Company這個資源的表述和服務端的Company是不一樣的，因為我們得到的是JSON格式（大多數情況）的Company數據。同時還有媒體類型（media type）對其進行描述，例如application/json等。如果請求的是xml格式的數據，那麼我們通常會得到xml格式表述的數據。所以同一個資源得到的表述也可能是不同的（例如JSON vs Xml）。 

  • 通過表述來對資源進行操縱：REST的組件對資源的操作（CRUD）是通過首先獲取該資源現有的表述或者目標表述，然後在組件之間完成從現有表述到目標表述的轉換。換句話講，當客戶端擁有資源表述的時候（包括可能的元數據），那麼它就應該擁有足夠的信息來修改或者刪除伺服器上的資源，前提是客戶端需要有這些許可權。例如，我從伺服器獲取到了Company的資源響應（包括元數據）之後，憑藉這些信息客戶端就應該可以成功的刪除或修改這個Company的資源數據了。但這又是怎麼實現的呢？如果伺服器上的Company API支持對Company進行刪除或者修改，那麼在我們獲取（GET）到這個Company資源的響應後，響應裡面應該包含著刪除或者修改這個Company資源的URI，通過這些URI客戶端就可以完成相應的操作。 

  • 帶有自我描述的信息：由於REST是無狀態的（沒有會話機制），所以發送REST請求的時候，必須把所有相關的信息隨著請求一起發送到伺服器端。換句話說，需要通過使用元數據或者其它方式，讓REST的請求中包含的數據必須帶有“自我描述”性的信息，以便讓對方知道如何處理該請求。 

  • 超媒體作為應用程式狀態的引擎（HATEOAS）：REST架構風格中，客戶端是通過超媒體與伺服器端動態提供的一個“應用網路”來進行交互的。這裡要求在首次進入REST網路時有第一個鏈接，還要求客戶端必須具備處理超媒體內容的能力。除此之外REST對客戶端來說再無其它要求。這是書上給出的解釋。舉個例子，本文第二段中提到用戶通過點擊網頁中的鏈接來進行跳轉的時候，瀏覽器的狀態就變化了。這些鏈接就是超文本，而超媒體就是超文本的泛化。針對API來說，它就是程式狀態的引擎。換句話說，超媒體會驅動如何消費和使用API，它會告訴API消費者使用這些API能做什麼，例如：能刪除這個資源嗎？能修改資源嗎？如何能創建這種資源？從哪能獲取這個資源？最終，它還允許自包含文檔的API。 

• 多層系統：REST的解決方案適用於多層架構，這些層可以被修改，可以被添加或刪除，可以是物理的，也可以是邏輯的。每一層只可以看到和它相鄰的上一層或下一層，其它非相鄰層的結構它完全看不到。這也說明客戶端無法得知它連接的是架構最終層還是連接到了某個中間層。所以REST僅僅知道一個層，也就是對外那一層，因為這個原因，整個系統的複雜性得到了控制，因為可以對任何局部的層次進行替換，而不至於影響整個系統。 

• 可緩存：每個響應信息必須明確的指出它是否可以被緩存。緩存響應數據可以減少客戶端感知的響應時間，提高整體的可用性和可靠性，並控制整個Web伺服器的負載。客戶端也可以在實時性和響應速度之間做出選擇，以便伺服器端相應的決定是從緩存還是從最終信息源哪裡獲得服務響應的內容。 

• 按需編碼（可選約束）：它描述了伺服器可以擴展或者定製客戶端的功能。例如如果客戶端是一個Web應用，那麼伺服器端可以發送一些javascript腳本給客戶端，以擴展客戶端的功能。但是這也造成了客戶端和伺服器端之間的技術耦合，因為客戶端必須能都懂得伺服器端發過來的代碼，所以這個約束是可選的。 

這些就是REST的約束，而沒有實現這些約束的Web API就不是RESTful API，所以現在見到的很多RESTful API並不是真的RESTful API，但是這也不能說明這些API就不好，只不過針對那些沒有實現的約束可能要做出一些權衡取捨，付出一些代價。 

Richardson 成熟度模型 

這個成熟度模型是由Leonard Richardson所提出的，這個模型是用來評價API的成熟度。它的結果分為0，1，3，4共四個級別。我們一個一個看。 

• Level 0，POX（Plain old xml）沼澤。它描述了API僅僅是使用HTTP協議來做遠程交互，而HTTP協議的其餘部分都是瞎用的，有時用出了RPC的風格(例如SOAP, 尤其是使用WCF的時候)。例如下麵這個程式都是在同一個URI上面進行讀取資源和創建資源的： 

• 換句話說，就是使用HTTP協議作為一種傳輸方式而已，沒有什麼規矩可言。 

• Level 1，資源。在這級里, 與Level 0不同，每個資源都映射到自己的URI上了, 但是HTTP方法並沒有正確的使用, 但是還是降低了一些複雜度。例如下麵這個例子使用了不同的URI，但是HTTP方法使用的都是POST： 

• Level 2，動詞。正確使用了HTTP動詞，例如GET、POST、DELETE、PUT、PATCH等等都是按照協議的意圖正確的使用了。狀態碼也正確的使用了，例如200表示成功，201表示創建成功等等。這也符合了統一資源介面/界面這個約束。從軟體開發角度，這也去掉了不必要的變種，因為我們使用同樣的動詞來做同類的事情。例如： 

• Level 3，超媒體。這意味著，API支持HATEOAS（超媒體作為應用狀態的引擎, Hypermedia as the Engine of Application State），這也是統一資源介面/界面約束裡面的一條。例如：