使用ASP.NET Core 3.x 構建 RESTful API - 3.2 路由和HTTP方法

ASP.NET Core 3.x 的路由

路由機制會把一個請求的URI映射到一個Controller上面的Action，因此當你發送一個HTTP請求的時候，MVC框架會解析這個請求的URI，並嘗試着把它映射到一個Controller上面的Action。 

 

兩個路由中間件 

在ASP.NET Core 3.x裏面，建議使用Endpoint路由來進行設置。可是咱們須要先在請求的管道里面添加兩個中間件： 

• app.UseRouting()。它是用來標記路由決策在請求管道里發生的位置，也就是在這裏會選擇端點。 

• app.UseEndpoints()。它是用來標記選擇好的端點在請求管道的什麼地方來執行。 

這樣作的好處就是，咱們能夠在選擇端點和執行端點的中間位置插入其它的中間件。這樣的話，插入到中間位置的中間件就會知道哪一個端點被選取了，並且它也有可能會選擇其它的端點。 

 

一個很是好的例子就是受權中間件： 

若是受權成功，那麼就繼續執行到以前選定的端點，不然的話就會跳轉到其它端點或者短路返回。 

 

官方文檔：Startup裏面路由配置的官方文檔。 

 

映射端點 

仍是能夠有兩種方式進行設置：基於約定 或者 基於屬性。 

基於約定的路由，例如這兩種： 

這種方式更適合於服務器端的Web應用程序。 

 

而針對Web API，使用基於屬性的路由更加適合： 

能夠看到，這裏面僅僅映射了Controller，並無使用任何約定，因此咱們須要採用屬性（Attribute）來進行設定。這裏須要用到屬性（attribute）和URI模板。 

• 屬性（Attribute）。例如[Route]，[HttpGet]，[HttpPost]等等，能夠把它們放在Controller級別，也能夠放在Action級別上。 

• URI模板。將屬性結合URI模板一塊兒使用，就能夠把請求映射到Controller的Action上面。 

 

例如： 

 

官方文檔：路由基礎知識。 

 

HTTP 方法

不一樣的動做能夠做用於相同的資源URI，例如獲取一個公司（api/company/3）和刪除一個公司（api/company/3）的URI就是同樣的。可是它們的HTTP方法則不一樣，一個是GET，一個是DELETE。下面咱們就來看看那些動做應該對應哪些 HTTP 方法。 

 

POST 

需求：添加一個公司信息。 

需求圖解： 

 

HTTP請求圖解： 

 

文字解釋： 

添加公司這個需求的HTTP表示就是 POST api/companies。 

當咱們向 api/companies這個標示添加一個公司信息的時候，就會利用提供的公司信息建立一個公司的資源。這裏對應的HTTP方法是POST。 

POST請求的參數一般存放在請求的body裏面，因此公司的信息就放在了body裏面。 

當公司資源建立好以後，這個action應該返回新建立的資源以及能夠獲取該資源的路徑標識，也就是api/companies/{新資源的id}。 

 

GET 

獲取單個資源 

需求：獲取一個公司信息 

需求圖解： 

 

HTTP請求圖解： 

 

文字解釋： 

咱們想要經過 api/companies/{companyId} 這個標示來獲取一個公司資源，這裏就須要使用HTTP GET 方法，放在一塊兒就是 GET api/companies/{companyId}。 

GET請求老是會返回請求 URI 所對應的資源，因此這個請求會返回這個資源的內容。 

 

獲取集合資源 

需求：獲取符合查詢條件的公司資源 

需求圖解： 

 

HTTP請求圖解： 

 

這個需求是按條件搜索資源，可能返回0個或者多個符合條件的資源。這裏咱們使用HTTP的GET方法，若是想獲取全部的公司資源，那麼請求路徑是 api/companies；若是想獲取符合查詢條件的公司資源，那麼請求裏就須要一些參數，一般使用查詢字符串（query string）來傳遞參數，例如： 

GET api/someresources?param1=value1&param2=value2 

GET api/products?xxxxx=something 

在這裏，參數是在問號？後邊，以name=value的形式存在。若是有多個查詢參數，它們之間使用 & 符號分隔開。 

當搜索資源的工做結束後，GET請求會返回匹配該路徑（包括參數部分）的資源。 

 

DELETE 

需求：刪除一個公司 

需求圖解： 

 

HTTP請求圖解： 

 

文字解釋： 

HTTP 的 DELETE 方法就很好理解了，就是刪除指定路徑的資源而已，並且不須要返回任何東西。 

 

PATCH 

需求：更新公司的信息。 

需求圖解： 

 

HTTP請求圖解： 

 

文字解釋： 

這裏有些初學者可能會出錯。HTTP 用來表示更新信息的方法是 PATCH，因此整個請求時 PATCH api/companies/{companyId}。注意PATCH表示對資源進行局部更新。 

和POST同樣，PATCH的參數也位於請求的body裏面。例如，若是你想更新公司的名稱，那麼就要把新的公司名稱放在body裏面。 

PATCH的請求無需返回任何東西。 

 

PUT 

需求：替換公司信息。 

需求圖解： 

 

HTTP請求圖解： 

 

文字解釋： 

HTTP 的 PUT 方法用於徹底替換已存在的一個資源；或者若是標識URI對應的資源不存在，那麼就建立一個資源。對於後一種狀況，它的效果和添加操做是同樣的。 

和 POST 同樣，PUT的參數也位於請求的body裏面。 

若是是替換現有資源，那麼無需返回任何東西；但若是是建立資源的操做，就應該返回新建立的資源。 

 

綜上 

經過HTTP方法可進行的CRUD基本操做已經介紹的差很少了，可是這裏的CRUD只是從API消費者的角度而言。例如，DELETE api/companies/12 並不意味着id爲12的公司信息從數據庫中被刪除了，也許只是把該公司的信息的狀態設置爲deleted而已。 

對於不限於CRUD的其它操做，咱們也得使用這些HTTP方法來進行表示，多少要進行一些妥協。 

 

最後使用一張圖表總結一下這些HTTP方法對應的操做： 

 

實際上還有 HTTP 的 OPTIONS 和 HEAD 也會直接或者間接的用到，這倆之後再說吧。