在.NET 8之前，ASP.NET Core项目里要做全局异常处理，常见的做法是自己写一段中间件，或者使用Mvc的ExceptionFilter。这两种方式都能拦住未处理的异常，但配置分散、执行顺序容易和鉴权中间件打架，而且过滤器拿不到某些管道早期的错误。.NET 8新增的IExceptionHandler接口把这件事收归到框架内部，开发者只要实现接口并注册为服务，运行时就会自动介入。它本质上是框架在管道末尾预留的异常终结点，不影响其他中间件的正常逻辑。
一、IExceptionHandler接口的定义与核心方法
IExceptionHandler位于Microsoft.AspNetCore.Diagnostics命名空间，只要求实现一个方法：Task TryHandleAsync(HttpContext context, Exception exception, CancellationToken cancellationToken)。该方法返回布尔值，若返回true表示异常已被处理，框架不再继续抛出；返回false则异常会沿管道向上传递，交给下一个注册的handler或默认页。
这种设计的优势在于支持多个handler链式注册。例如你可以注册一个专门处理业务验证异常的handler，再注册一个兜底记录日志的handler。框架按注册顺序依次调用，直到某个返回true。相比以前在中间件里写一大串if-else，结构清晰很多。下面的代码展示了一个最基础的实现，它将所有异常转为统一JSON格式返回。
using Microsoft.AspNetCore.Diagnostics;
using Microsoft.AspNetCore.Http;
using System.Text.Json;
using System.Threading;
using System.Threading.Tasks;
public class GlobalExceptionHandler : IExceptionHandler
{
public async Task<bool> TryHandleAsync(
HttpContext httpContext,
Exception exception,
CancellationToken cancellationToken)
{
httpContext.Response.StatusCode = 500;
httpContext.Response.ContentType = "application/json";
var result = new
{
success = false,
message = exception.Message
};
await httpContext.Response.WriteAsync(
JsonSerializer.Serialize(result),
cancellationToken);
return true;
}
}
需要注意，在TryHandleAsync内部不要再次抛出原异常，否则会脱离handler控制。如果当前handler只负责记录日志而不负责响应，应当返回false，让后续handler处理响应体。另外，由于handler以单例生命周期注册，其内部不能直接依赖Scoped服务，需要时用httpContext.RequestServices手动解析。
二、在.NET 8中注册与使用方式
注册过程非常简单，在Program.cs里先调用AddExceptionHandler<T>()把实现类加入服务容器，再调用app.UseExceptionHandler()启用中间件即可。框架会自动把所有注册的IExceptionHandler实例收集起来，在异常发生时按顺序执行。下面是一段完整的启动配置示例。
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
// 可继续添加其他handler
// builder.Services.AddExceptionHandler<BusinessExceptionHandler>();
var app = builder.Build();
app.UseExceptionHandler();
app.MapGet("/", () => "ok");
app.Run();
与旧版app.UseExceptionHandler(writeResponse)重载相比，新方式把响应逻辑从lambda移到了独立类，便于单元测试和复用。旧写法要求你在Configure方法里嵌入匿名函数，重构时往往要翻好几个文件。新接口配合DI，可以在handler构造函数里注入ILogger<GlobalExceptionHandler>、IOptions<AppSettings>等，而不必从httpContext临时取。
如果项目中同时存在传统异常处理中间件和IExceptionHandler，框架会优先走handler链；只有所有handler都返回false，才会退回到UseExceptionHandler设置的回退逻辑。因此迁移时可以先并行运行，逐步把旧逻辑搬进handler，验证无误后再移除旧中间件，降低线上风险。
三、与旧方案的对比及生产实践建议
从异常捕获范围看，传统中间件能抓到管道中任意位置抛出的异常，而IExceptionHandler同样工作在管道末端的异常处理器中，能力对等。差异主要在代码组织：过滤器只能覆盖Mvc动作，对静态文件、端点路由前的错误无能为力；handler则无此限制。下表列出三者关键区别。
| 方案 | 覆盖范围 | 依赖注入支持 | 多异常处理 |
|---|---|---|---|
| 自定义中间件 | 全管道 | 构造函数注入 | 需手动分支 |
| ExceptionFilter | 仅Mvc | 属性注入为主 | 需手动分支 |
| IExceptionHandler | 全管道 | 构造函数注入 | 链式注册 |
生产环境建议按异常类型拆分handler。例如第一个handler专门拦截自定义的BusinessException，返回400及业务码；第二个handler拦截DbUpdateException做数据库错误日志；最后一个兜底handler记录未预期异常并返回500。这样运维看日志时能快速区分故障域。代码上可通过exception is BusinessException判断，不符合就返回false交下一个处理。
另外，由于handler是单例，记录日志请用ILogger而不要保存请求级状态到字段。若需读取当前请求信息，始终通过参数httpContext获取。对于需要本地化消息的场景，可以用httpContext.RequestServices.GetService<IStringLocalizer>()解析，避免破坏单例约束。经过这样分层之后，全局异常处理既干净又容易扩展。
IExceptionHandler全局异常处理.NET_8修改时间：2026-08-19 04:38:27