shyleoking 2020-06-14
前言
一般来说需要更改我们API的时候才考虑版本控制,但是我觉得我们不应该等到那时候来实现它,我们应该有一个版本策略从我们应用程序开发时就开始制定好我们的策略,我们一直遵循着这个策略进行开发。
我们其实可以通过多种方式进行实现我们API版本的控制,其实对于版本控制没有最好的方式,这完全取决于我们面向的使用者。
API版本控制类型
安装版本控制包
Install-Package Microsoft.AspNetCore.Mvc.Versioning
在Startup.cs中的ConfigureServices方法中进行版本设置,以及在控制器通过特性进行设置版本,这样可以实现版本控制。
services.AddApiVersioning(options => { options.DefaultApiVersion = new ApiVersion(1, 0); options.AssumeDefaultVersionWhenUnspecified = true; options.ReportApiVersions = true; });
默认提供了四种版本控制方法:
默认方法是使用名为api-version 的查询字符串参数。我们还可以自己定义一个版本控制规则。
API版本约束方式
字符串参数形式
services.AddApiVersioning(options => options.ApiVersionReader = new QueryStringApiVersionReader("v"));
HTTP请求头
services.AddApiVersioning(options => options.ApiVersionReader = new HeaderApiVersionReader("api-version"));
组合方式
services.AddApiVersioning(options => { options.ApiVersionReader = ApiVersionReader.Combine( new QueryStringApiVersionReader("v"), new HeaderApiVersionReader("v"));});
URL方式
services.AddApiVersioning(options => options.ApiVersionReader = new UrlSegmentApiVersionReader());
我们可以更改代表版本的参数名称(例如,在上面的查询字符串方法中,我们使用字母v代替默认的api-version)。
控制器和方法中添加版本信息
选择版本控制策略并在ConfigureServices方法中对其配置后,我们可以开始对API端点进行版本控制,我们可以将这些属性应用于控制器和方法。
如果要使用URL路径则可以参考如下代码片段:
[Route("api/v{version:apiVersion}/[controller]")]
API控制器弃用,我们只需要设置
[ApiVersion("1.0", Deprecated = true)]
可通过如下方法方式获取所有API版本信息
var apiVersion = HttpContext.GetRequestedApiVersion();
当然他还支持模型绑定,我们还可以通过模型形式获取
[HttpGet] public string Get(ApiVersion apiVersion) => $"Controller = {GetType().Name}\nVersion = {apiVersion}"; }
API版本约束
我们除了在方法和控制器上指定我们的版本,我们还可以采用另一种方式
services.AddApiVersioning( options => { options.Conventions.Controller<HomeController>().HasApiVersion(1, 0); });
看如上代码我们可以看到我们在这里给HomeController配置版本,这样方便我们集中管理我们的版本。
services.AddApiVersioning( options => { options.Conventions.Controller<MyController>() .HasDeprecatedApiVersion(1, 0) .HasApiVersion(1, 1) .HasApiVersion(2, 0) .Action(c => c.Get1_0()).MapToApiVersion(1, 0) .Action(c => c.Get1_1()).MapToApiVersion(1, 1) .Action(c => c.Get2_0()).MapToApiVersion(2, 0); });
可以同时使用API版本约束和版本控制属性。
当然我们还可以自定义约束,从.NET Core 3.0开始,有一个IControllerConvention用于此目的的接口。
options.Conventions.Add(new MyCustomConvention());
当然我们还可以通过不同命名空间中的接口进行约束
options.Conventions.Add(new VersionByNamespaceConvention());
比如下面这种文件形式
api/v1/UsersController
api/v2/UsersController
api/v2_1/UsersController
映射后的路径如下所示
api/1.0/users
api/2.0/users
api/2.1/users