ASP.NET Core 中的行动过滤器如何使用？

ASP.NET Core 提供了一套强大的过滤器管道机制，其中行动过滤器是不可或缺的组成部分。它能够在控制器的行动方法执行前后运行自定义逻辑，非常适合处理与具体业务动作紧密相关的通用需求。例如，在接口权限校验、请求参数预处理、操作日志记录等场景中，行动过滤器能够有效地将横切关注点与核心业务逻辑分离，从而提升代码的可维护性与复用性。通过合理运用行动过滤器，开发者可以构建出更加健壮且易于扩展的Web应用架构。

行动过滤器的核心概念与工作原理

行动过滤器的核心在于其接口定义。在ASP.NET Core中，要实现一个自定义的行动过滤器，开发者通常需要实现 IActionFilter 接口或者 IAsyncActionFilter 接口。前者主要用于同步调用场景，后者则专为异步操作设计。这两个接口定义了过滤器在行动方法执行前后的拦截点，使得开发者能够在特定的时机插入自定义逻辑。

对于同步接口 IActionFilter 而言，其包含两个核心方法。OnActionExecuting 方法在行动方法执行之前被调用，在这个阶段，开发者可以读取或修改传入的参数，甚至通过设置结果来短路请求，直接返回自定义响应。OnActionExecuted 方法则在行动方法执行之后调用，此时可以获取行动方法的返回值，或者处理执行过程中产生的异常。

异步接口 IAsyncActionFilter 提供了一个统一的入口方法 OnActionExecutionAsync。该方法接收一个 ActionExecutionDelegate 委托，通过调用这个委托来控制后续过滤器管道以及行动方法的执行。这种设计使得异步资源清理、异步权限校验等操作能够以非阻塞的方式高效完成。

同步与异步行动过滤器的具体实现

在实际开发中，记录接口的执行耗时是一个非常常见的需求。我们可以通过实现同步过滤器来完成这项任务。在行动方法执行前启动计时器，在执行后停止计时器并记录时间。同时，在执行前的方法中，还可以顺带进行一些简单的参数校验工作，例如检查路由或请求体中是否包含必要的标识符。如果缺少必要参数，可以直接中断请求管道并返回错误提示。

如果业务场景需要在过滤器中调用外部服务，比如查询数据库或调用远程权限校验接口，同步过滤器可能会导致线程阻塞。此时，异步行动过滤器就成为了更好的选择。通过异步方式，可以在执行前逻辑中等待异步操作完成，再决定是否放行请求。在执行后逻辑中，也可以对可能发生的异常进行统一捕获和记录，避免异常直接抛出影响上层处理逻辑。

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
using System.Diagnostics;

// 定义同步行动过滤器，用于记录执行耗时
public class ExecutionTimeActionFilter : IActionFilter
{
    private Stopwatch _stopwatch;

    // 行动方法执行前触发
    public void OnActionExecuting(ActionExecutingContext context)
    {
        _stopwatch = Stopwatch.StartNew();
        // 校验是否包含必填参数id
        if (!context.ActionArguments.ContainsKey("id"))
        {
            // 短路请求并返回错误信息
            context.Result = new BadRequestObjectResult("缺少必填参数id");
        }
    }

    // 行动方法执行后触发
    public void OnActionExecuted(ActionExecutedContext context)
    {
        _stopwatch.Stop();
        var controllerName = context.Controller.GetType().Name;
        var actionName = context.ActionDescriptor.DisplayName;
        var elapsedTime = _stopwatch.ElapsedMilliseconds;
        // 输出耗时日志
        Console.WriteLine($"控制器 {controllerName} 的行动 {actionName} 执行耗时：{elapsedTime} 毫秒");
    }
}

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
using System.Threading.Tasks;

// 定义异步行动过滤器，用于异步权限校验
public class AsyncPermissionActionFilter : IAsyncActionFilter
{
    // 异步执行入口
    public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
    {
        // 执行前逻辑：校验用户登录状态
        var userId = context.HttpContext.User.FindFirst("UserId")?.Value;
        if (string.IsNullOrEmpty(userId))
        {
            context.Result = new UnauthorizedObjectResult("用户未登录");
            return;
        }

        // 调用next执行后续管道和行动方法
        var executedContext = await next();

        // 执行后逻辑：处理异常情况
        if (executedContext.Exception != null)
        {
            Console.WriteLine($"行动执行异常：{executedContext.Exception.Message}");
        }
    }
}

行动过滤器的多种注册方式与作用域

定义好过滤器之后，必须将其注册到ASP.NET Core的请求处理管道中才能发挥作用。根据业务需求的不同，框架提供了三种主要的注册方式：全局注册、控制器级别注册以及行动方法级别注册。不同的注册方式决定了过滤器的作用范围，开发者需要根据实际场景灵活选择。

全局注册是在 Program.cs 文件中配置的。通过在 AddControllers 方法中添加过滤器，该过滤器将对应用内所有控制器的所有行动方法生效。这种方式非常适合处理全局性的横切关注点，例如统一的耗时监控或全局的日志记录。同时，如果过滤器中使用了依赖注入的服务，也需要在此处将其注册到容器中。

如果只需要某个特定控制器的行动方法应用过滤器，可以使用控制器级别注册。通过在控制器类上添加 ServiceFilter 或 TypeFilter 特性即可实现。需要注意的是，使用 ServiceFilter 时，必须确保该过滤器已经通过依赖注入容器注册，否则会在运行时抛出异常。

对于更加精细化的控制，可以直接在具体的行动方法上添加特性，实现行动方法级别注册。这样只有被标记的方法才会应用该过滤器逻辑。这种方式适用于那些只针对个别接口的特殊处理需求，能够最大程度地避免对其他接口产生不必要的影响。

var builder = WebApplication.CreateBuilder(args);

// 全局注册行动过滤器
builder.Services.AddControllers(options =>
{
    options.Filters.Add<ExecutionTimeActionFilter>();
    options.Filters.Add<AsyncPermissionActionFilter>();
});

// 将过滤器注册到依赖注入容器
builder.Services.AddScoped<ExecutionTimeActionFilter>();
builder.Services.AddScoped<AsyncPermissionActionFilter>();

var app = builder.Build();
app.MapControllers();
app.Run();

using Microsoft.AspNetCore.Mvc;

// 控制器级别注册
[ServiceFilter(typeof(ExecutionTimeActionFilter))]
[ApiController]
[Route("api/[controller]")]
public class UserController : ControllerBase
{
    [HttpGet("{id}")]
    public string GetUser(int id)
    {
        return $"用户ID：{id}";
    }
}

[ApiController]
[Route("api/[controller]")]
public class OrderController : ControllerBase
{
    // 行动方法级别注册
    [ServiceFilter(typeof(ExecutionTimeActionFilter))]
    [HttpPost]
    public string CreateOrder([FromBody] object orderInfo)
    {
        return "订单创建成功";
    }

    [HttpGet]
    public string GetOrderList()
    {
        return "订单列表";
    }
}

行动过滤器与中间件的差异及依赖注入应用

在ASP.NET Core中，中间件和行动过滤器都可用于处理横切关注点，但两者存在本质区别。中间件作用于所有进入应用的HTTP请求，它只能获取 HttpContext 的基础信息，无法感知MVC框架的内部细节。而行动过滤器则专门作用于MVC或Web API的行动方法层面，能够获取控制器实例、行动方法描述符、路由参数以及模型绑定结果等丰富的上下文信息。

这种上下文信息的差异决定了它们的适用场景。中间件更适合处理与具体业务无关的通用请求逻辑，如跨域配置、静态文件提供、全局异常处理等。行动过滤器则专注于业务相关的通用逻辑，例如基于业务角色的接口权限校验、特定参数的预处理转换以及针对行动方法的操作日志记录。

行动过滤器天然支持依赖注入（DI）。这意味着开发者可以在过滤器的构造函数中请求所需的服务，如日志记录器、数据库访问上下文或配置服务。当过滤器通过 ServiceFilter 或 TypeFilter 注册，或者作为全局过滤器添加时，ASP.NET Core的依赖注入容器会自动解析并注入相应的依赖项。这种设计使得过滤器能够轻松集成各种基础服务，进一步增强了其处理复杂业务逻辑的能力。

using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.Extensions.Logging;

public class LogActionFilter : IActionFilter
{
    private readonly ILogger<LogActionFilter> _logger;

    // 通过构造函数注入日志服务
    public LogActionFilter(ILogger<LogActionFilter> logger)
    {
        _logger = logger;
    }

    public void OnActionExecuting(ActionExecutingContext context)
    {
        _logger.LogInformation("行动方法开始执行，参数：{Arguments}", context.ActionArguments);
    }

    public void OnActionExecuted(ActionExecutedContext context)
    {
        _logger.LogInformation("行动方法执行结束，结果：{Result}", context.Result);
    }
}

// 在容器中注册过滤器及其依赖项
builder.Services.AddScoped<LogActionFilter>();

综上所述，ASP.NET Core 的行动过滤器为处理MVC层面的横切关注点提供了一种灵活且强大的解决方案。通过理解同步与异步接口的区别，合理选择全局、控制器或方法级别的注册方式，并结合依赖注入机制，开发者能够构建出既保持业务逻辑纯粹性，又具备高度可维护性和扩展性的Web应用。在实际架构设计中，建议根据过滤器的具体职责和作用范围，将其与中间件合理搭配，共同构建稳健的请求处理管道。

ASP.NET_CoreAction_Filter依赖注入过滤器管道中间件修改时间：2026-07-24 11:30:33