.NET Core中如何在路由仅显示API主次版本的同时保留版本状态标识

没问题，这个需求在.NET Core的API版本控制体系里完全可以实现，核心思路是通过自定义API版本格式化器来分离路由显示的版本格式和系统内部使用的完整版本信息——既让路由只展示主副版本号，又保留版本字符串里的状态标识（如-AB）供系统内部识别。

具体实现步骤 #

1. 创建自定义API版本格式化器 #

实现IApiVersionFormatter接口，重写版本的格式化和解析逻辑：

• FormatApiVersion：负责生成路由中显示的版本字符串，只提取主副版本部分
• ParseApiVersion：负责将路由中的短版本解析回完整的带状态标识的版本（确保系统内部能正确匹配版本）

using Microsoft.AspNetCore.Mvc.Versioning;
using System;

public class CustomApiVersionFormatter : IApiVersionFormatter
{
    // 定义版本状态标识的后缀，比如你的场景是"-AB"
    private const string VersionSuffix = "-AB";

    public string FormatApiVersion(ApiVersion apiVersion, ApiVersionFormat format)
    {
        // 只返回主副版本号，比如把"1.0-AB"格式化为"1.0"
        return apiVersion.ToString(format).Replace(VersionSuffix, string.Empty);
    }

    public ApiVersion ParseApiVersion(string version, ApiVersionFormat format)
    {
        // 解析时把状态标识加回去，确保系统能识别完整版本
        if (!version.EndsWith(VersionSuffix, StringComparison.OrdinalIgnoreCase))
        {
            version += VersionSuffix;
        }
        return ApiVersion.Parse(version);
    }

    // 实现接口的其他方法，直接调用默认逻辑即可
    public bool TryParse(string version, ApiVersionFormat format, out ApiVersion apiVersion)
    {
        try
        {
            apiVersion = ParseApiVersion(version, format);
            return true;
        }
        catch
        {
            apiVersion = default;
            return false;
        }
    }
}

2. 在服务配置中注册自定义格式化器 #

在Program.cs（.NET 6+）或者Startup.cs（旧版本）中，配置API版本控制时指定使用你自定义的格式化器：

var builder = WebApplication.CreateBuilder(args);

// 添加API版本控制服务
builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    // 注册自定义版本格式化器
    options.ApiVersionFormatter = new CustomApiVersionFormatter();
});

// 其他服务配置...

var app = builder.Build();

// 中间件配置...

app.Run();

3. 保留控制器的原始版本属性 #

你的控制器依然保留原来的[ApiVersion]属性，不需要做任何修改：

[ApiVersion("1.0-AB")]
[ApiVersion("2.0-AB")]
[Route("v{version:apiVersion}/controller/action")]
[ApiController]
public class MyController : ControllerBase
{
    // 控制器动作方法示例
    [HttpGet]
    public IActionResult Get()
    {
        var apiVersion = HttpContext.GetRequestedApiVersion();
        // 这里获取到的apiVersion会是完整的"1.0-AB"或"2.0-AB"
        return Ok($"当前API版本：{apiVersion}");
    }
}

效果验证 #

完成配置后，你的API路由会变成：

• v1.0/controller/action
• v2.0/controller/action

而系统内部识别的API版本依然是完整的1.0-AB和2.0-AB，完全满足你的需求——路由简洁，同时版本状态信息不会丢失。

内容的提问来源于stack exchange，提问作者Kevin Pione