关于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别离运行