关于asp.net-core:aspnet-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 别离运行