幾天前,我和我的朋友們使用 ASP.NET Core 開發(fā)了一個API ,使用的是GET方式,將一些數(shù)據(jù)返回到客戶端 APP。我們在前端進(jìn)行了分頁,意味著我們將所有數(shù)據(jù)發(fā)送給客戶端,然后進(jìn)行一些data.length
操作,以獲得items count
用于分頁邏輯。為了減少HTTP請求的負(fù)荷,我們決定在后端(服務(wù)器端分頁)實現(xiàn)邏輯。在我們這樣的情況下,這是沒有任何問題的,因為我們在客戶端能快速實現(xiàn)。我們在客戶端和服務(wù)端修改了所有邏輯,并且快速完成所有功能。
但是,您可能會有其他客戶端在使用,因為只提供了一個數(shù)據(jù)源(API)。在一個API中引入突破性的變化可以支持一個客戶端,但同時破壞了其它客戶端。例如,假設(shè)您的手機(jī)團(tuán)隊正在度假,并且您的 Web 團(tuán)隊正在為了支持該服務(wù)器端分頁功能開展工作。為了支持Web團(tuán)隊,您在API中做了一個簡單的更改。這個變更,您和您的Web團(tuán)隊都很高興(如果感到幸福你就拍拍手)。噩夢開始了,您會發(fā)現(xiàn)因為一個很簡單(其實是突破性)的變化,數(shù)百萬移動客戶端不工作,用戶會卸載APP。當(dāng)您發(fā)現(xiàn)你們都不是移動應(yīng)用程序開發(fā)人員,也沒有訪問源代碼權(quán)限時,更多的惡夢來了?,F(xiàn)在您只能選擇降級您的 API 和 Web 應(yīng)用程序,但是,Web 應(yīng)用程序的開發(fā)團(tuán)隊現(xiàn)在也去度假了。因為更多的惡夢會接踵而至,所有的事情都只能停滯不前。
也許(不是也許,就是?。〢PI版本控制是在這種情況下,是一個非常不錯的選擇。使用 API 版本控制,您不僅可以安全地針對這些突破性的更改,還可以支持這些更改,這對每個人都是雙贏的。
我們來看一看如何在 ASP.NET Core 中配置 API 版本。
注意:我正在使用一個空的 ASP.NET Core Web API 項目(.NET Core 1.1)
通過 NuGet 安裝此軟件包:Microsoft.AspNetCore.Mvc.Versioning。現(xiàn)在,在Startup.cs
類的ConfigureServices()
方法中配置服務(wù)(services.AddApiVersioning()
):
public void ConfigureServices(IServiceCollection services){ services.AddMvc(); services.AddApiVersioning(); }
當(dāng)您使用的是Microsoft.AspNetCore.Mvc.Versioning
的1.1.1
版本時,只需要使用app.UseApiVersioning()
方法:
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory){ /* garbage code removed */ app.UseMvc(); app.UseApiVersioning(); }
接下來,您必須使用ApiVersion
定義要支持 API 版本控制的控制器(多個版本)。同樣,您還必須使用MapToApiVersion
定義特定Action
API版本號:
[ApiVersion("1.0")] [Route("api/[controller]")]public class ValuesController : Controller{ // GET api/values [MapToApiVersion("1.0")] [HttpGet] public IEnumerable<string> Get() { return Json(new string[] { "value1", "value2" }); } }
現(xiàn)在通過GET
方式的調(diào)用Action
,您必須指定 API 版本,暫時使用查詢字符串版本控制方式。這樣,您將直接在查詢字符串中指定 API 版本。例如這個:http://localhost:5000/api/values?api-version=1.0。
如果您將 API 版本控制添加到現(xiàn)有的API項目中,則可以告知 ASP.NET Core 將默認(rèn)的控制器和Action視為版本1.0
。為此,配置AddApiVersioning()
服務(wù)如下所示:
services.AddApiVersioning(options => options.AssumeDefaultVersionWhenUnspecified = true);
現(xiàn)在可以像這樣 http://localhost:5000/api/values 調(diào)用API ,不會導(dǎo)致任何錯誤。
可以通過三種方式指定API版本:
查詢字符 (已經(jīng)討論過)
URL路徑
媒體類型(Media Type)
通過URL路徑的方式,您可以將版本號作為URL路徑的一部分傳遞。像這樣的例子 http://localhost:5000/api/v1/values 。順便說一句,您必須修改您的路由屬性以適應(yīng)版本段,如下所示:
[ApiVersion("1.0")] [Route("api/v{version:apiVersion}/[controller]")]public class ValuesController : Controller{ [HttpGet, MapToApiVersion("1.0")] public IActionResult Get() { return Json(new string[] { "value1", "value2" }); } }
請注意,字母v
不是強制要添加在版本號之前,這只是一個慣例。
最后,您可以將服務(wù)配置為從特定的媒體類型(默認(rèn)情況下,從content-type媒體類型讀取,您可以配置自己的媒體類型)讀取API版本號。如下所示,配置您的服務(wù),以激活媒體類型版本控制:
public void ConfigureServices(IServiceCollection services){ // Add framework services. services.AddMvc(); services.AddApiVersioning(options => { options.ApiVersionReader = new MediaTypeApiVersionReader(); options.AssumeDefaultVersionWhenUnspecified = true; options.ApiVersionSelector = new CurrentImplementationApiVersionSelector(options); }); }
現(xiàn)在,當(dāng)您發(fā)送HTTP請求時,在請求頭中content-type
指定API版本號,如下所示(content-type: application/json;v=2.0):
順便說一句,使用CurrentImplementationApiVersionSelector
,如果沒有在content-type
媒體類型中定義版本,將使用最新的API版本。在下面的示例中,我沒有提到任何版本號,所以它在所有版本中使用最新版本。
這不是全部的功能,還有其它很酷的功能,您可以在 Microsoft 的 Microsoft's ASP.NET API Versioning git存儲庫中找到這些功能:https://github.com/Microsoft/aspnet-api-versioning/wiki。
發(fā)現(xiàn)一篇同類型的文章,講解的更詳細(xì),供大家參考:http://www.talkingdotnet.com/support-multiple-versions-of-asp-net-core-web-api/。
原文地址: https://www.codeproject.com/Tips/1197505/ASP-NET-Core-API-Versioning-in-Simple-Words-Update
翻譯:Sweet Tang
本文地址:http://www.cnblogs.com/tdfblog/p/asp-net-core-api-versioning.html
歡迎轉(zhuǎn)載,請在明顯位置給出出處及鏈接。
如果您覺得閱讀本文對您有幫助,請點一下“推薦”按鈕,您的“推薦”將是我最大的寫作動力!
歡迎各位轉(zhuǎn)載,轉(zhuǎn)載文章之后必須在文章頁面明顯位置給出作者和原文連接。
http://www.cnblogs.com/tdfblog/p/asp-net-core-api-versioning.html