簡介
Api的版本控制是Api開發中經常遇到的問題, 在大部分中大型項目都需要使用到Api的版本控制
在本篇博客中,我們將說明一下如何在.Net Core Api項目中使用Api版本控制。
本篇博客中測試項目的開發環境:
- Visual Studio 2019
- .Net Core 2.2 SDK
使用Nuget安裝Api版本控制庫
修改Startup類
public void ConfigureServices(IServiceCollection services) { services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2); services.AddApiVersioning(o => { o.ReportApiVersions = true; o.AssumeDefaultVersionWhenUnspecified = true; o.DefaultApiVersion = new ApiVersion(2, 0); //設置默認版本 }); }
ReportApiVersion
屬性是一個布爾類型,如果設置爲true, 在Api請求的響應頭部,會追加當前Api支持的版本
創建多版本Api
[ApiVersion("1.0")] [Route("api/values")] [ApiController] public class ValuesV1Controller : ControllerBase { [HttpGet] public IEnumerable<string> Get() { return new string[] { "Value1 from Version 1", "value2 from Version 1" }; } } [ApiVersion("2.0")] [Route("api/values")] [ApiController] public class ValuesV2Controller : ControllerBase { [HttpGet] public IEnumerable<string> Get() { return new string[] { "value1 from Version 2", "value2 from Version 2" }; } }
如何在查詢字符串(Query String)中使用版本控制
如何使用路由約束中指定請求Api的版本
[ApiVersion("1.0")] [Route("api/{v:apiVersion}/values")] [ApiController] public class ValuesV1Controller : ControllerBase { [HttpGet] public IEnumerable<string> Get() { return new string[] { "Value1 from Version 1", "value2 from Version 1" }; } } [ApiVersion("2.0")] [Route("api/{v:apiVersion}/values")] [ApiController] public class ValuesV2Controller : ControllerBase { [HttpGet] public IEnumerable<string> Get() { return new string[] { "value1 from Version 2", "value2 from Version 2" }; } }
如何在請求頭(HTTP Header)中使用版本控制
public void ConfigureServices(IServiceCollection services) { services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2); services.AddApiVersioning(o => { o.ReportApiVersions = true; o.AssumeDefaultVersionWhenUnspecified = true; o.DefaultApiVersion = new ApiVersion(2, 0); //設置默認版本 o.ApiVersionReader = new HeaderApiVersionReader("x-api-version");//如何在請求頭(HTTP Header)中使用傳入版本參數 }); }
一旦你使用o.ApiVersionReader = new HeaderApiVersionReader("x-api-version");,
在查詢字符串中指定版本號的方式將不再可用,如果你希望同時支持2種方式,
請改用o.ApiVersionReader = ApiVersionReader.Combine(new QueryStringApiVersionReader(), new HeaderApiVersionReader() { HeaderNames = { "x-api-version" }});
棄用Api(Deprecated)特性
有些時候,我們需要標記一些過時的Api爲棄用狀態,但是我們又不希望完全移除這個版本的Api, 我們可以使用Deprecated
特性。
例:我們當前希望棄用ValuesV1Controller
, 我們可以指定Deprecated特性的值爲true
header返回1.0版本的Api已經過期了,2.0版本中有相同的Api, 可以換用2.0版本的Api提示。
使用ApiVersionNeutral
指定不需要版本控制的Api
[ApiVersionNeutral] [Route("api/[controller]")] [ApiController] public class HealthCheckController : ControllerBase { public string Get() { return "Good"; } }