asp.net core的api版本管理最佳实践

什么要需要api版本控制

一开始，系统有一个api为客户A服务，随着业务发展，系统进行了升级，这个api也需要调整。但是，我还需要它继续能支持客户A，所以需要引入版本来管理。多个版本的API，相互之间的行为是不相同的。

在asp.net core中实现api 版本方式有哪些？

• 基于请求参数
• 基于URL
• 基于请求头

安装包

微软提供了独立的包支持，通过命令行或者nuget包管理工具引入

Install-Package Microsoft.AspNetCore.Mvc.Versioning

在启动类中启用api版本

定义扩展方法，启用配置

public static class ApiVersioningExtensions
    {
        public static IServiceCollection AddApiVersioning(this IServiceCollection services)
        {
            services.AddApiVersioning(config =>
            {
                // 指定默认版本
                config.DefaultApiVersion = new Microsoft.AspNetCore.Mvc.ApiVersion(1, 0);
                // 如果客户端没有在请求中指定api版本，则使用默认版本
                config.AssumeDefaultVersionWhenUnspecified = true;
                // 公布api版本
                config.ReportApiVersions = true;
            });

            return services;
        }
    }

最佳目录结构

将不同版本的api放到不同的目录下，职责更加清晰

基于url的api版本如何实现

在url中明确知道请求版本，我个人比较喜欢这种

https://xxxx/api/v1/user

https://xxxx/api/v2/user

1.0的api定义

namespace ApiVersioning.Controllers.V1
{
    [Route("api/v{version:apiVersion}/[controller]")]
    [ApiController]
    [ApiVersion("1.0")]
    public class UserController : ControllerBase
    {
        [HttpGet]
        public string Get()
        {
            return "use from api v1";
        }
    }
}

2.0的api定义

namespace ApiVersioning.Controllers.V2
{
    [Route("api/v{version:apiVersion}/[controller]")]
    [ApiController]
    [ApiVersion("2.0")]
    public class UserController : ControllerBase
    {
        [HttpGet]
        public string Get()
        {
            return "use from api v2";
        }
    }
}

运行看效果

基于query的api版本

将版本号拼接到请求参数中

https://xxxx/api/user?api-version=1

https://xxxx/api/v2/user?api-version=2

只需要将api控制器进行简单的调整。将每个控制器的[Route("api/v{version:apiVersion}/[controller]")]修改为[Route("api/[controller]")]。

执行效果

基于http请求头的api版本

修改启动类，增加 config.ApiVersionReader = new HeaderApiVersionReader("x-api-version"); 的配置项

namespace ApiVersioning
{
    public static class ApiVersioningExtensions
    {
        public static IServiceCollection AddApiVersioning(this IServiceCollection services)
        {
            services.AddApiVersioning(config =>
            {
                // 指定默认版本
                config.DefaultApiVersion = new Microsoft.AspNetCore.Mvc.ApiVersion(1, 0);
                // 如果客户端没有在请求中指定api版本，则使用默认版本
                config.AssumeDefaultVersionWhenUnspecified = true;
                // 导出api版本
                config.ReportApiVersions = true;
                // 支持HTTP Header
                config.ApiVersionReader = new HeaderApiVersionReader("x-api-version");
            });

            return services;
        }
    }
}

打开postman分别运行

示例代码

https://gitee.com/dx1024/full...