.Net Core中的Api版本控制

简介

Api的版本控制是Api开发中经常遇到的问题, 在大部分中大型项目都需要使用到Api的版本控制

在本篇博客中，我们将说明一下如何在.Net Core Api项目中使用Api版本控制。

本篇博客中测试项目的开发环境：

• Visual Studio 2019
• .Net Core 2.2 SDK

使用Nuget安装Api版本控制库

修改Startup类

       public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            services.AddApiVersioning(o => {
                o.ReportApiVersions = true;
                o.AssumeDefaultVersionWhenUnspecified = true;
                o.DefaultApiVersion = new ApiVersion(2, 0); //设置默认版本
            });
        }

ReportApiVersion属性是一个布尔类型，如果设置为true, 在Api请求的响应头部，会追加当前Api支持的版本

创建多版本Api

    [ApiVersion("1.0")]
    [Route("api/values")]
    [ApiController]
    public class ValuesV1Controller : ControllerBase
    {
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] { "Value1 from Version 1", "value2 from Version 1" };
        }
    }

    [ApiVersion("2.0")]
    [Route("api/values")]
    [ApiController]
    public class ValuesV2Controller : ControllerBase
    {
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] { "value1 from Version 2", "value2 from Version 2" };
        }
    }

如何在查询字符串(Query String)中使用版本控制

如何使用路由约束中指定请求Api的版本

    [ApiVersion("1.0")]
    [Route("api/{v:apiVersion}/values")]
    [ApiController]
    public class ValuesV1Controller : ControllerBase
    {
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] { "Value1 from Version 1", "value2 from Version 1" };
        }
    }

    [ApiVersion("2.0")]
    [Route("api/{v:apiVersion}/values")]
    [ApiController]
    public class ValuesV2Controller : ControllerBase
    {
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] { "value1 from Version 2", "value2 from Version 2" };
        }
    }

 

如何在请求头(HTTP Header)中使用版本控制

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            services.AddApiVersioning(o => {
                o.ReportApiVersions = true;
                o.AssumeDefaultVersionWhenUnspecified = true;
                o.DefaultApiVersion = new ApiVersion(2, 0); //设置默认版本
                o.ApiVersionReader = new HeaderApiVersionReader("x-api-version");//如何在请求头(HTTP Header)中使用传入版本参数
            });
        }

一旦你使用o.ApiVersionReader = new HeaderApiVersionReader("x-api-version");,
在查询字符串中指定版本号的方式将不再可用，如果你希望同时支持2种方式，
请改用o.ApiVersionReader = ApiVersionReader.Combine(new QueryStringApiVersionReader(), new HeaderApiVersionReader() { HeaderNames = { "x-api-version" }});

弃用Api(Deprecated)特性

有些时候，我们需要标记一些过时的Api为弃用状态，但是我们又不希望完全移除这个版本的Api, 我们可以使用Deprecated特性。

例：我们当前希望弃用ValuesV1Controller, 我们可以指定Deprecated特性的值为true

header返回1.0版本的Api已经过期了，2.0版本中有相同的Api, 可以换用2.0版本的Api提示。

使用ApiVersionNeutral指定不需要版本控制的Api

    [ApiVersionNeutral]
    [Route("api/[controller]")]
    [ApiController]
    public class HealthCheckController : ControllerBase
    {
        public string Get()
        {
            return "Good";
        }
    }