.NET Core中的API版本控制
英文｜neelbhatt.com
来源｜Neel Bhatt
译文｜cnblogs.com/lwqlun/archive
API的版本控制是API开发中经常遇到的问题, 在大部分中大型项目都需要使用到API的版本控制
在本篇博客中，我们将说明一下如何在.NET Core API项目中使用API版本控制。
本篇博客中测试项目的开发环境：
-
Visual Studio 2017
.NET Core 2.1 SDK
创建一个API项目
首先我们创建一个.NET Core API项目
使用Nuget安装API版本控制库
.NET Core MVC中，微软官方提供了一个可用的API版本控制库Microsoft.AspNetCore.Mvc.Versioning。
这里我们可以使用Nuget安装这个包。
PM> Install-Package Microsoft.AspNetCore.Mvc.Versioning修改Startup类
Microsoft.AspNetCore.Mvc.Versioning库安装完成之后，下一步我们来添加API版本控制服务。
这里我们需要在Startup类的ConfigureService方法中添加以下代码。
services.AddAPIVersioning(o => {
o.ReportAPIVersions = true;
o.AssumeDefaultVersionWhenUnspecified = true;
o.DefaultAPIVersion = new APIVersion(1, 0);
});代码解释
ReportAPIVersion 属性是一个布尔类型，如果设置为true, 在API请求的响应头部，会追加当前API支持的版本, 例
AssumeDefaultVersionWhenUnspecified属性是为了标记当客户端没有指定版本号的时候，是否使用默认版本号
DefaultAPIVersion属性即默认版本号
创建多版本API
这里为了测试.Net Core Mvc的API版本控制库，我们创建如下2个Controller。
代码解释
-
Value1Controller和Value2Controller使用了一样的路由"/API/values"
-
Value1Controller类头部使用APIVersion特性标记了当前Controller的API版本号是1.0
-
Value2Controller类头部使用APIVersion特性标记了当前Controller的API版本号是2.0
-Value1Controller和Value2Controller都持有相同方法签名的Get方法, 只是2个Get中返回了不同的字符串
现在我们启动项目，得到的结果如下，说明当没有指定API版本号时，项目自动使用1.0版本的API, 即ValuesV1Controller中的Get方法。
如何在查询字符串(Query String)中使用版本控制
Microsoft.AspNetCore.Mvc.Versioning支持以QueryString的形式指定请求API的版本号。开发人员可以在Url中指定API-version参数来选择调用的API版本号。
现在我们通过以下2个Url请求API, 返回的结果如下 :
/API/2.0/values
["value1 from Version 2","value2 from Version 2"]/API/1.0/values
["Value1 from Version 1","value2 from Version 1"]如何在请求头(HTTP Header)中使用版本控制
以上的2种方式需要修改请求的Url, 如果你不喜欢这2种方式，Microsoft.AspNetCore.Mvc.Versioning还提供了第三种指定API版本号的方式，即在HTTP请求头中添加版本号参数。
为了启用这种方式，我们首先需要在Startup.cs中修改Microsoft.AspNetCore.Mvc.Versioning的配置, 代码如下:
services.AddAPIVersioning(o =>
{
o.ReportAPIVersions = true;
o.AssumeDefaultVersionWhenUnspecified = true;
o.DefaultAPIVersion = new APIVersion(1, 0);
o.APIVersionReader = new HeaderAPIVersionReader("x-API-version");
});这里通过APIVersionReader属性指定了API版本号是从请求头部的x-API-version属性来的。
Tips: 一旦你使用o.APIVersionReader = new HeaderAPIVersionReader("x-API-version");, 在查询字符串中指定版本号的方式将不再可用，如果你希望同时支持2种方式，请改用o.APIVersionReader = APIVersionReader.Combine(new QueryStringAPIVersionReader(), new HeaderAPIVersionReader() { HeaderNames = { "x-API-version" }});(多谢seamaswang的更正)
下面我们通过Postman来请求2.0的API, 结果正确返回了。
弃用API(Deprecated)特性
有些时候，我们需要标记一些过时的API为弃用状态，但是我们又不希望完全移除这个版本的API, 我们可以使用Deprecated特性。
例：我们当前希望弃用ValuesV1Controller, 我们可以指定Deprecated特性的值为true
[APIVersion("1.0", Deprecated = true)]
[Route("API/values")]
[APIController]
public class ValuesV1Controller : ControllerBase
{
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "Value1 from Version 1", "value2 from Version 1" };
}
}当我们请求在此请求这个API的时候, 在响应头中会出现API-deprecated-versions和API-supported-versions2个属性。
这段响应的意思就是1.0版本的API已经过期了，2.0版本中有相同的API, 可以换用2.0版本的API。
使用APIVersionNeutral指定不需要版本控制的API
在编写API的时候，对于一些非常简单的API， 我们可能不需要指定API版本号, 例如健康检查API。
我们可以使用APIVersionNeutral特性，将它从API版本控制中排除掉。
例：
[APIVersionNeutral]
[Route("API/[controller]")]
[APIController]
public class HealthCheckController : ControllerBase
{
public string Get()
{
return "Good";
}
}
源代码：
https://files.cnblogs.com/files/lwqlun/ApiVersioningSample.zip