支持多个版本的ASP.NET Core Web API

提示：扫一扫查出行
【扫一扫了解最新限行尾号】
复制提示

基本配置及说明

版本控制有助于及时推出功能，而不会破坏现有系统。它还可以帮助为选定的客户提供额外的功能。 API版本可以通过不同的方式完成，例如在URL中添加版本或通过自定义标头和通过Accept-Header作为查询字符串参数。在这篇文章中，我们来看看如何支持多版本的ASP.NET Core Web API

创建一个ASP.NET Core Web API应用程序。通过 NuGet 安装此软件包：Microsoft.AspNetCore.Mvc.Versioning，打开Startup.cs,修改ConfigureServices方法，代码如下：

public void ConfigureServices(IServiceCollection services) { services.AddMvc(); services.AddApiVersioning(option => { option.ReportApiVersions = true; option.AssumeDefaultVersionWhenUnspecified = true; option.DefaultApiVersion = new ApiVersion(1, 0); }); }

你可以看到配置了3个不同的选项:

ReportAPIVersions :这是可选的。但是当设置为true时，API会在响应头中返回受支持的版本信息。
AssumeDefaultVersionWhenUnspecified :此选项将用于在没有版本的情况下提供请求。假定的API版本默认为1.0
DefaultApiVersion :此选项用于指定在请求中未指定任何版本时要使用的默认API版本。这将默认版本为1.0

这就是配置和设置。现在我们将看到访问API版本的不同方法。

Via Query String(通过查询字符串)

打开Controller 类，然后用ApiVersion属性装饰控Controller类。像下面这样，

namespace MultipleAPIVersions.Controllers { [ApiVersion("1.0")] [Route("api/[controller]")] public class ValuesController : Controller { [HttpGet] public IActionResult Get() => Ok(new string[] { "value1" }); } }

以上版本被设置为1.0，你还可以设置API版本为2.0，为此你需要在不同命名空间中创建具有相同名称的另一个Controller类。像下面这样，

namespace AspNetCoreWebApi.Controllers2 { [ApiVersion("2.0")] [Route("api/[controller]")] public class ValuesController : Controller { [HttpGet] public IActionResult Get() => Ok(new string[] { "value2" }); } }

现在去浏览器并访问控制器。您应该看到API版本1.0控制器的输出，因为默认访问为1.0的版本。现在在URL中附加api-version = 2，你应该看到API 2.0版控制器的输出。

Via URL Path Segment(通过URL路径)

查询字符串参数是有用的，但在长URL和其他查询字符串参数的情况下可能会很痛苦。相反，更好的方法是在URL路径中添加版本。像这样,

api/v1/values
api/v2/values

所以要做到这一点，我们需要把版本放在route属性中:

namespace MultipleAPIVersions.Controllers { [ApiVersion("1.0")] [Route("api/v{version:apiVersion}/[controller]")] public class ValuesController : Controller { [HttpGet] public IActionResult Get() => Ok(new string[] { "value1" }); } }

同样，您需要将路由参数更新到所有请求中。通过此更改，API端点始终需要具有版本号。您可以通过api/v1/values导航到版本1.0，要想访问2.0版本，更改URL中的版本号。简单，看起来更干净

Via HTTP Headers(通过HTTP头传递)

在上述两种方法中，需要修改URL以支持版本控制。但是，如果您希望您的API URL保持干净，那么API版本信息也可以通过附加HTTP头传递。为了使其工作，您需要配置ApiVersionReader选项

services.AddApiVersioning(option => { option.ReportApiVersions = true; option.ApiVersionReader = new HeaderApiVersionReader("api-version"); option.DefaultApiVersion = new ApiVersion(1, 0); option.AssumeDefaultVersionWhenUnspecified = true; });

打开Postman添加header api-version测试

当您将2.0作为值提供给api-version时，它将调用2.0版Controller并返回输出

简单易用的设置。但是，现在查询字符串参数(query string parameter)将无法正常工作。设置header后，不能指定查询字符串参数(query string parameter)。如果你希望支持,请使用 ApiVersionReader.Combine

option.ApiVersionReader = ApiVersionReader.Combine ( new QueryStringApiVersionReader("api-version"), new HeaderApiVersionReader("api-version") );

现在，查询字符串参数和header都支持

请记住，我们还将ReportApiVersions设置为true，返回响应头中的版本信息。见下图

现在，让我们来看看另外几个选项

MapToApiVersion

MapToApiVersion 特性允许将单个API action 映射到任何版本。换句话说，支持多个版本的单个Controller

namespace MultipleAPIVersions.Controllers { [ApiVersion("1.0")] [ApiVersion("3.0")] [Route("api/v{version:apiVersion}/[controller]")] public class ValuesController : Controller { [HttpGet] public IActionResult Get() => Ok(new string[] { "value1" }); [HttpGet, MapToApiVersion("3.0")] public IActionResult GetV3() => Ok(new string[] { "value3" }); } }

Deprecated(弃用)

当支持多个API版本时，一些版本最终将被淘汰。要想标明一个或多个API版将被弃用，只需将准备弃用的API版本标记。这并不意味着不支持API版本，这些被标记的API仍然可以调用。这只是让用户意识到以后版本将被废弃的一种方式

[ApiVersion("1.0", Deprecated = true)]

ApiVersionNeutral(版本中立)

ApiVersionNeutral特性定义该API是版本中立的。这对于行为方式完全相同的API非常有用，不论是支持API版本的Controller还是不支持API版本的Controller。因此，你可以添加ApiVersionNeutral特性以退出版本控制

[ApiVersionNeutral] [RoutePrefix( "api/[controller]" )] public class SharedController : Controller { [HttpGet] public IActionResult Get() => Ok(); }