ASP.NET Core Filters

ASP.NET MVC 中的过滤器(Filter)是 AOP(面向切面编程) 思想的一种实现,供我们在执行管道的特定阶段执行代码,通过使用过滤器可以实现 短路请求、缓存请求结果、日志统一记录、参数合法性验证、异常统一处理、返回值格式化 等等,同时使业务代码更加简洁单纯,避免很多重复代码。

过滤器执行流程

MVC 在选择要执行的 Action 方法后,会执行过滤器管道,流程如下图:

MVC 调用管道

过滤器作用域

过滤器作用域设置是非常灵活的,可以选择为:

  1. 全局有效(整个 MVC 应用程序下的每一个 Action);

  2. 仅对某些 Controller 有效 (控制器内所有的 Action );

  3. 仅对某些 Action 有效;

过滤器类型

过滤器分为 Authorization Filter、Resource Filter、Action Filter、Exception Filter、Result Filter,每种过滤器都有其应用场景,不同类型的过滤器会在执行管道的不同阶段运行,我们需要根据实际情况来选择使用。

Authorization Filter

授权过滤器在过滤器管道中第一个被执行,通常用于验证请求的合法性(通过实现接口 IAuthorizationFilter or IAsyncAuthorizationFilter

Resource Filter

资源过滤器在过滤器管道中第二个被执行,通常用于请求结果的缓存和短路过滤器管道(通过实现接口 IResourceFilter or IAsyncResourceFilter

Action Filter

Acioin 过滤器可设置在调用 Acioin 方法之前和之后执行代码,如:请求参数的验证(通过实现接口 IActionFilter or IAsyncActionFilter

Exception Filter

程序异常信息处理(通过实现接口 IExceptionFilter or IAsyncExceptionFilter

Result Filter

Action 执行完成后执行,对执行结果格式化处理(通过实现接口 IResultFilter or IAsyncResultFilter

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
public class AddHeaderResultFilter : IResultFilter
{
public void OnResultExecuted(ResultExecutedContext context)
{
Console.WriteLine("AddHeaderResultFilter:OnResultExecuted");
}

public void OnResultExecuting(ResultExecutingContext context)
{
context.HttpContext.Response.Headers.Add("ResultFilter", new string[] { "AddHeader" });

context.Result = new ObjectResult(new ApiResult<string>()
{
Code = Enum.ResultCode.Success,
Data = "我是 AddHeaderResultFilter 修改后的值"
});
}
}

Filter Attributes

将过滤器接口的实现以特性(Attributes) 的方式使用是非常方便的,过滤器特性可应用于 Controller 和 Action 。框架包含了内置的基于特性的过滤器,我们可以直接继承或另外定制。

继承内置的 ExceptionFilterAttribute:

1
2
3
4
5
6
7
8
9
10
11
public class CustomExceptionFilterAttribute : ExceptionFilterAttribute
{
public override void OnException(ExceptionContext context)
{
context.Result = new ObjectResult(new ApiResult()
{
Code = Enum.ResultCode.Exception,
ErrorMessage = $"CustomExceptionFilterAttribute: {context.Exception.Message}"
});
}
}

1
2
3
4
5
[CustomExceptionFilter]
public ApiResult ExceptionAttributeTest()
{
throw new Exception("Boom");
}

定制 ResourceFilterAttribute:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
public class ShortCircuitingResourceFilterAttribute : Attribute, IResourceFilter
{
public void OnResourceExecuted(ResourceExecutedContext context)
{
}

public void OnResourceExecuting(ResourceExecutingContext context)
{
context.Result = new ObjectResult(new ApiResult<string>()
{
Code = Enum.ResultCode.Failed,
Data = "我是 ShortCircuitingResourceFilterAttribute 的返回值"
});
}
}

过滤器实战

问题:在开发中都存在这样的场景,方法参数需要添加一些 if 的判断,不合法直接返回错误信息,方法体加个 try\catch,捕获到异常后记录日志,而这些基本是每一个接口方法必须的,实际情况下我们可能是 ctrl+c & ctrl+v ,部分代码微调,搞定,并不会花什么时间,但我们可以看看整个文件的代码,大部分都是一样的架子,头部验证,尾部捕获,中间调用主逻辑层的方法,满满的重复代码,而且如果后期要调整基础架子,每个方法都得来一遍,那必须得蛋疼死。

解决方案: Action Filter + Exception Filter

  1. 创建一个 Filter,同时实现 IAsyncActionFilter 和 IAsyncExceptionFilter:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    public class XXXActionFilter : IAsyncActionFilter, IAsyncExceptionFilter
    {
    private IDictionary<string, object> _actionArguments;

    public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
    {
    // 如果参数验证不通过,返回参数错误的信息
    if (!context.ModelState.IsValid)
    {
    var errorMessages = new List<string>();
    foreach (var key in context.ModelState.Keys)
    {
    var state = context.ModelState[key];
    var errorModel = state?.Errors?.First();
    if (errorModel != null)
    errorMessages.Add($"{key}:{errorModel.ErrorMessage}");
    }
    var result = new ApiResult()
    {
    Code = ResultCode.ArgumentError,
    Message = errorMessages.Join(",")
    };
    context.Result = new ObjectResult(result);
    return;
    }

    // 保存下来,ExceptionContext 中取不到,如果出异常了需要记录请求参数
    _actionArguments = context.ActionArguments;

    await next();
    }

    public async Task OnExceptionAsync(ExceptionContext context)
    {

    // 记录异常日志
    // some code..........

    var result = new ApiResult()
    {
    Code = ResultCode.Exception,
    Message = $"{context.ActionDescriptor.RouteValues["action"]} Exception")
    };
    context.Result = new ObjectResult(result);
    await Task.CompletedTask;
    }
    }
  2. Startup.cs 的 ConfigureServices 中添加 XXXActionFilter 为全局有效:

    1
    2
    3
    4
    services.AddMvc(options =>
    {
    options.Filters.Add<XXXActionFilter>();
    });
  3. Controller 中的添加测试方法 :

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    public ApiResult ActionTest(XXXRequest request)
    {
    if (request.Id == "1")
    {
    throw new Exception("xxxx");
    }
    return new ApiResult<string>()
    {
    Code = Enum.ResultCode.Success,
    Data = "ActionTest"
    };
    }
    1
    2
    3
    4
    5
    public class XXXRequest
    {
    [Required]
    public string Id { get; set; }
    }

调用 ActionTest 进行测试,如果 id 没传,会进去 OnActionExecutionAsync 的 context.ModelState.IsValid 为 fasle 的情况:

invalid

如果 id 为1,会进入 OnExceptionAsync:

exception

其他情况下正常返回:

success

参考链接

如果对你有帮助就好