路由機制會把一個請求的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上面。
例如:
官方文檔:路由基礎知識。
不同的動作可以作用于相同的資源URI,例如擷取一個公司(api/company/3)和删除一個公司(api/company/3)的URI就是一樣的。但是它們的HTTP方法則不同,一個是GET,一個是DELETE。下面我們就來看看那些動作應該對應哪些 HTTP 方法。
需求:添加一個公司資訊。
需求圖解:
HTTP請求圖解:
文字解釋:
添加公司這個需求的HTTP表示就是 POST api/companies。
當我們向 api/companies這個标示添加一個公司資訊的時候,就會利用提供的公司資訊建立一個公司的資源。這裡對應的HTTP方法是POST。
POST請求的參數通常存放在請求的body裡面,是以公司的資訊就放在了body裡面。
當公司資源建立好之後,這個action應該傳回新建立的資源以及可以擷取該資源的路徑辨別,也就是api/companies/{新資源的id}。
需求:擷取一個公司資訊
我們想要通過 api/companies/{companyId} 這個标示來擷取一個公司資源,這裡就需要使用HTTP GET 方法,放在一起就是 GET api/companies/{companyId}。
GET請求總是會傳回請求 URI 所對應的資源,是以這個請求會傳回這個資源的内容。
需求:擷取符合查詢條件的公司資源
這個需求是按條件搜尋資源,可能傳回0個或者多個符合條件的資源。這裡我們使用HTTP的GET方法,如果想擷取所有的公司資源,那麼請求路徑是 api/companies;如果想擷取符合查詢條件的公司資源,那麼請求裡就需要一些參數,通常使用查詢字元串(query string)來傳遞參數,例如:
GET api/someresources?param1=value1&param2=value2
GET api/products?xxxxx=something
在這裡,參數是在問号?後邊,以name=value的形式存在。如果有多個查詢參數,它們之間使用 & 符号分隔開。
當搜尋資源的工作結束後,GET請求會傳回比對該路徑(包括參數部分)的資源。
需求:删除一個公司
HTTP 的 DELETE 方法就很好了解了,就是删除指定路徑的資源而已,而且不需要傳回任何東西。
需求:更新公司的資訊。
這裡有些初學者可能會出錯。HTTP 用來表示更新資訊的方法是 PATCH,是以整個請求時 PATCH api/companies/{companyId}。注意PATCH表示對資源進行局部更新。
和POST一樣,PATCH的參數也位于請求的body裡面。例如,如果你想更新公司的名稱,那麼就要把新的公司名稱放在body裡面。
PATCH的請求無需傳回任何東西。
需求:替換公司資訊。
HTTP 的 PUT 方法用于完全替換已存在的一個資源;或者如果辨別URI對應的資源不存在,那麼就建立一個資源。對于後一種情況,它的效果和添加操作是一樣的。
和 POST 一樣,PUT的參數也位于請求的body裡面。
如果是替換現有資源,那麼無需傳回任何東西;但如果是建立資源的操作,就應該傳回新建立的資源。
通過HTTP方法可進行的CRUD基本操作已經介紹的差不多了,但是這裡的CRUD隻是從API消費者的角度而言。例如,DELETE api/companies/12 并不意味着id為12的公司資訊從資料庫中被删除了,也許隻是把該公司的資訊的狀态設定為deleted而已。
對于不限于CRUD的其它操作,我們也得使用這些HTTP方法來進行表示,多少要進行一些妥協。
最後使用一張圖表總結一下這些HTTP方法對應的操作:
實際上還有 HTTP 的 OPTIONS 和 HEAD 也會直接或者間接的用到,這倆以後再說吧。
