.Net中WebApiController如何实现多版本兼容？

理解多版本兼容的需求

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）。

示例代码：

csharp 复制代码

        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;
        });

版本废弃与兼容处理

标记过时版本：

csharp 复制代码

[ApiVersion("1.0", Deprecated = true)]
public class ProductV1Controller : ControllerBase { ... }

新增SwaggerOperationFilter：

csharp 复制代码

    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 引入分页重构。