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