ASP.NET CORE Web API版本管理工具

概要

本文介绍一个ASP.NET CORE Web API版本管理工具，以方便我们在开发过程中，针对不同的开发版本，进行管理。

代码和实现

本文主要介绍如何通过对Microsoft.AspNetCore.Mvc.Versioning进行简单的配置，实现Web API的版本管理。

开发环境搭建

mkdir [project_directory]
cd [project_directory]
dotnew new mvc 
dotnet add package Microsoft.AspNetCore.Mvc.Versioning

1. 本文所使用的ASP.NET CORE 版本是3.1
2. Microsoft.AspNetCore.Mvc.Versioning API版本管理工具版本是5.0.0

开发环境配置

Microsoft.AspNetCore.Mvc.Versioning和其他ASP.NET CORE插件一样，都是采用依赖注入的方式进行配置，在Startup.cs中的基本配置如下:

public void ConfigureServices(IServiceCollection services)
        {
            services.AddApiVersioning(options => {
                options.AssumeDefaultVersionWhenUnspecified = true;
                options.ReportApiVersions = true;
                options.DefaultApiVersion = new ApiVersion(1,0);
                options.ApiVersionReader = ApiVersionReader.Combine(
                    new HeaderApiVersionReader("x-api-version"),
                    new MediaTypeApiVersionReader("x-api-version"),
                    new QueryStringApiVersionReader("version")
                );
            });
                
        }

1. ReportApiVersions开启后，我们可以在Web API返回的Response的header中找到api-supported-versions，api-deprecated-versions等版本管理信息。
2. DefaultApiVersion 可以配置默认的版本信息。
3. ApiVersionReader定义了Web API的管理方式，本文将常用的三种方式列出：
   A. HeaderApiVersionReader 表示可以在Request的请求heaer中，通过x-api-version属性，选择要访问的Web API版本
   B. MediaTypeApiVersionReader 表示可以在Request的请求heaer中，通过将Accept设置为application/json;x-api-version=1.0，选择要访问的Web API版本
   C QueryStringApiVersionReader 表示可以通过Web API 的URL查询字符串来选择要访问的Web API版本
   D. 默认也可以通URI中的路径来选择要访问的Web API版本，例如/api/v1/todo

代码实现

本文通过一个VersionController, 来介绍版本管理插件的基本功能

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;

namespace branches.Management
{
     [ApiController]
     [Route("api")]
    public class VersionsController : ControllerBase
    {
        private readonly ILogger<VersionsController> _logger;

        public VersionsController(ILogger<VersionsController> logger)
        {
            _logger = logger;
        }

        [HttpGet("version")]
        [HttpGet("version/{v:apiVersion}")]
        [ApiVersion("1.0")]
        public  IActionResult getv1(){
            return Ok("This is V1");
        }

        [HttpGet("version")]
        [ApiVersion("2.0")]
        [HttpGet("version/{v:apiVersion}")]
        public  IActionResult getv2(){
            return Ok("This is V2");
        }


    }
}

1. 定义了两个Action，getv1和getv2，返回不同的版本信息字符串
2. 两个Action的URI相同，都是/api/version
3. 为两个Action通过Annotation设置版本信息 [ApiVersion([YourVersion])]
4. [HttpGet(“version/{v:apiVersion}”)]为两个Web API设置基于版本的URI访问路径

实验验证

本文使用Thunder Client 来作为客户端访问Web API, Thunder Client和Postman使用方法类似，不再赘述。

通过URL参数选择Web API

https://localhost:5001/api/version?version=1.0

https://localhost:5001/api/version?version=2.0

根据不同的版本参数，调用了不用的Web API，返回结果中，可以看到所有的版本信息。

通过URI参数选择Web API

https://localhost:5001/api/version/1.0

https://localhost:5001/api/version/2.0

通过header选择Web API

https://localhost:5001/api/version，调用1.0的Web API
https://localhost:5001/api/version，调用2.0的Web API

通过header/Accept选择Web API

https://localhost:5001/api/version，调用1.0的Web API

https://localhost:5001/api/version，调用2.0的Web API

Deprecated 1.0 Web API

Deprecated 同样通过Annotation实现，代码如下：

 [HttpGet("version")]
        [HttpGet("version/{v:apiVersion}")]
        [ApiVersion("1.0", Deprecated = true)]
        public  IActionResult getv1(){
            return Ok("This is V1");
        }

此时我们通过上面任何一种方式，依然可以访问1.0的Web API，但是在返回header中，会有相应的版本Deprecated 说明。

标记为Deprecated的Web API依然可以访问。因为Deprecated本身的意思就是不再推荐使用，未来将不再支持，可能在未来的版本中彻底移除。