理解多版本兼容的需求
Web API 版本兼容的必要性：业务迭代、客户端适配、接口演进时的平滑过渡。常见场景包括新增字段、废弃旧接口、重构参数结构等。
版本控制实现方式
URL 路径版本控制
在路由中嵌入版本号（如 api/v1/products），通过路由配置或特性标记实现。
查询字符串版本控制
通过 URL 参数传递版本（如 api/products?version=1），灵活但需手动解析。
请求头版本控制
利用 Accept 或自定义头（如 X-API-Version）传递版本，无侵入性但需客户端配合。
具体实现可参考NetCoreKevin中的Kevin.Api.Versioning模块
一个基于NET8搭建DDD-微服务-现代化Saas企业级WebAPI前后端分离架构：前端Vue3、IDS4单点登录、多级缓存、自动任务、分布式、AI智能体、一库多租户、日志、授权和鉴权、CAP事件、SignalR、领域事件、MCP协议服务、IOC模块化注入、Cors、Quartz自动任务、多短信、AI、AgentFramework、SemanticKernel集成、RAG检索增强+Qdrant矢量数据库、OCR识别、API多版本、单元测试、RabbitMQ
项目地址：github：https://github.com/junkai-li/NetCoreKevin
Gitee: https://gitee.com/netkevin-li/NetCoreKevin
多版本代码组织策略
文件夹分层
按版本号划分目录（如 Controllers/V1/ProductController.cs），物理隔离但可能重复代码。
条件逻辑分支
同一控制器内通过 if-else 或策略模式处理不同版本，适合差异较小的场景。
抽象基类与继承
公共逻辑提取到基类，派生类实现版本差异，平衡复用与隔离。
版本切换与路由配置
使用 IApiVersionReader 配置版本读取方式（如 HeaderApiVersionReader）。
示例代码：
var apiVersioningBuilder = services.AddApiVersioning(options =>
{
//通过Header向客户端通报支持的版本
options.ReportApiVersions = true;
//允许不加版本标记直接调用接口
options.AssumeDefaultVersionWhenUnspecified = true;
//接口默认版本
//options.DefaultApiVersion = new ApiVersion(1, 0);
//如果未加版本标记默认以当前最高版本进行处理
options.ApiVersionSelector = new CurrentImplementationApiVersionSelector(options);
// 结合多种版本控制方式
options.ApiVersionReader = ApiVersionReader.Combine(
new QueryStringApiVersionReader("version"),
new UrlSegmentApiVersionReader(),
new HeaderApiVersionReader("X-API-Version"),
new MediaTypeApiVersionReader("version")
);
});
apiVersioningBuilder.AddApiExplorer(options =>
{
// add the versioned api explorer, which also adds IApiVersionDescriptionProvider service
// note: the specified format code will format the version as "'v'major[.minor][-status]"
options.GroupNameFormat = "'v'VVV";
// note: this option is only necessary when versioning by url segment. the SubstitutionFormat
// can also be used to control the format of the API version in route templates
options.SubstituteApiVersionInUrl = true;
});
版本废弃与兼容处理
标记过时版本：
[ApiVersion("1.0", Deprecated = true)]
public class ProductV1Controller : ControllerBase { ... }
新增SwaggerOperationFilter：
public class SwaggerOperationFilter : IOperationFilter
{
public void Apply(OpenApiOperation operation, OperationFilterContext context)
{
var apiDescription = context.ApiDescription;
//判断接口遗弃状态，对接口进行标记调整
operation.Deprecated |= apiDescription.IsDeprecated();
if (operation.Parameters == null)
{
return;
}
//为 api-version 参数添加必填验证
foreach (var parameter in operation.Parameters)
{
var description = apiDescription.ParameterDescriptions.First(p => p.Name == parameter.Name);
if (parameter.Description == null)
{
parameter.Description = description.ModelMetadata?.Description;
}
if (parameter.Schema.Default == null && description.DefaultValue != null)
{
parameter.Schema.Default = new OpenApiString(description.DefaultValue.ToString());
}
parameter.Required |= description.IsRequired;
}
}
}
通过 Sunset 响应头通知客户端废弃时间，并提供迁移文档。
测试与文档化
单元测试覆盖不同版本逻辑，确保兼容性。
使用 Swagger 或 OpenAPI 生成多版本文档，标注版本差异。
性能与维护权衡
缓存策略减少版本判断开销，避免过度设计。
制定版本生命周期规则（如支持 N-2 版本）。
案例分析
对比电商平台订单接口的演进：V1 仅基础字段，V2 增加优惠券逻辑，V3 引入分页重构。
