支持多個版本的ASP.NET Core Web API

基本配置及說明php

版本控制有助於及時推出功能,而不會破壞現有系統。 它還能夠幫助爲選定的客戶提供額外的功能。 API版本能夠經過不一樣的方式完成,例如在URL中添加版本或經過自定義標頭和經過Accept-Header做爲查詢字符串參數。 在這篇文章中,咱們來看看如何支持多版本的ASP.NET Core Web APIapi

建立一個ASP.NET Core Web API應用程序。經過 NuGet 安裝此軟件包:Microsoft.AspNetCore.Mvc.Versioning,打開Startup.cs,修改ConfigureServices方法,代碼以下:瀏覽器

[源碼]  view plain
  1. public void ConfigureServices(IServiceCollection services)  
  2. {  
  3.     services.AddMvc();  
  4.     services.AddApiVersioning(option =>  
  5.     {  
  6.         option.ReportApiVersions = true;  
  7.         option.AssumeDefaultVersionWhenUnspecified = true;  
  8.         option.DefaultApiVersion = new ApiVersion(1, 0);  
  9.     });  
  10. }  

你能夠看到配置了3個不一樣的選項:測試

ReportAPIVersions :這是可選的。 可是當設置爲true時,API會在響應頭中返回受支持的版本信息。AssumeDefaultVersionWhenUnspecified :此選項將用於在沒有版本的狀況下提供請求。 假定的API版本默認爲1.0DefaultApiVersion :此選項用於指定在請求中未指定任何版本時要使用的默認API版本。 這將默認版本爲1.0spa

這就是配置和設置。 如今咱們將看到訪問API版本的不一樣方法。版本控制

Via Query String(經過查詢字符串)code

打開Controller 類,而後用ApiVersion屬性裝飾控Controller類。 像下面這樣,blog

[源碼]  view plain
  1. namespace MultipleAPIVersions.Controllers  
  2. {  
  3.     [ApiVersion("1.0")]  
  4.     [Route("api/[controller]")]  
  5.     public class ValuesController : Controller  
  6.     {  
  7.         [HttpGet]  
  8.         public IActionResult Get() => Ok(new string[] { "value1" });  
  9.     }  
  10. }  

以上版本被設置爲1.0,你還能夠設置API版本爲2.0,爲此你須要在不一樣命名空間中建立具備相同名稱的另外一個Controller類。 像下面這樣,ip

[源碼]  view plain
  1. namespace AspNetCoreWebApi.Controllers2  
  2. {  
  3.     [ApiVersion("2.0")]  
  4.     [Route("api/[controller]")]  
  5.     public class ValuesController : Controller  
  6.     {  
  7.         [HttpGet]  
  8.         public IActionResult Get() => Ok(new string[] { "value2" });  
  9.     }  
  10. }  

如今去瀏覽器並訪問控制器。 您應該看到API版本1.0控制器的輸出,由於默認訪問爲1.0的版本。 如今在URL中附加api-version = 2,你應該看到API 2.0版控制器的輸出。ci

api res

Via URL Path Segment(經過URL路徑)

查詢字符串參數是有用的,但在長URL和其餘查詢字符串參數的狀況下可能會很痛苦。 相反,更好的方法是在URL路徑中添加版本。 像這樣,

api/v1/values api/v2/values

因此要作到這一點,咱們須要把版本放在route屬性中:

[源碼]  view plain
  1. namespace MultipleAPIVersions.Controllers  
  2. {  
  3.     [ApiVersion("1.0")]  
  4.     [Route("api/v{version:apiVersion}/[controller]")]  
  5.     public class ValuesController : Controller  
  6.     {  
  7.         [HttpGet]  
  8.         public IActionResult Get() => Ok(new string[] { "value1" });  
  9.     }  
  10. }  

一樣,您須要將路由參數更新到全部請求中。 經過此更改,API端點始終須要具備版本號。 您能夠經過api/v1/values導航到版本1.0,要想訪問2.0版本,更改URL中的版本號。 簡單,看起來更乾淨

api path

Via HTTP Headers(經過HTTP頭傳遞)

在上述兩種方法中,須要修改URL以支持版本控制。 可是,若是您但願您的API URL保持乾淨,那麼API版本信息也能夠經過附加HTTP頭傳遞。 爲了使其工做,您須要配置ApiVersionReader選項

[源碼]  view plain
  1. services.AddApiVersioning(option =>  
  2. {  
  3.     option.ReportApiVersions = true;  
  4.     option.ApiVersionReader = new HeaderApiVersionReader("api-version");  
  5.     option.DefaultApiVersion = new ApiVersion(1, 0);  
  6.     option.AssumeDefaultVersionWhenUnspecified = true;  
  7. });  

打開Postman添加header api-version測試

test v1

當您將2.0做爲值提供給api-version時,它將調用2.0版Controller並返回輸出

test v2

簡單易用的設置。 可是,如今查詢字符串參數(query string parameter)將沒法正常工做。 設置header後,不能指定查詢字符串參數(query string parameter)。 若是你但願支持,請使用ApiVersionReader.Combine

[源碼]  view plain
  1. option.ApiVersionReader = ApiVersionReader.Combine  
  2.             (  
  3.                 new QueryStringApiVersionReader("api-version"),  
  4.                 new HeaderApiVersionReader("api-version")  
  5.             );  

如今,查詢字符串參數和header都支持
請記住,咱們還將ReportApiVersions設置爲true,返回響應頭中的版本信息。 見下圖

ReportApiVersions

如今,讓咱們來看看另外幾個選項

MapToApiVersion

MapToApiVersion 特性容許將單個API action 映射到任何版本。 換句話說,支持多個版本的單個Controller

[源碼]  view plain
  1. namespace MultipleAPIVersions.Controllers  
  2. {  
  3.     [ApiVersion("1.0")]  
  4.     [ApiVersion("3.0")]  
  5.     [Route("api/v{version:apiVersion}/[controller]")]  
  6.     public class ValuesController : Controller  
  7.     {  
  8.         [HttpGet]  
  9.         public IActionResult Get() => Ok(new string[] { "value1" });  
  10.   
  11.         [HttpGet, MapToApiVersion("3.0")]  
  12.         public IActionResult GetV3() => Ok(new string[] { "value3" });  
  13.     }  
  14. }  

MapToVer

Deprecated(棄用)

當支持多個API版本時,一些版本最終將被淘汰。 要想標明一個或多個API版將被棄用,只需將準備棄用的API版本標記。 這並不意味着不支持API版本,這些被標記的API仍然能夠調用。 這只是讓用戶意識到之後版本將被廢棄的一種方式
[ApiVersion("1.0", Deprecated = true)]

Deprecated

ApiVersionNeutral(版本中立)

ApiVersionNeutral特性定義該API是版本中立的。 這對於行爲方式徹底相同的API很是有用,不管是支持API版本的Controller仍是不支持API版本的Controller。 所以,你能夠添加ApiVersionNeutral特性以退出版本控制

[源碼]  view plain
  1. [ApiVersionNeutral]  
  2. [RoutePrefix( "api/[controller]" )]  
  3. public class SharedController : Controller  
  4. {  
  5.     [HttpGet]  
  6.     public IActionResult Get() => Ok();  
  7. }  

訪問版本信息

若是你想知道哪一個版本的客戶端正在嘗試訪問,那麼你能夠從中獲取該信息:

[源碼]  view plain
    1. public string Get() => HttpContext.GetRequestedApiVersion().ToString();  
相關文章
相關標籤/搜索