ASP.NET API如何实现自动匹配不高于客户端版本的最近可用接口

算力阿峰

2026-10-2

解决方案

你需要的功能由微软官方维护的NuGet包Microsoft.AspNetCore.Mvc.Versioning原生支持，无需自行实现路由逻辑。

操作步骤

安装对应NuGet包
如果你是ASP.NET Core应用，直接安装最新稳定版的Microsoft.AspNetCore.Mvc.Versioning即可，如果需要配合Swagger生成多版本文档，可额外安装Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer。
配置版本控制策略
在Program.cs中添加如下配置（.NET 6+顶层语句写法，旧版本写法对应修改Startup.cs的ConfigureServices方法即可）：

builder.Services.AddApiVersioning(options =>
{
    // 配置默认版本，无匹配时的兜底版本
    options.DefaultApiVersion = new ApiVersion(1, 0);
    // 响应头返回接口支持的所有版本，可按需开启
    options.ReportApiVersions = true;
    // 核心配置：使用最高匹配版本选择器，自动选择不高于请求版本的最近可用接口版本
    options.ApiVersionSelector = new HighestMatchingApiVersionSelector(options);
    // 你用的是URL路径传递版本号，指定版本读取器为URL段模式
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
})
// 启用MVC集成
.AddMvc()
// 按需添加，用于Swagger多版本适配
.AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});