Microsoft.AspNetCore.Mvc.Versioning学习笔记

摘要：对API实行版本控制可以再不破坏现有功能的基础上，及时推出新功能，以便更好地支持多个客户端版本。

例如：原先的APP版本为1.0，调用的API版本也是1.0；现在由于某个原因需要对某个功能进行调整，同时发布APP的2.0版本，如果直接在原先的1.0API上进行修改，那么使用APP2.0新版本的用户不会有问题，但那些没有及时更新APP版本的用户就有可能会出现问题（这种情况并不能避免）。
这时候对API进行版本控制就显得格外重要。

Microsoft.AspNetCore.Mvc.Versioning的使用

service.AddApiVersioning(option =>
            {
                option.ReportApiVersions = true;
                option.DefaultApiVersion = new ApiVersion(2, 0);
                option.AssumeDefaultVersionWhenUnspecified = true;
                // Url Path的形式无需特别配置

                // 使用Http Header时的配置
                // option.ApiVersionReader=new HeaderApiVersionReader("api-version");

                // 使用Query String时的配置
                // option.ApiVersionReader=new QueryStringApiVersionReader("api-version");

                // Http Header和Query String能一起使用时的配置
                option.ApiVersionReader = ApiVersionReader.Combine
                (
                    new HeaderApiVersionReader("api-version"),
                    new QueryStringApiVersionReader("api-version")
                );
            });

备注：在不配置 ApiVersionReader 的情况下，Query String（使用 api-version=1 形式）和Url Path（使用 v1,v2 这种形式）这两种形式都能起作用。
但是，如果想要使用Http Header这种形式，就必须配置 ApiVersionReader ，此时配置了 HeaderApiVersionReader 之后，Query String这种形式无法使用。
如果想要Http Header和Query String共存，则需要配置 ApiVersionReader.Combine

ReportApiVersions：这个配置是可选的，当我们设置为 true 时，API 会在响应的 header 中返回版本信息。
DefaultApiVersion：当请求中未指明版本时，使用此处指定的默认版本，此处设定为1.0。
AssumeDefaultVersionWhenUnspecified：这个配置项将用于在没有指明 API 版本的情况下提供请求，默认情况下，会请求默认版本的 API，例如，这里就会请求 1.0 版本的 API。

访问API版本的几种方式

Query String：例如api/user?api-version=1.0这种形式
Url Path：例如api/v1/user,api/v2/user这种形式，使用更为简洁（推荐）
HTTP Request Header：直接在请求HEADER中指定版本，好处是请求的路径不会有任何改变

其它特性

    [ApiVersion("1.0",Deprecated = true)]
    [ApiVersion("2.0")]
    // 多路由
    [Route("api/v{version:apiVersion}/[controller]")]
    [Route("api/[controller]")]
    [ApiController]
    public class UserController:ControllerBase
    {
        [MapToApiVersion("1.0")]
        [HttpGet]
        public async Task<ActionResult> Get1()
        {
            var values = new {Version = "1.0", Method = "Get"};
            return Ok(values);
        }

        [MapToApiVersion("2.0")]
        [HttpGet]
        public async Task<ActionResult> Get2()
        {
            var values = new { Version = "2.0", Method = "Get" };
            return Ok(values);
        }
    }

MapToApiVersion：MapToApiVersion 特性允许将单个 action 映射到任何版本。在上面的代码中Get1对应v1，Get2对应v2
Deprecated(弃用)：只是增加一个标识，并不代表该版本的API无法使用（此时访问v1版本仍然会有返回值）
多路由特性：采用这种形式可以保证api/user（访问的是指定的默认版本）和api/v1/user两种形式都可以正常访问