ASP.Net Core WebApi几种版本控制对比

 1、版本控制的好处：

（1）有助于及时推出功能, 而不会破坏现有系统。

（2）它还能够帮助为选定的客户提供额外的功能。

API 版本控制能够采用不一样的方式进行控制，方法以下：

（1）在 URL 中追加版本或做为查询字符串参数,

（2）经过自定义标头和经过接受标头

在这篇文章中, 让咱们来看看如何支持多个版本的 ASP.NET  Core  Web API。

1、建立asp.net core webapi 项目，引用NuGet包：Install-Package Microsoft.AspNetCore.Mvc.Versioning -Version 2.0.0

 

 

项目和安装包都好了，接着咱们须要在Startup.cs中的ConfigureServices 方法中添加下面的代码：

 

 

如您所见, 配置了3不一样的选项。

•  ReportAPIVersions: 这是可选的。可是, 当设置为 true 时, API 将返回响应标头中支持的版本信息。
•  AssumeDefaultVersionWhenUnspecified: 此选项将用于不提供版本的请求。默认状况下, 假定的 API 版本为1.0。
• DefaultApiVersion: 此选项用于指定在请求中未指定版本时要使用的默认 API 版本。这将默认版本为1.0。

这是全部的配置和设置。如今, 咱们将看到访问 API 版本的不一样方式。

 

2、经过QueryString来实现版本控制

打开咱们的控制器，在上面添加ApiVersion特性，以下代码所示：

上面的代码做为1.0版本。您还能够在不一样的命名空间中建立另外一个具备相同名称的控制器类, 并将 API 版本设置为2.0版本。以下图所示：

 

就这样。如今转到浏览器并访问控制器。您应该看到 API 版本1.0 控制器的输出, 由于它被设置为默认值。如今在 URL 中追加 api-version=2, 您应该看到 api 版本2.0 控制器的输出。

2、经过URL Path Segment来实现：

查询字符串参数颇有用, 但在长 URL 和其余查询字符串参数的状况下可能会很痛苦。相反, 更好的方法是在 URL 路径中添加版本。好比：

• api/v1/values
• api/v2/values

仍是上面的项目，只不过须要在v1和v2控制器中加入，下面的代码。以下图所示：

一样, 您须要将路由参数更新到全部适用的位置。使用此更改, 在访问API 接口时老是须要有版本号。您能够经过 api/v1/values 访问到版本 1.0, 经过api/v2/values 访问版本 2.0, 更改 URL 中的版本号。简单, 看起来更干净了。

测试结果以下：

3、经过HTTP Headers来实现版本控制

在上述两种方法中, 须要修改 URL 以支持版本控制。可是, 若是您但愿 api 的URL 保持干净, 则 api 版本信息也能够经过附加 HTTP 报头来传递。要进行此工做, 您须要配置 ApiVersionReader 选项。代码以下：

 

 

 

突出显示的行告诉咱们header  "api-version" 如今是 api 版本号的预期位置。确保路由属性没有版本详细信息。因此测试它，结果以下：

当您将2.0 做为值提供给 "api 版本" 时, 它将调用版本2.0 控制器并返回输出。

简单, 易于设置。可是, 如今查询字符串参数的方法进行版本控制将不起做用。一旦设置了header, 就不能指定查询字符串参数。若是您但愿支持这两种状况, 而不是 HeaderApiVersionReader, 请使用 QueryStringOrHeaderApiVersionReader。代码以下：

 

所以, 如今支持查询字符串参数和header。默认查询字符串参数名称是 api-version, 所以您能够将构造函数留空, 但若是须要其余名称, 则须要提供。您还能够对查询字符串参数和标头使用有不一样的名称。请记住, 咱们还将 ReportApiVersions 设置为 true, 该值返回响应标头中的版本信息。见下图。

 

如今, 让咱们来看看另外几个选项。

MapToApiVersion参数的用法：

MapToApiVersion 属性容许将单个 API 操做映射到任何版本。换言之, 一个支持多个版本的单控制器。控制器可能只有版本3支持的 API 操做方法。在这种状况下, 您可使用 MapToApiVersion。看看下面的代码。

上面代码的意思是：public string Get()该方法只有在版本1.0中支持，public string Getv3()方法只有在版本3.0中支持。

有图有真像，很灵活，我很喜欢。

Deprecated参数的用法：

当支持多个 API 版本时, 某些版本最终会随着时间的推移而被弃用。要标记一个或多个 api 版本已被废弃, 只需用Deprecated修饰您的控制器。这并不意味着不支持 API 版本。你仍然能够调用该版本。它只是一种让 调用API 用户意识到如下版本在未来会被弃用。

上面把Deprecated设置为TRUE表示，版本1.0未来会被弃用。访问咱们的API接口，能够在响应头中能够看到，下面信息，以下图所示：

ApiVersionNeutral特性的使用：

ApiVersionNeutral 特性定义此 API 不在支持版本控制。不管 支持api 版本控制或不支持 api 版本控制的旧式 api，这对于行为彻底相同的 api 很是有用。所以, 您能够添加 ApiVersionNeutral 属性以从版本控制中退出。

获取版本信息（Version Information）

若是你想知道那个版本的客户端在被访问，你能够经过下面的代码实现该功能：

综上所述, 具备多个版本的 API 能够帮助以一种有效的方式推出加强的功能, 同时也便于跟踪更改。在这篇文章中, 咱们看到了如何在 ASP.NET  core WEB API 中添加对多个版本的支持。nuget 包支持经过查询字符串参数进行版本控制, 在 URL 中添加路径段和经过标头。它还具备版本单一 API 操做和从版本中选择退出的功能。

能不能不借助第三方的包来实现一个API的版本控制，方法是有的，不卖关子了，你们接着往下看。

 

4、终极版本（不借助任何NuGet包）asp.net core web api版本控制

新建一个core API项目：

 

在VersionControl文件夹下面，新建一个实现了IApplicationModelConvention接口的类NameSpaceVersionRoutingConvention   代码以下：

 

 1  public class NameSpaceVersionRoutingConvention:IApplicationModelConvention
 2     {
 3         private readonly string apiPrefix;
 4         private const string urlTemplate = "{0}/{1}/{2}";
 5         public NameSpaceVersionRoutingConvention(string apiPrefix = "api")
 6         {
 7             this.apiPrefix = apiPrefix;
 8         }
 9 
10         public void Apply(ApplicationModel application)
11         {
12             foreach (var controller in application.Controllers)
13             {
14                 
15                 var hasRouteAttribute = controller.Selectors
16                 .Any(x => x.AttributeRouteModel != null);
17                 if (!hasRouteAttribute)
18                 {
19                     continue;
20                 }
21                 var nameSpaces = controller.ControllerType.Namespace.Split('.');
22                 //获取namespace中版本号部分
23                 var version = nameSpaces.FirstOrDefault(x => Regex.IsMatch(x, @"^v(\d+)$"));
24                 if (string.IsNullOrEmpty(version))
25                 {
26                     continue;
27                 }
28                 string template = string.Format(urlTemplate, apiPrefix, version,
29                 controller.ControllerName);
30                 controller.Selectors[0].AttributeRouteModel = new AttributeRouteModel()
31                 {
32                     Template = template
33                 };
34             }
35         }
36     }

 

调试代码发现这种方式只在程序第一次运行的时候会执行，以后不会再执行屡次，所以效率很高。

5、总结：

经过上面两种版本控制的实现和对比，我更偏向经过第三方的包来实现版本控制，这种方法功能更强大。这纯属于我的爱好了，你们能够根据不一样的场景来决定使用哪一种方式来实现，好了讲到这里，谢谢，但愿对你有帮助。

以为能够的话，但愿点下推荐哈~大家的推荐是个人动力。

 

多谢@光阴四溅 及时指出个人错误，很感谢！

代码下载地址：WebApiVersionControl.rar

做者：郭峥

出处：http://www.cnblogs.com/runningsmallguo/

本文版权归做者和博客园共有，欢迎转载，但未经做者赞成必须保留此段声明，且在文章页面明显位置给出原文连接。