practical-aspnetcore 实战:Minimal API Endpoint Filter 从单过滤器应用到多过滤器管线解析

原创2026-10-14 18:25:121,452 阅读
文章标签:示例工程

practical-aspnetcore 实战:Minimal API Endpoint Filter 从单过滤器应用到多过滤器管线解析

本指南基于 practical-aspnetcore 仓库的 projects/minimal-api/endpoint-filter-* 系列示例,系统讲解如何为 Minimal API 端点挂载 Endpoint Filter(端点过滤器),并深入剖析多个过滤器叠加时的执行顺序、如何在过滤器内检查并改写请求结果。读完本文,你将能够独立写出可复用的端点过滤器,并理解过滤器与端点处理器之间的"洋葱模型"调用链。

Endpoint Filter 是什么

Endpoint Filter 是 ASP.NET Core Minimal API 提供的一种轻量级横切机制:它允许你在路由匹配成功之后、端点处理器执行前后插入自定义逻辑,常用于鉴权前置检查、日志记录、统一改写响应、透传上下文数据等场景。

在仓库的 projects/minimal-api/README.md 中,"Endpoint Filter" 一节整理了 4 个递进式示例,完整覆盖了这一特性的核心用法:

示例目录 主题
endpoint-filter-1 为单个端点应用一个 Endpoint Filter
endpoint-filter-2 为同一端点叠加多个 Endpoint Filter
endpoint-filter-3 观察多个过滤器在 RouteHandlerFilterDelegate 前后代码的执行顺序
endpoint-filter-4 在过滤器内用 IStatusCodeHttpResult 检查返回结果并改写

运行环境与工程结构

示例工程的目标框架为 .NET 10。查看 endpoint-filter-1.csproj:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>true</ImplicitUsings>
    <LangVersion>preview</LangVersion>
  </PropertyGroup>
</Project>

要点说明:

  • ImplicitUsings 开启后,WebApplication、HttpContext、Results 等常用命名空间无需显式 using,示例代码因此非常精简;
  • LangVersion 设置为 preview,以启用原始字符串插值等最新 C# 语法特性;
  • 仓库根目录的 global.json 将 SDK 固定为 10.0.0(rollForward: major、allowPrerelease: true),与示例的目标框架保持一致。

运行方式(在对应示例目录下):

dotnet run

启动后浏览器访问 http://localhost:5000(或终端输出的 URL)即可看到效果。

示例一:为单个端点应用 Endpoint Filter

这是 endpoint-filter-1 的核心演示,完整源码见 Program.cs:

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

app.MapGet("/", (HttpContext context) => Results.Content($$"""
<html>
<head>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-0evHe/X+R7YkIZDRvuzKMRqM+OrBnVFBL6DOitfPri4tjfHxaWutUpFmBp4vmVor" crossorigin="anonymous">
</head>
<body>
    <div class="container">
        {{ context.Items["message"]}}
    </div>
</body>
</html>
""", "text/html"))
    .AddEndpointFilter((context, next) =>
    {
       context.HttpContext.Items["message"] = "hello from filter";
       return next(context);
    });

app.Run();

这段代码的要点如下:

  1. 端点定义:app.MapGet("/", ...) 注册根路径的 GET 端点,处理器接收 HttpContext,用 Results.Content 直接返回一段 HTML,并显式指定 text/html 内容类型。
  2. 原始字符串插值:响应模板使用 $$"""...""" 形式的原始字符串插值,插值边界是双花括号 {{ ... }},因此 {{ context.Items["message"]}} 会把 context.Items["message"] 的值渲染进最终 HTML。
  3. 挂载过滤器:对 MapGet 返回的 RouteHandlerBuilder 链式调用 .AddEndpointFilter(...)。这里的 lambda 签名是 (EndpointFilterInvocationContext context, EndpointFilterDelegate next):
    • 通过 context.HttpContext 拿到当前请求的 HttpContext,把 "hello from filter" 写入 HttpContext.Items["message"]——这是过滤器向端点处理器(以及最终响应)传递数据的典型方式;
    • return next(context) 调用下一段管线(此处即真正的端点处理器),并返回其执行结果。

访问页面后,{{ context.Items["message"]}} 位置会渲染出 hello from filter,说明过滤器中写入的数据成功流向了端点处理器的响应模板。

深入理解 AddEndpointFilter 的调用契约

从上面的代码可以看出过滤器 lambda 的两个参数承载了核心契约:

  • context(EndpointFilterInvocationContext):封装了当前 HttpContext,同时暴露本次端点调用的参数列表 Arguments,过滤器可以读取、甚至替换传入端点的参数;
  • next(EndpointFilterDelegate):指向管线中后续的过滤器或最终的端点处理器。调用 next(context) 返回 ValueTask<object?>,其中对象本质上是端点最终产生的 IResult 实例。

AddEndpointFilter 是扩展方法,作用于 RouteHandlerBuilder,因此支持像示例中那样链式连续调用,这一特点在下一个示例中会被充分使用。

示例二:为同一端点叠加多个 Endpoint Filter

当同一个端点需要做多件事时(例如:先写审计日志、再做鉴权、再改写响应头),可以把多个过滤器依次挂上去。endpoint-filter-2 展示了这一用法,完整源码见 Program.cs:

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

app.MapGet("/", (HttpContext context) => Results.Content($$"""
<html>
<head>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-0evHe/X+R7YkIZDRvuzKMRqM+OrBnVFBL6DOitfPri4tjfHxaWutUpFmBp4vmVor" crossorigin="anonymous">
</head>
<body>
    <div class="container">
        {{ context.Items["message"]}}
    </div>
</body>
</html>
""", "text/html"))
    .AddEndpointFilter((context, next) =>
    {
       context.HttpContext.Items["message"] = "filter 1";
       return next(context);
    })
    .AddEndpointFilter((context, next) =>
    {
       context.HttpContext.Items["message"] += " filter 2";
       return next(context);
    })
    .AddEndpointFilter((context, next) =>
    {
       context.HttpContext.Items["message"] += " filter 3";
       return next(context);
    });

app.Run();

三个过滤器分别对 context.HttpContext.Items["message"] 执行"赋值 / 追加 / 追加",最终页面渲染出 filter 1 filter 2 filter 3。这验证了一个关键事实:多个过滤器按 AddEndpointFilter 的调用顺序依次执行(第一个挂载的过滤器最先运行 next 之前的代码)。

示例三:过滤器在 next 前后代码的执行顺序

理解了多个过滤器的叠加后,下一个自然的问题是:如果我在 next(context) 之后再写代码,它会什么时候执行?endpoint-filter-3 正是为了回答这个问题而设计的,完整源码见 Program.cs:

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

app.MapGet("/", (HttpContext context) => Results.Content($$"""
<html>
    <head>
        <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-0evHe/X+R7YkIZDRvuzKMRqM+OrBnVFBL6DOitfPri4tjfHxaWutUpFmBp4vmVor" crossorigin="anonymous">
    </head>
    <body>
        <div class="container">
            {{ context.Items["message"]}}
        </div>
    </body>
</html>
""", "text/html"))
    .AddEndpointFilter((context, next) =>
    {
       context.HttpContext.Items["message"] = "filter 1";
       var result = next(context);
       context.HttpContext.Response.Headers["x-application"] += "filter 1 ";
       return result;
    })
    .AddEndpointFilter((context, next) =>
    {
       context.HttpContext.Items["message"] += " filter 2";
       var result = next(context);
       context.HttpContext.Response.Headers["x-application"] += "filter 2 ";
       return result;
    })
    .AddEndpointFilter((context, next) =>
    {
       context.HttpContext.Items["message"] += " filter 3";
       var result = next(context);
       context.HttpContext.Response.Headers["x-application"] += "filter 3 ";
       return result;
    });

app.Run();

每个过滤器都把"进入"和"退出"逻辑都写了出来:

  • next(context) 之前的代码:在请求进入更内层管线前执行,本例中按 filter 1 → filter 2 → filter 3 的顺序写入 message,因此页面渲染 filter 1 filter 2 filter 3;
  • next(context) 之后的代码:在内层管线全部完成后、逐层返回时执行,本例中向 x-application 响应头追加内容。

从源码结构可以推断,多个过滤器构成经典的"洋葱模型":next 之前的部分按挂载顺序正向执行,next 之后的部分按挂载顺序逆向执行。用浏览器开发者工具查看响应头 x-application,可以看到追加顺序与 message 的拼接顺序相反,这正是"进入正向、退出逆向"的直接证据。

理解这一顺序对实际开发很有价值:例如"进入时记录开始时间、退出时计算耗时并写入响应头"的计时过滤器,就必须分别写在 next 的前后两侧。

示例四:在过滤器内检查并改写返回结果

过滤器不仅能"顺带"做点事,还能读取端点处理器产生的结果,甚至替换它。endpoint-filter-4 展示了如何通过 IStatusCodeHttpResult 判断返回结果,完整源码见 Program.cs:

app.MapGet("/about/{name}", (string name) =>
{
    if (name.Equals("anne"))
        return Results.Ok(name);
    else
        return Results.BadRequest();
}).AddEndpointFilter(async (context, next) =>
{
    var result = await next(context);

    return result switch
    {
        IStatusCodeHttpResult a when a.StatusCode == StatusCodes.Status400BadRequest => Results.Ok("Bad Request"),
        _ => result
    };
});

本例中端点处理器根据路由参数 name 返回 Results.Ok(name) 或 Results.BadRequest(),而过滤器通过 await next(context) 拿到真实结果后,用 C# 模式匹配检查:

  • 若结果实现了 IStatusCodeHttpResult 且 StatusCode 为 400 Bad Request,则替换为 Results.Ok("Bad Request");
  • 其余情况原样返回。

这种"结果改写"模式非常适合统一处理错误:把 BadRequest 包装成更友好的响应、给 NotFound 统一附加说明、或者统一为成功响应补充字段等。注意这里的过滤器使用了 async/await 版本,说明过滤器本身可以是异步的。

该示例的 README 还列出了一组可用于结果检测的新增 HttpResults 接口,均位于 Microsoft.AspNetCore.Http 命名空间:

接口 用途
IContentTypeHttpResult 携带内容类型信息的 HTTP 结果
IFileHttpResult 文件类结果
INestedHttpResult 包装了内层结果的复合结果
IStatusCodeHttpResult 携带状态码的结果(如 Ok、BadRequest)
IValueHttpResult 携带返回值的结果
IValueHttpResult<TValue> 携带强类型返回值的结果

利用这些接口做模式匹配,可以写出不依赖具体结果类型、又足够精确的过滤器逻辑。

小结与延伸阅读

从 endpoint-filter-1 出发,本仓库的 Endpoint Filter 系列实际上给出了从入门到进阶的完整路径:

  1. 单过滤器:AddEndpointFilter((context, next) => ...) 是最小的接入形态,通过 HttpContext.Items 即可向管线传递数据;
  2. 多过滤器:链式叠加,next 之前的代码按挂载顺序执行;
  3. 执行顺序:next 前后构成洋葱模型,退出阶段的代码逆向执行,可通过自定义响应头验证;
  4. 结果改写:await next(context) 拿到结果后用 IStatusCodeHttpResult 等接口做模式匹配,实现统一响应处理。

进一步探索时,可以:

登录后查看全文
practical-aspnetcore