practical-aspnetcore 实战:Minimal API Endpoint Filter 从单过滤器应用到多过滤器管线解析
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();
这段代码的要点如下:
- 端点定义:
app.MapGet("/", ...)注册根路径的 GET 端点,处理器接收HttpContext,用Results.Content直接返回一段 HTML,并显式指定text/html内容类型。 - 原始字符串插值:响应模板使用
$$"""..."""形式的原始字符串插值,插值边界是双花括号{{ ... }},因此{{ context.Items["message"]}}会把context.Items["message"]的值渲染进最终 HTML。 - 挂载过滤器:对
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 系列实际上给出了从入门到进阶的完整路径:
- 单过滤器:
AddEndpointFilter((context, next) => ...)是最小的接入形态,通过HttpContext.Items即可向管线传递数据; - 多过滤器:链式叠加,
next之前的代码按挂载顺序执行; - 执行顺序:
next前后构成洋葱模型,退出阶段的代码逆向执行,可通过自定义响应头验证; - 结果改写:
await next(context)拿到结果后用IStatusCodeHttpResult等接口做模式匹配,实现统一响应处理。
进一步探索时,可以:
- 对比阅读 endpoint-filter-2/Program.cs 与 endpoint-filter-3/Program.cs,加深对叠加与顺序的理解;
- 查看 endpoint-filter-4/Program.cs,把结果改写模式应用到自己的错误处理流程中;
- 返回 projects/minimal-api/README.md 总览 Minimal API 的其他主题(路由约束、参数绑定、Route Group、Typed Results 等),了解过滤器在整个 Minimal API 生态中的位置。