用ASP.NET Core 2.0 建立规范的 REST API -- 预备知识
什么是REST
REST 是 Representational State Transfer 的縮寫. 它是一種架構的風格, 這種風格基于一套預定義的規(guī)則, 這些規(guī)則描述了網(wǎng)絡資源是如何定義和尋址的.
一個實現(xiàn)了REST這些規(guī)則的服務就叫做RESTful的服務.
最早是由Roy Fielding提出的.
RPC 風格
/getUsers/getUser?id=1/createUser/deleteUser?id=4/updateUser?name=dave?
上面這些節(jié)點是針對User的CRUD操作.?
這種樣式風格的web服務更傾向于叫做RPC風格的服務.
在RPC的世界里, 節(jié)點僅僅就是可以在遠程被觸發(fā)的函數(shù), 而在REST的世界里, 節(jié)點就是實體, 也叫做資源.
REST的原則/約束
REST有6大原則/約束, 每一個原則都是對API有正面或負面影響的設計決定.
RESTful API 最關心的有這幾方面:?性能, 可擴展性, 簡潔性, 互操作性, 通訊可見性, 組件便攜性和可靠性.
這些方面被封裝在REST的6個原則里, 它們是:?
1.?客服端-服務端約束: 客戶端和服務端是分離的, 它們可以獨自的進化.
2.?無狀態(tài): 客戶端和服務段的通信必須是無狀態(tài)的, 狀態(tài)應包含在請求里的. 也就是說請求里要包含服務端需要的所有的信息, 以便服務端可以理解請求并可以創(chuàng)造上下文.
3.?分層系統(tǒng): 就像其它的軟件架構一樣, REST也需要分層結構, 但是不允許某層直接訪問不相鄰的層.?
4.?統(tǒng)一接口: 這里分為4點, 他們是: 資源標識符(URI), 資源的操作(也就是方法Method, HTTP動詞), 自描述的響應(可以認為是媒體類型Media-Type), 以及狀態(tài)管理(超媒體作為應用狀態(tài)的引擎 HATEOAS, Hypermedia as the Engine of Application State).
5.?緩存: 緩存約束派生于無狀態(tài)約束, 它要求從服務端返回的響應必須明確表明是可緩存的還是不可緩存的.
6.?按需編碼: 這允許客戶端可以從服務端訪問特定的資源而無須知曉如何處理它們. 服務端可以擴展或自定義客戶端的功能.
只有滿足了這6個原則的系統(tǒng)才可以真正稱得上是RESTful的, 其實大部分系統(tǒng)的RESTful API并不是RESTful的, 但這樣并不代表這些API就不好, 利弊需要開發(fā)人員去衡量.
Richardson 成熟度模型
Richardson 成熟度模型代表著你的API是否足夠成熟, 分為4個級別, 0代表最差, 3代表最好.
0級, 天花沼澤:
這里HTTP協(xié)議只是被用來進行遠程交互, 協(xié)議的其余部分都用錯了, 都是RPC風格的實現(xiàn)(例如SOAP, 尤其是使用WCF的時候).
例如:
POST (查詢數(shù)據(jù)信息) http://host/myapiPOST (創(chuàng)建數(shù)據(jù)) http://host/myapi?
1級, 資源:
這級里, 每個資源都映射到一個URI上了, 但是HTTP方法并沒有正確的使用, 結果的復雜度不算太高.
例如這兩個查詢:
POST http://host/api/authorsPOST http://host/api/authors/{id}?
2級, 動詞:
正確使用了HTTP動詞, 狀態(tài)碼也正確的使用了, 同時也去掉了不必要的變種.
例如:
GET http://host/api/authors200 Ok (authors) POST (author representation) http://host/api/authors201 Created (author)3級, 超媒體:
API支持超媒體作為應用狀態(tài)的引擎?HATEOAS, Hypermedia as the Engine of Application State, 引入了可發(fā)現(xiàn)性.
例如:
GET http://host/api/authors200 Ok (返回了authors 和 驅(qū)動應用程序的超鏈接)?
介紹ASP.NET Core
略.
但是, 你需要知道以下概念: .NET Core, .NET Standard.
還需要會使用下列工具: .NET Core CLI, Visual Studio 2017/Visual Studio Code/Visual Studio for Mac
ASP.NET Core 支持創(chuàng)建Web API, 但并不是直接支持RESTful的 Web API.
?
ASP.NET Core的基本知識
這部分還是需要簡單的介紹下, 如果已經(jīng)會了, 請略過本文其余部分.
創(chuàng)建ASP.NET Core項目
打開VS2017, 選擇ASP.NET Core Web Application項目模板, 寫好名字, OK.
?
選擇空模板, OK:
?
項目建立好了, 結果如下:
然后我們看一下項目文件, 右鍵編輯MyRestful.Api:
這里, SDK屬性表示了我們使用的是哪個SDK, 而目標框架是.NET Core 2.0.
(提示: 如果需要指向多個目標框架的話可以使用TargetFrameworks元素, 注意多了個s)
?
看一下Program.cs:
Main方法是程序的入口. 而Web的宿主是通過BuildWebHost函數(shù)來實例化的, 它調(diào)用了WebHost.CreateDefaultBuilder方法, 很明顯這是一個建造者模式, 它最終會構建出一個web宿主.
調(diào)用WebHost.CreateDefaultBuilder會返回一個IWebHostBuilder, 它允許我們進行一些配置動作.
程序啟動
UseStartup方法會注冊一個類, 這個類負責配置整個程序的啟動過程. 這里默認用的是Startup類.
Startup類有兩個方法 ConfigureServices (這個可以沒有) 和 Configure (這個必須有):
在Configure方法里, 配置應該遵循Add/Use的風格樣式, 首先定義需要什么, 然后定義如何使用它.
而在ConfigureServices方法里, 所有程序級的依賴項都可以在這里注冊到默認的IoC容器里, 把它們添加到IServiceCollection即可.
Configure方法才是真正負責配置HTTP請求管道的方法, 并且運行時也需要它.
IApplicationBuilder的擴展方法Run會傳遞一個RequestDelegate, 其內(nèi)部功能就是回寫Hello World.
?
ASP.NET Core還允許我們按約定為指定環(huán)境建立單獨的啟動配置. 啟動類可以通過這個函數(shù)定義UseStartup(startupAssemblyName: xxx); 運行時會在這個指定的組件查找叫做Startup, Startup[環(huán)境名]的類, 其中[環(huán)境名]就是ASPNETCORE_ENVIRONMENT這個環(huán)境變量的值. 如果能找到指定環(huán)境的類, 那么它將覆蓋默認的啟動類.?
例如 環(huán)境變量值如果是Developmen的話, 那么運行時就會嘗試尋找Startup和StartupDevelopment類, 該約定在啟動類里面的方法名上也有效, 環(huán)境特定的啟動類里的兩個方法分別是 Configure[環(huán)境名]和Configure[環(huán)境名]Services.
?
除了之前講的Run方法外, IApplicationBuilder還有一個Use擴展方法.
Use擴展方法接受RequestDelegate作為參數(shù)來提供HttpContext, 同時接受也為下一層準備的RequestDelegate參數(shù).
需要注意的是, Run方法和Use方法定義的順序非常重要, 運行時將會精確的按照創(chuàng)建的順序來執(zhí)行.
?
服務器
ASP.NET Core 服務器的作用是響應客戶端發(fā)過來的請求, 這些請求會作為HttpContext傳遞進來. ASP.NET Core 內(nèi)置兩種服務器:
Kestrel, 它是跨平臺的服務器, 基于Libuv.
HTTP.sys, 它是僅限Windows系統(tǒng)的服務器, 基于HTTP.sys內(nèi)核驅(qū)動.
下面就是從客戶端發(fā)請求到應用程序的流圖:
其中Kestrel可以作為一個獨立進程自行托管, 也可以在IIS里. 但是還是建議使用IIS或Nginx等作為反向代理服務器. 在構建API或微服務時, 這些服務器可以作為網(wǎng)關使用, 因為它們會限制對外暴露的東西也可以更好的與現(xiàn)有系統(tǒng)集成, 所以它們會提供額外的防御層,?
使用反向代理服務器(IIS)之后的流圖如下:
讓web宿主工作于IIS之后需要使用IWebHostBuilder的UseIISIntegration這個擴展方法.
除了內(nèi)置的兩種服務器, 您還可以使用自定義的服務器, 使用IWebHostBuilder的UserServer擴展方法, 它接受一個實現(xiàn)了IServer接口的實例, 您的自定義服務器需要實現(xiàn)該接口. 這里就不講了.
?
中間件
在應用程序請求管道內(nèi)裝配的組件就是中間件, 它們負責處理通過管道的請求和響應.
在HTTP請求管道的上下文里, 中間件可以叫做請求委托, 它們是由Run, Map 和 Use 擴展方法共同組建而成的.
每個中間件可以在它被調(diào)用之前和之后執(zhí)行可選的邏輯, 同時也可以決定該請求是否可以被送到管道的下一個中間件那里.
請求在中間件里的流圖如下:
看一下這個例子:
如果我在瀏覽器地址輸入?http://localhost:5000/return, 那么結果就是Returned!
如果輸入 http://localhost:5000/end, 那么是The End.
如果輸入?http://localhost:5000/xxx?value=1234, 結果是 the number is 1234
如果輸入?http://localhost:5000/xxx?value=abcde, 結果是?Hello, the value is abcde!
?
注意:?應用程序管道里的請求委托(中間件)定義的順序是非常重要的, 請求的時候按定義的順序執(zhí)行, 而響應的順序正好相反.
?
中間件最好不要像上面一樣寫在Startup類里, 每個中間件應該放在單獨的類里.?
我把上例中檢查是否為數(shù)字的中間件寫在一個單獨的類里:
這種中間件沒有實現(xiàn)特定的接口或者繼承特定類, 它更像是Duck Typing (你走起路來像個鴨子, 叫起來像個鴨子, 那么你就是個鴨子).
然后在Startup的Configure方法里調(diào)用app.UseMiddleware<NumberMiddleware>()即可:
?
路由
在ASP.NET Core里,使用路由中間件RouterMiddleware來處理路由.
想要使用路由, 同樣也是遵循 Add/Use 這個模式.?
首先在ConfigureServices方法里添加(Add):
然后在Configure方法里使用(Use):
UseRouter這個擴展方法可以接受IRouter或者Action<IRouterBuilder>作為參數(shù).
例如:
當發(fā)送?http://localhost:5000/ GET請求的時候, 返回 Default route.
當 GET http://localhost:5000/user/dave的時候, 返回 Hi dave
當 POST?http://localhost:5000/user/dave的時候, 返回 Hi, posted name is dave
其中{name}, 是名為name的參數(shù).
如果寫成"user/{name}/{age:number}", 那么age這個參數(shù)的必須可以被解析為數(shù)值型.
而"user/{name}/{gender?}", 這里的gender參數(shù)可以沒有.
?
Controller
HTTP請求通過管道最終到達Action并返回的流圖如下：
默認情況下Controller放在ASP.NET Core項目的Controllers目錄下。
在ASP.NET Core項目里可以通過多種方式來創(chuàng)建Controller，當然最建議的方式還是通過繼承AspNetCore.Mvc.Controller這個抽象類來建立Controller。
例如：
上例中類名可以不是以Controller結尾。
?
還有其它的方式創(chuàng)建Controller，按約定類名以Controller結尾的POCO類也會被認為是Controller，例如：
?
針對POCO類， 即使名稱不是以Controller結尾，仍然可以把它作為Controller，這就需要在類上面添加?[Controller]?這個屬性：
?
如果某個類的名字以Controller結尾， 但是你不想把它當作Controller，那么就應該為該類標注?[NonController]?這個屬性：
?
實際上， 看源碼就可以知道 Controller 繼承于 ControllerBase:
?
?而ControllerBase上面標注著?[Controller]?屬性。
?
Action
在Controller里面，可以使用public修飾符來定義Action，通常會帶有參數(shù)，可以返回任何類型，但是大多數(shù)情況下應該返回IActionResult。Action的方法名要么是以HTTP的動詞開頭，要么是使用HTTP動詞屬性標簽，包括：[HttpGet], [HttpPut], [HttpPost], [HttpDelete], [HttpHead], [HttpOptions], [HttpPatch].
例如：
其中某個方法名如果恰好是以HTTP的動詞開頭，那么可以通過標注?[NonAction]?屬性來表示這個方法不是Action。
通過繼承Controller基類的方法來創(chuàng)建Controller還是有很多好處的，因為它提供了很多幫助方法，例如：Ok, NotFound, BadRequest等，它們分別對應HTTP的狀態(tài)碼 200, 404, 400；此外還有Redirect，LocalRedirect，RedirectToRoute，Json，File，Content等方法。
?
為MVC定義路由有兩種方式：使用IRouteBuilder或者使用基于屬性標簽的路由。針對Rest，最好還是使用基于屬性標簽的方式。
路由屬性標簽可以標注在Controller或者Action方法上，例如：
Controller類上標注的路由“api/[controller]”，其中[controller] 就代表該類的名字去掉結尾Controller的部分，也就是“api/person”。
在Controller上使用[Route]屬性就定義了該Controller下所有Action的路由基地址，每個Action可以包含一個或者多個相對的路由模板（地址），這些路由模板可以在[Http...]中定義。但是如果使用?~?這個符號的話，該Action的地址將會是絕對路由地址，也就是覆蓋了Controller定義的基路由。
?
實體綁定
傳入的請求會映射到Action方法的參數(shù)，可以實原始數(shù)據(jù)類型也可以是復雜的類型例如Dto（data transfer object）或ViewModel。這個把Http請求綁定到參數(shù)的過程叫做實體綁定。
例如：
?
其中id參數(shù)是定義在路由里的，而name參數(shù)在路由里沒有，但是仍然可以從查詢參數(shù)中把name參數(shù)映射出來。
注意路由參數(shù)和查詢參數(shù)的區(qū)別，下面這個URL里val1和val2是查詢參數(shù)，它們是在url的后邊使用?和&分隔：
/product?val1=2&val2=10?
而針對上面的Action，下面這個URL的路由參數(shù)id就是123：
/api/first/123?
?
針對下面這個POST Action：
我們可以通過幾種方式為其傳遞類型為Person的參數(shù)。
可以使用查詢參數(shù)：/api/people?id=1&name=Dave
如果POST Json數(shù)據(jù)：
那么在Action里面得到的參數(shù)person的屬性值都是null。這是因為這樣的原始數(shù)據(jù)是包含在請求的Body里面，為了解決這個問題，你需要告訴Action從哪里獲取參數(shù)，針對這個例子就應該使用?[FromBody]?屬性標簽：
如果提交的是表單數(shù)據(jù)，那么就應該使用[FromForm]:
其它的出處還有?[FromHeader], [FromRoute], [FromServices]等。
再看一個FromHeader的例子：
?
如果使用復雜類型Person來獲取person參數(shù)好像不行，只能使用原始類型的吧？
?
實體驗證
ASP.NET Core內(nèi)置的實體驗證是通過驗證屬性標簽來實現(xiàn)的，大多數(shù)情況下這樣會很方便。
例如：
其中Display不是驗證標簽，但是通過它可以自定義屬性的顯式名稱，在其它錯誤信息里可以使用{0}來引用該名稱。
?
判斷實體參數(shù)是否符合要求，可以檢查ModelState.IsValid屬性，這個屬性也是由ControllerBase提供的，例如：
發(fā)送一個請求：
這是個不合理的參數(shù)，返回的是400 BadRequest，帶著驗證結果：
?
盡管大多數(shù)情況西，驗證屬性標簽都滿足要求，但是有時候還是需要進行一些靈活的驗證，你可以使用像FluentValidation這樣的第三方庫，也可以使用內(nèi)置的方式來實現(xiàn)自定義驗證。
ASP.NET Core內(nèi)置支持兩種方式來進行自定義驗證：通過繼承ValidationAttribute來創(chuàng)建自定義驗證屬性標簽，或者讓實體實現(xiàn)IValidatebleObject接口。
使用自定義驗證屬性標簽：
把該標簽放到name屬性上
使用剛才的請求，其結果是：
?
另一種方式，在Person類實現(xiàn)IValidatableObject接口
但是我使用這種方法并不好用，不知道我哪里用錯了！
?
過濾器
和中間件一樣，ASP.NET Core MVC的過濾器也可以在請求管道的特定階段的之前或之后執(zhí)行某些代碼。過濾器還可以有子管道，子管道里面包含著其它過濾器。
過濾器和中間件的區(qū)別：中間件是應用程序級別的，它可以處理每個發(fā)送過來的請求；而過濾器是針對MVC的，它只會處理發(fā)往MVC的請求。
ASP.NET Core MVC的過濾器分為5類：
授權過濾器，它是第一個運行的，它的作用就是判斷HTTP Context中的用戶是否擁有當前請求的權限，如果用戶沒有權限，那么它就會“短路”管道。
資源過濾器，在授權過濾器后運行，在管道其它動作之前，和管道動作都結束后運行。它可以實現(xiàn)緩存或由于性能原因執(zhí)行短路操作。它在實體綁定之前運行，所以它也可以對影響實體綁定。
Action過濾器，它在Action方法調(diào)用之前和之后立即執(zhí)行，它可以操作傳進Action的參數(shù)和返回的結果。
異常過濾器，針對在寫入響應Body之前發(fā)生的未處理的異常，它可以應用全局的策略，
結果過濾器，它可以在每個Action結果執(zhí)行之前和之后運行代碼，但也只是在Action方法無錯誤的成功完成后才可以執(zhí)行。
下圖標明了這些過濾器在管道中是如何交互的：
過濾器可以作為屬性標簽使用，或者也可以在Startup類里面進行全局注冊。
例子：
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc.Filters;
namespace MyRestful.Api.Filters
{
? ? public class DefaultNameFilter: IActionFilter, IAsyncActionFilter
? ? {
? ? ? ? public void OnActionExecuting(ActionExecutingContext context)
? ? ? ? {
? ? ? ? ? ? context.ActionDescriptor.RouteValues["name"] = "Anonymous";
? ? ? ? }
? ? ? ? public void OnActionExecuted(ActionExecutedContext context)
? ? ? ? {
? ? ? ? ? ? context.HttpContext.Response.Headers["X-Name"] = context.ActionDescriptor.RouteValues["name"];
? ? ? ? }
? ? ? ? public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
? ? ? ? {
? ? ? ? ? ? OnActionExecuting(context);
? ? ? ? ? ? var result = await next();
? ? ? ? ? ? OnActionExecuted(result);
? ? ? ? }
? ? }
}
全局注冊，在Startup里：
public void ConfigureServices(IServiceCollection services)
? ? ? ? {
? ? ? ? ? ? services.AddMvc(options =>
? ? ? ? ? ? {
? ? ? ? ? ? ? ? options.Filters.Add<DefaultNameFilter>();
? ? ? ? ? ? });
? ? ? ? }
或者自定義一個屬性標簽，內(nèi)部的代碼是一樣的：
using System;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc.Filters;
namespace MyRestful.Api.Filters
{
? ? public class DefaultUserNameFilterAttribute: Attribute, IActionFilter, IAsyncActionFilter
? ? {
? ? ? ? public void OnActionExecuting(ActionExecutingContext context)
? ? ? ? {
? ? ? ? ? ? context.ActionDescriptor.RouteValues["name"] = "Anonymous";
? ? ? ? }
? ? ? ? public void OnActionExecuted(ActionExecutedContext context)
? ? ? ? {
? ? ? ? ? ? context.HttpContext.Response.Headers["X-Name"] = context.ActionDescriptor.RouteValues["name"];
? ? ? ? }
? ? ? ? public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
? ? ? ? {
? ? ? ? ? ? OnActionExecuting(context);
? ? ? ? ? ? var result = await next();
? ? ? ? ? ? OnActionExecuted(result);
? ? ? ? }
? ? }
}
然后把該標簽用在Action方法上即可：
[DefaultUserNameFilter]
? ? ? ? [HttpGet("first/{id}")]
? ? ? ? public IActionResult FindFirstPerson(int id, string name)
? ? ? ? {
? ? ? ? ? ? return null;
? ? ? ? }
?
格式化響應結果
Action的結果最好使用IActionResult, 但也可以使用其他類型，例如IEnumerable<T>等。強制結果輸出為特定的類型可以通過調(diào)用特定的方法來實現(xiàn)，例如JsonResponse就是輸出JSON，ContentResponse就是輸出文本。另外也可以使用[Produces(xxx)] 這個過濾器，它可以應用于全局，controller或者Action。
在REST服務里，有個詞叫內(nèi)容協(xié)商，它表示客戶端通過Accept Header里的media-type來指定所需的結果格式。
ASP.NET Core MVC 默認實現(xiàn)并使用JSON格式化，但也支持其它格式，這需要在startup里面注冊。
客戶端瀏覽器可能在請求的Accept Headers里提供了多種的格式，但是ASP.NET Core MVC 默認是忽略瀏覽器的Accept Header的，并使用標準的輸出格式。但是修改MvcOptions的RespectBrowserAcceptHeader值為true，可以改變這個行為:
ASP.NET Core還提供了 XML 格式，可以在MvcOptions里面添加：
?
今天先寫到這，還沒有切入正題。
原文地址: https://www.cnblogs.com/cgzl/p/9010978.html
.NET社區(qū)新聞，深度好文，歡迎訪問公眾號文章匯總 http://www.csharpkit.com
總結
以上是生活随笔為你收集整理的用ASP.NET Core 2.0 建立规范的 REST API -- 预备知识的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 从Xamarin.Essentials谈
- 下一篇： 使用ML.NET预测纽约出租车费