asp.net|asp.net core的api版本管理最佳实践 asp.netcore的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; } } }

【asp.net|asp.net core的api版本管理最佳实践】打开postman分别运行