ASP.NET Core Minimal API中基于Header的路由实现方案问询

针对路径无参数但需要按特定请求头区分路由的场景，这里提供两种实用的Minimal API实现方式：

方法一：使用MapWhen分支路由 #

MapWhen可以根据自定义请求条件（比如请求头的值）划分路由分支，适合路径完全相同但请求头不同的场景。

示例代码：

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// 匹配请求头X-Version=v1的端点
app.MapWhen(context => 
    context.Request.Headers.TryGetValue("X-Version", out var version) && 
    version.Equals("v1", StringComparison.OrdinalIgnoreCase), 
    appBranch =>
    {
        appBranch.MapGet("/api/data", () => Results.Ok(new { Version = "v1", Data = "v1版本数据" }));
    });

// 匹配请求头X-Version=v2的端点
app.MapWhen(context => 
    context.Request.Headers.TryGetValue("X-Version", out var version) && 
    version.Equals("v2", StringComparison.OrdinalIgnoreCase), 
    appBranch =>
    {
        appBranch.MapGet("/api/data", () => Results.Ok(new { Version = "v2", Data = "v2版本数据" }));
    });

// 无匹配请求头时的默认处理
app.MapGet("/api/data", () => Results.BadRequest("请指定有效的X-Version请求头"));

app.Run();

这种方式逻辑清晰，不同请求头对应的端点完全隔离，便于维护。

方法二：自定义端点筛选器（EndpointFilter） #

如果希望在同一个路由下根据请求头分发到不同处理逻辑，或者需要复用请求头验证逻辑，可以自定义EndpointFilter。

步骤1：实现自定义筛选器 #

public class RequireHeaderFilter : IEndpointFilter
{
    private readonly string _headerName;
    private readonly string _headerValue;

    public RequireHeaderFilter(string headerName, string headerValue)
    {
        _headerName = headerName;
        _headerValue = headerValue;
    }

    public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next)
    {
        if (!context.HttpContext.Request.Headers.TryGetValue(_headerName, out var value) ||
            !value.Equals(_headerValue, StringComparison.OrdinalIgnoreCase))
        {
            return Results.NotFound(); // 或返回400/BadRequest
        }
        return await next(context);
    }
}

步骤2：在Minimal API中应用筛选器 #

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// 绑定v1版本的端点，要求X-Version=v1
app.MapGet("/api/data", () => Results.Ok(new { Version = "v1", Data = "v1版本数据" }))
   .AddEndpointFilter(new RequireHeaderFilter("X-Version", "v1"));

// 绑定v2版本的端点，要求X-Version=v2
app.MapGet("/api/data", () => Results.Ok(new { Version = "v2", Data = "v2版本数据" }))
   .AddEndpointFilter(new RequireHeaderFilter("X-Version", "v2"));

// 默认处理
app.MapGet("/api/data", () => Results.BadRequest("请指定有效的X-Version请求头"));

app.Run();

补充说明 #

• 请求头默认不区分大小写，若需要严格匹配可修改StringComparison参数。
• 两种方式都可以扩展到POST/PUT等其他HTTP方法。
• 若需要更复杂的请求头匹配规则（比如正则匹配），只需修改条件判断逻辑即可。

内容的提问来源于stack exchange，提问作者Tomáš Bezouška