支持多个版本的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.0DefaultApiVersion :此选项用于指定在请求中未指定任何版本时要使用的默认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();
}

访问版本信息

若是你想知道哪一个版本的客户端正在尝试访问，那么你能够从中获取该信息：

public string Get() => HttpContext.GetRequestedApiVersion().ToString();