使用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()。它是用來標記選擇好的端點在請求管道的什么地方來執行。 

這樣做的好處就是,我們可以在選擇端點和執行端點的中間位置插入其它的中間件。這樣的話,插入到中間位置的中間件就會知道哪個端點被選取了,而且它也有可能會選擇其它的端點。 

 

一個非常好的例子就是授權中間件: 

app . UseRouting( ) ; 
app . UseAuthorization( ) ; 
app . UseEndpoints( endpoints 
endpoints .MapControllers( ) ;

如果授權成功,那么就繼續執行到之前選定的端點,否則的話就會跳轉到其它端點或者短路返回。 

 

 

映射端點 

還是可以有兩種方式進行設置:基于約定 或者 基于屬性 

基于約定的路由,例如這兩種: 

app . UseEndpoints( endpoints 
endpoints . MapControllerRoute( 
"default", 
name : 
" {controller=Home} ) ; 
pattern: 
endpoints .MapRazorPages( ) ;

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

 

而針對Web API,使用基于屬性的路由更加適合: 

app . UseEndpoints( endpoints 
endpoints .MapControllers( ) ;

可以看到,這里面僅僅映射了Controller,并沒有使用任何約定,所以我們需要采用屬性(Attribute)來進行設定。這里需要用到屬性(attribute)和URI模板。 

  • 屬性(Attribute)。例如[Route][HttpGet][HttpPost]等等,可以把它們放在Controller級別,也可以放在Action級別上。 

  • URI模板。將屬性結合URI模板一起使用,就可以把請求映射到ControllerAction上面。 

 

例如: 

ApiController] 
Route( template: "api/companies " ) ] 
I reference 
public class CompaniesController 
ControllerBase 
private readonly ICompanyRepository 
companyRepos i tory ; 
O references 
public CompaniesController(ICompanyRepository companyRepository) 
HttpGet 
O references 
public async Task<IActionResult> GetCompanies() 
await companyRepository .GetCompaniesAsync() ; 
var companies = 
return new JsonResult(companies);

 

官方文檔:路由基礎知識 

 

HTTP 方法

不同的動作可以作用于相同的資源URI,例如獲取一個公司(api/company/3)和刪除一個公司(api/company/3)的URI就是一樣的。但是它們的HTTP方法則不同,一個是GET,一個是DELETE。下面我們就來看看那些動作應該對應哪些 HTTP 方法 

 

POST 

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

需求圖解: 

添 加 
, 加 好 的 
公 司 信 , 
公 司 信 , 
公 司 資 源

 

HTTP請求圖解: 

POST api/companies 
POST 對 應 的 操 作 
就 是 建 立 資 源 
POST 的 參 數 放 在 
請 求 的 body 里 面 
POST 
ompany 信 息 
在 body 里 
pi/companies/{ 生 成 的 id} 
的 內 容 
POST 請 求 應 該 返 回 新 創 建 的 資 源 
以 及 可 以 獲 取 該 資 源 的 唯 一 標 識 U 剛 
api/Compan ies

 

文字解釋: 

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

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

POST請求的參數通常存放在請求的body里面,所以公司的信息就放在了body里面。 

當公司資源創建好之后,這個action應該返回新創建的資源以及可以獲取該資源的路徑標識,也就是api/companies/{新資源的id} 

 

GET 

獲取單個資源 

需求:獲取一個公司信息 

需求圖解: 

獲 取 
公 司 信 
公 司 資 源

 

HTTP請求圖解: 

GET api/companies/{compayld} 
GET 對 應 的 動 作 就 是 
獲 取 資 源 
G ET 
GET 請 求 會 返 回 請 求 路 徑 所 對 應 的 資 源 
pi/companies/{companyld} 
的 內 容 
不 需 要 參 數 
api ℃ ompanies/{companyld} 
通 過 這 種 形 式 (URI) 來 表 示 公 司 資 源 中 的 一 個 公 司

 

文字解釋: 

我們想要通過 api/companies/{companyId} 這個標示來獲取一個公司資源,這里就需要使用HTTP GET 方法,放在一起就是 GET api/companies/{companyId} 

GET請求總是會返回請求 URI 所對應的資源,所以這個請求會返回這個資源的內容。 

 

獲取集合資源 

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

需求圖解: 

獲 取 
符 合 條 件 的 
公 司 信 息 
查 詢 條 件 
公 司 資 源

 

HTTP請求圖解: 

GET api/companies?param1=xx&param2=xx... 
GET 對 應 的 動 作 就 是 
獲 取 資 源 
GET 
GET 請 求 會 返 回 請 求 路 徑 所 對 應 的 資 源 
pi/companies/{companyldl} 
api/companies/{companyldn} 
的 內 容 
自 定 義 的 
查 詢 參 
G ET 的 參 數 是 資 源 地 址 ? 后 邊 的 部 分 , 
例 如 GET api/companies?name=Nick 
api.Com pan ies

 

這個需求是按條件搜索資源,可能返回0個或者多個符合條件的資源。這里我們使用HTTP的GET方法,如果想獲取所有的公司資源,那么請求路徑是 api/companies;如果想獲取符合查詢條件的公司資源,那么請求里就需要一些參數,通常使用查詢字符串(query string)來傳遞參數,例如: 

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

GET api/products?xxxxx=something 

在這里,參數是在問號?后邊,以name=value的形式存在。如果有多個查詢參數,它們之間使用 & 符號分隔開 

當搜索資源的工作結束后,GET請求會返回匹配該路徑(包括參數部分)的資源。 

 

DELETE 

需求:刪除一個公司 

需求圖解: 

刪 除 
公 司 資 源

 

HTTP請求圖解: