理解多版本兼容的需求
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 templatesoptions.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 引入分页重构。
