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两种形式都可以正常访问