之前講了RESTful API的統一資源介面這個約束，里面提到了資源是通過URI來進行識別的，每個資源都有自己的URI，URI里還涉及到資源的名稱，而針對資源的名稱卻沒有一個標準來進行規范，但是業界還是有一些最佳實踐的，那么我們首先看看這些最佳實踐對資源命名是如何建議的， 

資源命名 

下面讓我們來看看RESTful API資源命名的一些最佳實踐， 

使用名詞，而不是動詞 

一個資源的URI代表的是一個實際上或概念上存在的東西，因此，它應該是名詞，所以也就不應該出現動詞，動詞應該使用HTTP方法來表達， 

需求：我們看這樣一個需求的例子：“我想獲得系統里所有的用戶”， 

常見錯誤做法：你可能把API的URI設計成這樣：api/getusers，這樣的設計是不好的，因為里面出現了一個動詞get， 

分析：這個句話的主要動詞就是“獲取”，而想要獲取的資源（也就是主要的名詞）是“用戶”， 

正確的做法：需求里面主要的動詞應該通過HTTP方法來體現，“獲取”對應的HTTP方法就是GET，而“用戶”這個資源可以用英文user或者users來表示（是否使用復數一直存在爭議，兩種方法都行，但你在使用的時候需要保持一致），所以正確的uri應該是 GET api/user， 

人類能讀懂 

還是上面那個需求：“我想獲得系統里所有的用戶”， 

我們可以把uri設計成 api/u 或者 api/ur，但是這樣設計的話，對API的消費者來說非常的不友好，因為不能直觀的看出來它到底代表的是什么資源，可能是user，也可能是university， 

所以建議的做法是要足夠友好，并且比較簡短，例如：api/users， 

要體現資源的結構關系 

假設如果后端API系統里面有若干種資源，而用戶這個資源與其它的資源并沒有直接的關系，這樣的話獲取用戶資源的uri應該是 api/users，而不是 api/products/users，也不是api/catalogs/products/users，因為user和product或者catalog沒有直接的關系， 

通過id獲取單個用戶的uri應該是：api/users/{userId}，而不是api/userid/users， 

這樣寫的好處是可以讓API具有很好的可預測性和一致性， 

需求1：系統里有兩類資源，公司（Company）和員工（Employee），它們倆是包含關系，也就是一個公司包含多個員工，現在我想獲取某個公司下所有的員工資訊， 

分析：這里的主要動詞還是“獲取”，所以我們可以使用HTTP的GET，而這里的資源有兩個，分別是公司和員工，而且它們是包含關系：一個公司包含多個員工或者說一個公司是一個員工的集合，所以API的URI在設計的時候需要體現這種包含關系， 

常見的錯誤做法：如果你想獲得公司這個資源，我想你現在應該不會出錯，uri應該是 api/companies，而想要獲取某個公司下的員工，常見的錯誤做法有：api/employees，api/employees/{companyId}等等，這些設計非常不好是因為它無法體現出Company和Employee之間的結構關系， 

建議的做法：需要體現Company和Employee之間的關系，所以uri應該是GET api/companies/{companyId}/employees，這樣做直接體現出了Company和Employee之間的結構關系，而且也體現出了一個Company就是一個Employee的集合體， 

需求2：我想獲取某個公司的某個員工資訊， 

常見的錯誤做法：api/employees/{employeeId}，api/companies/{employeeId}等等，這些做法都無法體現出Company和Employee之間的關系， 

建議的做法：api/companies/{companyId}/employees/{employeeId}， 

自定義查詢怎么命名 

我們經常會遇到這樣的需求，比如獲取按照某個資源排序后的資源，或者按照某些條件過濾后的資源，這時候應該怎對資源進行命名呢？ 

需求：“我想獲取所有的用戶資訊，并要求結果是按年齡從小到大進行排列的”， 

常見錯誤的做法：api/users/orderby/age，之前說了，uri里面使用的都應該是名詞，如果按照這個uri的結構來看，那么orderby和age就應該是另外兩個資源，并且users包含orderby，orderby包含age，這顯然是錯誤的， 

建議的做法：api/users?orderby=name，這樣設計更合理一些，這里使用了query string作為查詢引數進行排序， 

例外 

有一些需求總是無法滿足的達到RESTful的約束， 

需求：“我想獲取系統里所有用戶的數量”， 

妥協的做法：我們確實可以先通過 GET api/users來獲取系統里所有的用戶資訊，然后再算出用戶的數量，但是這樣做也太浪費資源并且效率也太低了，我們也很難使用某個名詞來表示這個需求的資源，例如：api/users/totalamountofuser，這樣的uri按理說就代表著我們將會獲取到一個集合資源，里面是一堆數字，但針對這個需求，我也沒有特別好的辦法讓uri命名完全符合RESTful的約束，所以針對這個需求，我使用的就是這個uri， 

Demo

下面我們就來實踐一下，打開之前的專案，并建立CompaniesController： 

這里有6個地方比較關鍵，我們挨個看一下： 

1. RESTful API 或者其它Web API的Controller都應該繼承于 ControllerBase 這個類（點此查看詳細的官方檔案），而不是Controller這個類， 

   1. Controller類繼承于ControllerBase，Controller添加了對視圖的支持，因此它更適合用于處理 MVC Web 頁面，而不是 Web API，但是如果你的Controller需要同時支持MVC Web頁面和Web API，那么這時候就應該繼承于Controller這個類， 

   2. ControllerBase 類提供了很多用于處理 HTTP 請求的屬性和方法， 例如，ControllerBase.CreatedAtAction 回傳 201 狀態代碼，關于ControllerBase的屬性和方法的詳細串列，請查看官方參考檔案， 

2. [ApiController]，這個屬性是應用于Controller的，它其實并不是強制的，但是它提供了一些幫助，使得Web API的開發體驗更好，詳細教程請點擊 [ApiController]的官方檔案，在Controller上面添加了[ApiController]屬性之后，就會啟用以下行為： 

   1. 要求使用屬性路由（Attribute Routing），也就是不能通過Startup的Configure方法統一配置路由模板，這部分的詳細介紹請點擊：官方檔案， 

   2. 自動HTTP 400回應，也就是Action方法傳入的model含有驗證錯誤的時候，自動觸發HTTP 400回應，這部分的詳細介紹請點擊：官方檔案， 

   3. 推斷引數的系結源，它將會推斷出Action方法的引數到底來自哪個系結源，例如[FromBody]、[FromForm]等等，這部分的詳細介紹請點擊：官方檔案， 

   4. Multipart/form-data 請求推斷，使用 [FromForm] 屬性批注操作引數時，[ApiController] 屬性將應用推斷規則，它會推斷 multipart/form-data 為請求的內容型別，這部分的詳細介紹請點擊：官方檔案， 

   5. 錯誤狀態代碼的問題詳細資訊，MVC 會將錯誤結果（狀態代碼為 400 或更高的結果）轉換為狀態代碼為 ProblemDetails 的結果， ProblemDetails 型別基于 RFC 7807 規范，用于提供 HTTP 回應中計算機可讀的錯誤詳細資訊，這部分的詳細介紹請點擊：官方檔案， 

3. 我們需要通過建構式注入ICompanyRepository，并把它存放在一個只讀的欄位里面， 

4. 如果注入的ICompanyRepository的實體為null，那么就拋出一個ArgumentNullException， 

5. 想要回傳資料結果，我們需要在Controller里面添加一個Action方法，我暫時把它的回傳型別寫為IActionResult（詳細介紹請點擊官方檔案），IActionResult里面定義了一些合約，它們可以代表Action方法回傳的結果， 

6. 我暫時只想把結果序列化為JSON格式并回傳，這里我new了一個JsonResult（參考檔案），它可以做這項作業， 

目前我只做了這幾項最基本的作業：創建Controller，注入Repository，創建Action方法并回傳結果，下面運行一下看看報了什么錯： 

這是因為GetCompanies這個Action方法并沒有使用屬性路由（Attribute Routing），關于路由這部分，下一篇文章再介紹， 

標籤：ASP.NET

上一篇：.net 呼叫C++ dll

下一篇：序列化物件設定欄位首字母小寫(駝峰命名法)