使用ASP.NET Core 3.x 构建 RESTful API - 1. 开始
以前寫過ASP.NET Core 2.x的REST API文章,今年再更新一下到3.0版本。
預備知識:ASP.NET Core 和?C#?
工具:Visual Studio 2019最新版(VSCode、VS for Mac,Rider等也湊合),POSTMAN?
?
Web?API?
Web?API通常是指“使用HTTP協議并通過網絡調用的API”,由于它使用了HTTP協議,所以需要通過URI信息來指定端點。?
?
API是Application Programming Interface的縮寫,是軟件的外部接口。也就是說,針對某個軟件,人們可以知道它的外部功能,但并不知道(也不需要知道)它的內部運作細節,為了從外部調用某些功能,需要指定軟件的調用規范等信息,這樣的規范就是API。?
所以Web?API就是一個Web系統,通過訪問URI可以與其進行信息交互。?
?
大多數的?Web?API?并不是?RESTful API?
REST一詞是在2000年首次出現的,它是由Roy?Fielding博士在《架構風格以及基于網路的軟件架構設計》這篇論文中提到的。他為REST風格的API制定了一套約束規范或者叫架構風格。?
所以準確的說,只有符合了Roy?Fielding架構風格的Web?API才能稱作是RESTful API。但是在實際開發中,有時候也有不完全符合Roy?Fielding架構風格的情形出現,針對這點我將會在稍后的文章中介紹。?
?
MVC模式與RESTful API?
本系列文章中我將使用ASP.NET Core 3.0 MVC 來構建 RESTful API。?
?
MVC(Model-View-Controller)我認為是一種主要用來構建UI的架構模式。對于MVC模式其實有很多種解釋存在,但是無論那種解釋,它們都會強調松耦合和關注點分離(separation of concerns)。?
也是由于這兩點的存在,程序的可測試性會大大提高,程序各部分的可復用性也很高。?
更多關于MVC的介紹,可以看一下微軟的官方文檔:https://docs.microsoft.com/zh-cn/aspnet/core/mvc/overview?view=aspnetcore-3.0?
?
注意:MVC不是一個完整的應用程序架構,我認為它主要是用在展示層。所以實現UI就是MVC的一部分工作。?
?
如何把MVC映射到API
我認為API同樣可以看作是UI,它就是為API消費者所提供的UI。?
讓我們把MVC的三部分分別對應到API:?
Model,它負責處理程序數據的邏輯。這里的Model可以包含在當前級別獲取從存儲獲取數據的邏輯。但是有一些Model不包含任何邏輯,例如API所使用的DTO(Data transfer objects),這類的Model會被串行化到響應的body里面。?
View,它是程序里負責展示數據的那部分。在構建API的時候,View就是數據或資源的展示。現在通常使用JSON格式。?
Controller,它負責View和Model之間的交互。包括處理用戶輸入,用API的術語來講,和API交互的“用戶”就是指API的消費者,這類用戶通常是另一個程序,例如Angular的SPA程序。?
?
下面看看MVC這三部分的依賴關系:?
Controller和View依賴于Model,Controller依賴于View,這也是分離的一個好處。?
換句話說,Controller會選取適當的View來展現給用戶,并一同把用戶請求的Model數據帶回去。?
?
當API消費者發出請求的時候,在Controller上面的Action將會被觸發,Controller會把接收到的輸入數據發送給負責業務處理邏輯或數據訪問邏輯的那部分程序。然后Controller會把Model返回給View,這里的View就是資源的展示(通常是JSON格式)。?
?
接下來我們就是用這套概念和ASP.NET Core 3.0?來創建RESTful API。?
但是請注意,通過ASP.NET Core MVC或API模板建立出來的新項目,我們并不會直接得到RESTful(REST架構風格)的API。我們必須在這個基礎上,自己構建RESTful的API,因為之前已經提到了,標準的RESTful API有很多約束和規范。?
?
創建ASP.NET Core 3.0 Web API項目?
打開VS2019,選擇項目模板ASP.NET Core Web Application:?
?
然后為項目和解決方案起名字,并選擇所在目錄:?
?
然后選擇ASP.NET Core的項目模板:?
首先要選擇ASP.NET Core 3.0。?
這里我選擇了API這個模板。在以前,我通常會選擇Empty模板,因為其它模板通常包含很多我不需要的東西,但是ASP.NET Core 3.0的API模板還是比較干凈的,可以接受。?
最后,由于本課程中不需要使用HTTPS和Docker,所以把這兩個東西都勾掉。?
?
解剖?ASP.NET?Core 3.0 API?模板項目?
點擊Create,項目就建立好了:?
?
先看看?appsettings.json:?
里面只有默認的Log配置以及允許的Hosts。?
?
而appsettings.Development.json里面:?
也只有關于Log的默認配置。?
?
注意:您需要知道appsettings.json?和?appsettings.Development.json之間的關系,關于這點可以看我ASP.NET Core 3.0的入門視頻教程,但是更簡單的辦法是看一下官方文檔:在ASP.NET Core中使用多個環境。?
?
項目模板里還有兩個類我們不需要,所以把它刪掉,分別是WeatherForecastController和WeatherForecast:?
?
Program.cs:?
這里其實就是整個程序的入口,Main方法負責配置和運行整個Web程序。?
由于這是一個Web項目,所以我們還需要一個宿主(Host),這個宿主就是由下面的CreateHostBuilder方法來負責創建的。該方法首先會創建出一個實現了IHostBuilder接口的類(HostBuilder)的實例,然后調用它的Build方法來創建宿主(類型為Host,實現了IHost接口),最后調用宿主上面的Run方法來運行程序。?
?
我們暫時不修改這里面的代碼,所以一切都會按照項目模板默認的配置進行,注意到下面的方法里我們使用到了Startup這個類:?
所以我們來看看Startup類。?
?
Startup.cs?
在這個類的構造函數里:?
我們看到IConfiguration被注入了,這樣就允許我們使用配置信息了,例如appsettings.json里面的配置信息。?
?
下面有一個ConfigureServices方法:?
這個方法負責向服務容器里面注冊服務,已注冊的服務可以通過依賴注入的方式在整個應用程序的其它地方進行使用。這里的服務是一個比較廣義的概念,它就是一個在整個程序中做一些通用性操作的組件。?
?
這里面只有一句話:?
在3.0之前的版本里,這里面應該寫的是services.AddMvc();,實際上在ASP.NET?Core 3.0里面這樣寫也是可以的。但是AddMvc()里面不僅僅包含用于構建API的服務,還包含很多其它服務,例如構建View視圖和TagHelper相關的服務等。而AddControllers()方法只包含用于構建API的那些服務,例如Controller的支持、Model綁定、Data?Annotation和格式化器等等。?
?
最下面還有一個Configure方法:?
這個方法使用到了在ConfigureServices方法里面注冊和配置的服務,所以這個方法是在ConfigureServices方法之后被調用的。?
Configure方法是用來指定ASP.NET Core Web程序是如何響應每一個HTTP請求的。換句話說,也就是我們在這里配置請求的管道,配置的方法就是在這里添加很多中間件(Configure方法里面每一個app.UseXxx就是添加一個中間件,可以查看中間件的官方文檔來了解更多)。?
?
在開發環境的時候,如果有異常發生,那么會展示出一個異常頁面:?
?
app.UseAuthorization(),它會為整個Web程序添加授權的能力。當你需要考慮API安全性的時候,這點就很重要了。通常授權配置是在ConfigureServices方法里完成的,而我現在沒有對授權進行配置,但是app.UseAuthorization()仍然會允許API可以被匿名的訪問。?
?
其它這幾句話:?
這幾句話都是用來指定如何把HTTP請求分配到特定的Controller?Action上面的。也就是說這是關于路由的。?
?
很重要的一點就是:每一個請求會按照代碼的順序穿越所有在這里添加的中間件。但是每一個中間件都有可能將請求短路,這樣的話請求就不會進入下一個中間件了,而會按照原路返回。?
所以,添加中間件的順序非常重要。如果你把授權中間件放在了Controller的后邊,那么即使需要授權,那么請求也會先到達Controller并執行里面的代碼,這樣的話授權就沒有意義了。?
?
修改項目啟動配置?
我喜歡使用控制臺啟動Web程序,這樣可以很直觀的看到Log信息。為達到這個目的,可以修改launchSettings.json文件:?
?
修改后,在項目的Debug屬性里也有體現:?
由于我主要是使用POSTMAN來調用API,所以我不需要Launch?Browser(啟動瀏覽器)。?
?
運行程序?
可以看到程序可以正常運行,并且在控制臺上有日志的輸出。?
總結
以上是生活随笔為你收集整理的使用ASP.NET Core 3.x 构建 RESTful API - 1. 开始的全部內容,希望文章能夠幫你解決所遇到的問題。
- 上一篇: 求知无限,刷新.NET 中国社区
- 下一篇: .NET Core 3.1 编写混合 C