.NET Core HttpResponseExceptionFilter同步Action不生效问题排查

在ASP.NET Core Web API项目中实现IAsyncExceptionFilter全局异常过滤器，用于捕获所有接口异常、返回固定结构的JSON错误响应，注册过滤器后出现以下现象：

• 返回Task<IActionResult>的异步Action抛出异常时，过滤器可正常生效
• 返回IActionResult的同步Action抛出异常时，过滤器、UseExceptionHandler异常中间件均无法捕获异常
• 将同步Action改为异步签名后，异常处理逻辑恢复正常

相关实现代码 #

异常过滤器代码 #

public class HttpResponseExceptionFilter : IAsyncExceptionFilter
{
    private readonly ILogger<HttpResponseExceptionFilter> _logger;

    public HttpResponseExceptionFilter(ILogger<HttpResponseExceptionFilter> logger)
    {
        _logger = logger;
    }

    public Task OnExceptionAsync(ExceptionContext context)
    {
        if (context.Exception == null)
            return Task.CompletedTask;
        switch (context.Exception)
        {
            case BadHttpRequestException ex:
                context.Result = new JsonResult(new BaseResponse<object?>()
                {
                    StatusCode = ex.StatusCode,
                    Message = ex.Message,
                    Data = null
                })
                {
                    StatusCode = ex.StatusCode
                };
                break;
            default:
                _logger.LogError(context.Exception, "error");
                context.Result = new JsonResult(new BaseResponse<object?>()
                {
                    StatusCode = 500,
                    Message = context.Exception.Message,
                    Data = null
                })
                {
                    StatusCode = 500
                };
                break;
        }
        context.ExceptionHandled = true;
        return Task.CompletedTask;
    }
}

过滤器注册代码 #

builder.Services.AddControllers(options =>
{
    options.Filters.Add<HttpResponseExceptionFilter>();
});

测试接口代码 #

[HttpPost]
[Route("Register")]
public async Task<IActionResult> Register(UserRegisterRequest registerRequest)
{
    throw new BadHttpRequestException("error details", 500);
    User user = await _userService.Register(registerRequest);
    return JsonResult(user);
}

[HttpPost]
[Route("Login")]
public IActionResult Login(string account, string password)
{
    throw new BadHttpRequestException("error details", 500);
    string token = _userService.Login(account, password);
    return JsonResult(new LoginResponse() { Token = token });
}

该现象由两个ASP.NET Core框架的默认行为共同导致：

1. [ApiController]内置过滤器优先级更高：Web API项目默认给控制器加了[ApiController]特性，内置的ModelStateInvalidFilter优先级远高于自定义异常过滤器，同步Action执行前的模型绑定阶段如果抛出BadHttpRequestException，会直接被这个内置过滤器捕获返回默认400响应，根本不会走到后续的自定义异常过滤器、异常中间件管道。而异步Action的调用链被Task封装，异常会在Action执行阶段随Task抛出，绕开了内置过滤器的提前拦截。
2. 同步IO路径的异常特殊处理：Kestrel对同步请求处理路径抛出的BadHttpRequestException有特殊的底层捕获逻辑，默认会直接返回底层错误响应，不会冒泡到上层应用的异常处理管道；异步请求路径的异常会被包装进Task的异常栈，正常进入应用层异常处理流程。

方案1：配置ApiBehaviorOptions统一处理请求类错误（推荐） #

通过官方提供的配置项替换内置的模型绑定/校验错误响应逻辑，和自定义异常过滤器配合覆盖全场景异常，无性能损耗：

builder.Services.AddControllers(options =>
{
    options.Filters.Add<HttpResponseExceptionFilter>();
})
.ConfigureApiBehaviorOptions(options =>
{
    // 替换默认的模型绑定、参数校验错误响应
    options.InvalidModelStateResponseFactory = context =>
    {
        var errMsg = string.Join("; ", context.ModelState.Values
            .SelectMany(v => v.Errors)
            .Select(e => string.IsNullOrEmpty(e.ErrorMessage) ? e.Exception?.Message : e.ErrorMessage));
        return new JsonResult(new BaseResponse<object?>
        {
            StatusCode = StatusCodes.Status400BadRequest,
            Message = errMsg,
            Data = null
        })
        {
            StatusCode = StatusCodes.Status400BadRequest
        };
    };
});

方案2：统一使用异步Action签名（零额外配置） #

项目中所有Action统一使用async Task<IActionResult>签名，哪怕方法内部没有异步调用、不需要写await，编译器也会自动完成Task包装，不会有额外性能开销，异常会正常进入自定义异常处理管道。

方案3：关闭内置拦截+开启同步IO（不推荐生产使用） #

通过配置关闭框架内置的模型校验错误拦截、允许同步IO，让同步路径的异常可以正常冒泡：

// 允许同步IO
builder.Services.Configure<KestrelServerOptions>(options =>
{
    options.AllowSynchronousIO = true;
});
builder.Services.AddControllers(options =>
{
    options.Filters.Add<HttpResponseExceptionFilter>();
})
.ConfigureApiBehaviorOptions(options =>
{
    // 关闭内置模型校验自动返回
    options.SuppressModelStateInvalidFilter = true;
});

该方案会带来线程阻塞的性能损耗，同时需要自行实现参数校验逻辑，仅建议临时调试使用。

内容的提问来源于stack exchange，提问作者HHao