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

 一、版本控制的好处：

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

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

API 版本控制可以采用不同的方式进行控制，方法如下：

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

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

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

一、创建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 版本的不同方式。

 

二、通过QueryString来实现版本控制

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

上面的代码作为1.0版本。您还可以在不同的命名空间中创建另一个具有相同名称的控制器类,并将 API版本设置为2.0版本。如下图所示：

 

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

二、通过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 中的版本号。简单, 看起来更干净了。

测试结果如下：

三、通过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的版本控制，方法是有的，不卖关子了，大家接着往下看。

 

四、终极版本（不借助任何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.Selectors16                 .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 = template33                 };34             }35         }36     }

 

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

五、总结：

通过上面两种版本控制的实现和对比，我更偏向通过第三方的包来实现版本控制，这种方法功能更强大。这纯属于个人爱好了，大家可以根据不同的场景来决定使用哪种方式来实现，好了讲到这里，谢谢，希望对你有帮助。

觉得可以的话，希望点下推荐哈~你们的推荐是我的动力。

 

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

代码下载地址：WebApiVersionControl.rar

作者：郭峥

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

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