ASP.NET Core 3.x API版本控制

前言

通常来讲须要更改咱们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;
});

• options.DefaultApiVersion = new ApiVersion(1,0): 这个设置不是必须的，由于默认状况下给咱们设置的是1.0，可是显式的声明出来是一个很好的习惯，固然DefaultApiVersion它会将默认的[ApiVersion("1.0")]添加到控制器上，也就是说它会隐式的绑定API版本，可是为了咱们方便理解或者说方便咱们后面开发建议显式的设置。
• options.AssumeDefaultVersionWhenUnspecified = true:默认API版本控制须要将其属性设置为true才能够开启
• options.ReportApiVersions = true:默认状况下它是禁用的，启用此选项后，来自咱们API端点的响应将带有标头，告诉咱们的客户端支持或不推荐使用哪一个版本(api-supported-versions:1.1,2.0, api-deprecated-versions:1.0)

默认提供了四种版本控制方法：

• 字符串参数
• 经过HTTP请求头
• URL方式
• 媒体类型（Media Type）

默认方法是使用名为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端点进行版本控制，咱们能够将这些属性应用于控制器和方法。

• 控制器的默承认能没有任何API版本属性，并隐式配置的默认API版本。默认配置使用值1.0。
• 使用[ApiVersion("1.0")]属性注释咱们的控制器，意味着该控制器支持API版本1.0
• 控制器能够支持多个API版本。只需[ApiVersion(...)]在控制器上应用多个属性
• 为了区分控制器支持的多个版本，咱们使用[MapToApiVersion()]属性注释控制器方法。

若是要使用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