诺禾-ASP.NET Core 3.x API版本控制

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().HasApiVersion(1, 0);
});
看如上代码我们能够看到我们在这里给HomeController配置版本，这样便当我们集中管理我们的版本。

services.AddApiVersioning( options =>
{
options.Conventions.Controller()
.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