背景：ASP.NET Core 请求管道与中间件机制回顾
在深入 IStartupFilter 之前，我们先回顾一下 ASP.NET Core 的请求管道模型。ASP.NET Core 的核心是一个由中间件组成的管道，每个请求都会依次流经这些中间件，响应则反向返回。
中间件的注册顺序重要性
中间件的注册顺序至关重要。由于管道是线性的，先注册的中间件会先看到请求，并最后看到响应。这意味着：
- 异常处理中间件应该放在最前面，这样才能捕获后续所有中间件抛出的异常。
- 静态文件中间件通常放在靠前的位置，以便尽早短路返回静态资源。
- 路由与认证中间件需要按特定顺序排列，否则可能导致鉴权失效。
顺序写错往往是 ASP.NET Core 应用中最难排查的 bug 之一。
Use、Run、Map 方法
在 Configure 方法中，我们通过 IApplicationBuilder 提供的三个核心方法构建管道：
Use：注册一个中间件，并通过next()调用将控制权交给后续中间件。这是最常用的方式。Run：注册一个终端中间件，它会短路管道，不再调用后续中间件。Map：基于请求路径进行分支，将匹配的请求导入一个独立的子管道。
public void Configure(IApplicationBuilder app)
{
app.Use(async (context, next) =>
{
Console.WriteLine("Middleware A - before");
await next();
Console.WriteLine("Middleware A - after");
});
app.Map("/branch", branchApp =>
{
branchApp.Run(async context =>
{
await context.Response.WriteAsync("From branch");
});
});
app.Run(async context =>
{
await context.Response.WriteAsync("Main pipeline");
});
}
IApplicationBuilder.Build() 构建管道
IApplicationBuilder.Build() 方法会将所有注册的中间件按照”洋葱模型”组装成一个 RequestDelegate，即管道的入口委托。本质上，它利用了委托的嵌套包装：第一个注册的中间件位于最外层，最后注册的终端中间件位于最内层。
理解了这一点，我们就能更好地理解 IStartupFilter 存在的意义。
IStartupFilter 的作用与原理
为什么需要 IStartupFilter
在常规开发中，我们通过 Startup.Configure 方法注册中间件。但有些场景下，类库或框架希望能够在用户 Configure 方法执行之前就把某些中间件注册到管道中，确保这些中间件位于管道的最前端。
最典型的例子就是异常处理中间件。如果异常处理中间件由用户自己注册，用户可能会忘记把它放在第一位；如果某个框架希望提供一个全局的异常处理能力，它就需要一种机制，能在用户代码之前注册中间件。这就是 IStartupFilter 的用武之地。
IStartupFilter 接口定义非常简洁：
namespace Microsoft.AspNetCore.Hosting
{
public interface IStartupFilter
{
Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next);
}
}
它只有一个 Configure 方法，接收一个 Action<IApplicationBuilder>（即用户原本的 Configure 逻辑），返回一个新的 Action<IApplicationBuilder>。这本质上是一个装饰器模式：我们可以在调用 next 之前，先往 IApplicationBuilder 中注册自己的中间件。
IStartupFilter vs IHostingStartup 的区别
很多人会混淆 IStartupFilter 和 IHostingStartup，它们的区别如下：
IHostingStartup：用于在程序集级别向IWebHostBuilder添加配置，例如注册额外的服务、配置项或IStartupFilter。它通常通过HostingStartupAssembly特性激活，是在宿主构建早期执行的。IStartupFilter：用于在管道构建阶段包裹用户的Configure方法，从而在用户中间件之前注册自定义中间件。
简而言之，IHostingStartup 是宿主级别的扩展点，IStartupFilter 是管道构建阶段的扩展点。前者可以注册后者，但二者关注的时机不同。
源码分析：WebHostBuilder 如何调用 IStartupFilter
在 ASP.NET Core 内部，WebHostBuilder 构建应用时，会从 DI 容器中解析所有的 IStartupFilter 实例，并把它们与用户 Startup 类的 Configure 方法串联起来。核心逻辑大致如下（简化版）：
// 伪代码，反映 Microsoft.AspNetCore.Hosting 内部逻辑
var configureBuilder = startup.ConfigureDelegate; // 用户的 Configure 方法
// 将所有 IStartupFilter 反向包裹，形成洋葱结构
foreach (var filter in startupFilters.Reverse())
{
configureBuilder = filter.Configure(configureBuilder);
}
// 最终执行 configureBuilder，构建出最终的管道
configureBuilder(appBuilder);
可以看到，IStartupFilter 的执行顺序是倒序包裹的：最后注册的 IStartupFilter 在最外层，最先执行。这跟我们后面讲到的注册顺序与执行顺序的关系直接相关。
实现自定义 IStartupFilter
完整代码示例
下面我们实现一个 IStartupFilter，它会在管道最前端注册一个自定义中间件：
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
public class CustomMiddlewareStartupFilter : IStartupFilter
{
public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
{
// 返回一个新的 Configure 委托
return builder =>
{
// 先注册我们的中间件——它将位于管道最前端
builder.Use(async (context, nextMiddleware) =>
{
// 在所有请求处理之前执行
context.Response.Headers["X-Powered-By"] = "MyApp";
await nextMiddleware();
});
// 再调用用户原本的 Configure 逻辑
next(builder);
};
}
}
注意这里的关键点：我们在调用 next(builder) 之前就向 builder 注册了中间件。由于 IApplicationBuilder 是按注册顺序构建管道的，所以我们的中间件会位于用户 Configure 方法中所有中间件之前。
注册 IStartupFilter 到 DI 容器的两种方式
方式一：在 ConfigureServices 中直接注册
public void ConfigureServices(IServiceCollection services)
{
services.AddTransient<IStartupFilter, CustomMiddlewareStartupFilter>();
// 其他服务...
}
方式二：通过 IWebHostBuilder 的扩展方法注册
这种方式常用于类库对外提供扩展方法，让使用者在 Program.cs 中通过链式调用启用功能：
public static class CustomMiddlewareExtensions
{
public static IWebHostBuilder UseCustomMiddleware(this IWebHostBuilder builder)
{
builder.ConfigureServices(services =>
{
services.AddTransient<IStartupFilter, CustomMiddlewareStartupFilter>();
});
return builder;
}
}
// 在 Program.cs 中使用
var host = Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
webBuilder.UseCustomMiddleware();
})
.Build();
两种方式在效果上是等价的，选择哪种主要看使用场景：内部应用多用方式一，对外发布的类库多用方式二。
多个 IStartupFilter 的执行顺序
当容器中存在多个 IStartupFilter 时，它们的执行顺序遵循”洋葱模型”：后注册的 filter 包裹在更外层，因此先执行。
假设按顺序注册了 FilterA、FilterB、FilterC，那么最终的包裹顺序是：
FilterC -> FilterB -> FilterA -> 用户的 Configure
也就是说，FilterC 注册的中间件会最先执行。这一点在调试时要特别留意，注册顺序直接决定了”谁在最前面”。
实战场景
场景1：在管道最前端注册统一异常处理中间件
我们希望提供一个类库，无论用户如何写 Configure，都能保证异常处理中间件位于管道最前端：
public class GlobalExceptionStartupFilter : IStartupFilter
{
public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
{
return builder =>
{
builder.Use(async (context, nextMiddleware) =>
{
try
{
await nextMiddleware();
}
catch (Exception ex)
{
context.Response.StatusCode = 500;
context.Response.ContentType = "application/json";
await context.Response.WriteAsync(
System.Text.Json.JsonSerializer.Serialize(new { error = ex.Message }));
}
});
next(builder);
};
}
}
// 注册
services.AddTransient<IStartupFilter, GlobalExceptionStartupFilter>();
这样，无论用户是否记得注册异常处理中间件，框架层都已经保证了它的存在。
场景2：注册请求日志中间件（记录所有请求包括短路请求）
如果我们在 Configure 中通过 app.Use(...) 注册日志中间件，它位于管道中间。一旦静态文件中间件短路返回，日志中间件可能就看不到这次请求了。为了让日志中间件记录所有请求（包括短路的），它必须位于管道最前端：
public class RequestLoggingStartupFilter : IStartupFilter
{
public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
{
return builder =>
{
builder.Use(async (context, nextMiddleware) =>
{
var stopwatch = System.Diagnostics.Stopwatch.StartNew();
await nextMiddleware();
stopwatch.Stop();
Console.WriteLine(
$"{context.Request.Method} {context.Request.Path} " +
$"-> {context.Response.StatusCode} ({stopwatch.ElapsedMilliseconds}ms)");
});
next(builder);
};
}
}
由于它在最前端，即使下游中间件短路，它也依然能捕获到响应状态码和耗时。
场景3：框架/类库自动注册中间件
这是 IStartupFilter 最典型的应用场景。很多知名类库都利用了这一机制：
- Swagger：在 ASP.NET Core 中，
UseSwagger/UseSwaggerUI需要在Configure中显式调用，但如果配合IStartupFilter，可以让插件自动注册文档中间件，减少用户配置负担。 - 健康检查：
HealthCheck服务通常通过services.AddHealthChecks()注册服务，再通过IStartupFilter自动注册/health端点的响应中间件。
示例：让一个监控类库自动注册健康检查端点：
public class HealthCheckEndpointStartupFilter : IStartupFilter
{
public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
{
return builder =>
{
builder.Map("/health", app =>
{
app.Run(async context =>
{
// 简化示例，实际应注入 HealthCheckService
context.Response.StatusCode = 200;
await context.Response.WriteAsync("Healthy");
});
});
next(builder);
};
}
}
注意事项与最佳实践
IStartupFilter 注册的中间件总是在 Configure 方法的中间件之前执行
这是 IStartupFilter 的核心特性，也是它的设计目的。无论用户在 Configure 中如何注册中间件，IStartupFilter 注册的中间件都会位于它们之前。这一行为是确定的、不可绕过的，所以适合用于框架级、全局性的横切关注点。
不要在 IStartupFilter 中注册业务中间件
由于 IStartupFilter 的执行时机早于用户代码，在它里面注册业务中间件会带来两个问题：
- 可读性差：开发者阅读
Configure方法时，无法直观看到所有中间件的注册顺序，容易产生”管道里怎么多了个中间件”的困惑。 - 顺序难以控制：当存在多个
IStartupFilter时，中间件之间的相对顺序依赖注册顺序，隐式且不直观。
因此，IStartupFilter 应该只用于框架级、横切关注点的中间件（如异常处理、日志、监控），业务中间件应放在 Configure 中显式注册。
与 MiddlewareFilter 的区别
ASP.NET Core 中还有一个容易混淆的概念：MiddlewareFilter。
MiddlewareFilter：是一种”通过筛选器管道触发中间件”的机制，它借助 MVC 的筛选器管道，让中间件可以在特定路由或控制器级别生效。它的作用域是局部的。IStartupFilter：作用在宿主启动阶段，注册的中间件作用于整个请求管道，是全局的。
简单来说，如果你想让某个中间件对所有请求生效且位于最前端，用 IStartupFilter；如果你想让中间件只在某些路由或控制器上生效，用 MiddlewareFilter。
小结
IStartupFilter 是 ASP.NET Core 中一个强大但低调的扩展点。它通过装饰器模式包裹用户的 Configure 方法，让框架或类库可以在管道最前端注册中间件，从而实现全局异常处理、请求日志、自动注册端点等横切关注点。理解它的执行时机、注册顺序以及与 IHostingStartup、MiddlewareFilter 的区别，能帮助我们在合适的场景下选择合适的方案，写出更健壮、更易维护的 ASP.NET Core 应用。
在实际开发中，遵循”框架级中间件用 IStartupFilter、业务中间件用 Configure“的原则，可以让管道结构清晰可控，避免隐式行为带来的维护负担。