Asp.Net Core 輕鬆學-被低估的過濾器
前言
過濾器，從我們開始開發 Asp.Net 應用程式開始，就一直伴隨在我們左右；Asp.Net Core 提供多種型別的過濾器，以滿足多種多樣的業務應用場景；並且在 Asp.Net Core 本身，過濾器的應用也非常廣泛；但是，在實際的業務場景中，大部分開發人員只使用到其中 1 到 2 種類型，當然，這其中大部分可能性是由於業務場景的適用性使然，本文嘗試簡單介紹 Asp.Net Core 中提供的各種過濾器，以及實際的應用場景，希望對您有所幫助。
1. 介紹
1.1 作用範圍
過濾器的作用範圍
每種不同的過濾器都有實際的作用範圍，有一些全域性過濾器還有作用域的限制，這取決於應用開發者在定義和初始化過濾器的時候的選擇，每個過濾器本身處理任務的許可權和功能都大不相同，但是他們都有一個共同點，就是通過特性標記的方式使用，比如以下程式碼，對一個 Action 使用了過濾器 CustomerActionFilter
[CustomerActionFilter]
public ActionResult<string> Get(int id)
{
return "value";
}1.2 過濾器的工作原理
原理解釋
過濾器一般在 Asp.Net Core MVC 管道內執行，一般在操作執行之前（befor） 或者執行之後（after） 執行，以供開發者可以選擇在不同的執行階段介入處理
1.3 過濾器型別，看下圖
型別介紹
上圖既是 Asp.Net Core 內建的各種過濾器型別，也是其執行優先順序順序，相同型別的過濾器還可以定義在某個階段執行的順序
- 授權過濾器 AuthorizeAttribute
- 資源過濾器 IResourceFilter
- 異常過濾器 IExceptionFilter
- 操作過濾器 ActionFilterAttribute
- 結果過濾器 IResultFilter
3. 授權過濾器
3.1 使用介紹
在請求到達的時候最先執行，優先順序最高，主要作用是提供使用者請求許可權過濾，對不滿足許可權的使用者，可以在過濾器內執行拒絕操作，俗稱“管道短路”
*注意：該過濾器只有執行之前（befor），沒有執行之後（after）的方法
通常情況下，不需要自行編寫過濾器，因為該過濾器在 Asp.Net Core 內部已經有了預設實現，我們需要做的就是配置授權策略或者實現自己的授權策略，然後由系統內建的授權過濾器呼叫授權策略即可
必須將該過濾器內部可能出現的異常全部處理，因為在授權過濾器之前，沒有任何元件能夠捕獲授權過濾器的異常，一旦授權管理器內部發生異常，該異常將直接輸出到結果中
3.2 應用場景
授權管理器 AuthorizeAttribute 位於 名稱空間 Microsoft.AspNetCore.Authorization 內，使用方式非常簡單，檢視以下程式碼
[Authorize]
[Route("api/[controller]")]
public class UserController : Controller
{
[AllowAnonymous]
[HttpGet]
public ActionResult<string> Get()
{
return "default";
}
[HttpPost]
public ActionResult<string> Post()
{
return "default";
}
}UserController 被應用了 Authorize 特性進行標記，表示對該控制器內的任意操作執行授權驗證；但是單獨對 Get 操作進行了授權通過對標記，即 AllowAnonymous ，表示允許匿名訪問
這是非常常用的做法，在授權應用中，常常需要對部分操作進行單獨的授權策略
關於授權過濾器，先介紹到這裡，下一篇單獨對授權過濾器進行演示，因為關於這塊的內容，要講的實在是太多了
4. 資源過濾器
但請求進入，通過授權過濾器後，接下來將執行資源過濾器（如果有定義），使用資源過濾器甚至可以改變繫結模型，還可以在資源過濾器中實現快取以提高效能
4.1 資源管理器實現自介面 IResourceFilter 或者 IAsyncResourceFilter，現在我們來實現一個資源過濾器，輸出一行資訊，看看執行順序
public class CustomerResourceFilter : Attribute, IResourceFilter
{
public void OnResourceExecuted(ResourceExecutedContext context)
{
Console.WriteLine("==== OnResourceExecuted");
}
public void OnResourceExecuting(ResourceExecutingContext context)
{
Console.WriteLine("==== OnResourceExecuting");
}
}4.2 對 HomeController 的操作應用該資源過濾器，看看對一個操作同時應用 CustomerActionFilter 和 CustomerResourceFilter ，他們的執行順序是什麼
[Route("api/[controller]")]
[ApiController]
public class HomeController : ControllerBase
{
[HttpGet]
[CustomerActionFilter]
[CustomerResourceFilter]
public async Task<ActionResult<IEnumerable<string>>> Get()
{
return new string[] { "value1", "value2" };
}
}4.3 啟動程式，訪問 http://localhost:5000/api/home，輸出結果如下
可以看到，執行順序和開篇的第一張圖例一直，首先執行時資源過濾器的 OnResourceExecuting 方法，接著請求接入了 操作過濾器的 OnActionExecuting 方法，最後執行操作過濾器的 OnResultExecuting 方法，然後把請求交給資源過濾器的 OnResourceExecuted，最後返回到客戶端
所以，從執行順序可以看出，資源管理器的執行優先順序總是高於操作過濾器
資源過濾器可以應用於控制器或者操作，然後基於其執行優先順序的特點，開發員人員可以在資源過濾器中定義某些靜態資源或者快取直接將資料返回給客戶端，並使其執行短路操作，減少後續管道請求步驟，以提高伺服器響應效能
5. 異常過濾器
在伺服器向客戶端寫入響應內容之前，如果系統引發了異常，異常過濾器可以捕獲該異常，該過濾器作用於全域性範圍，這也是最常用的過濾器
5.1 建立一個異常過濾器
public class CustomerExceptionFilter : Attribute, IExceptionFilter
{
public void OnException(ExceptionContext context)
{
Console.ForegroundColor = ConsoleColor.Red;
Console.WriteLine("發生了異常：{0}", context.Exception.Message);
Console.ForegroundColor = ConsoleColor.Gray;
}
}5.2 將 CustomerExceptionFilter 應用到 HomeController 上
請注意，HomeController 上還同時應用了資源過濾器；現在要做到就是在資源過濾器內部丟擲異常，看看 CustomerExceptionFilter 是否可以捕獲該異常
public class CustomerResourceFilter : Attribute, IResourceFilter
{
public void OnResourceExecuted(ResourceExecutedContext context)
{
Console.WriteLine("==== OnResourceExecuted");
}
public void OnResourceExecuting(ResourceExecutingContext context)
{
Console.WriteLine("==== OnResourceExecuting");
throw new Exception("資源管理器發生了異常");
}
}5.3 執行程式，訪問 http://localhost:5000/api/home
可以看到，系統丟擲了異常；但是，異常過濾器 CustomerExceptionFilter 並沒有捕獲該異常，事實證明資源過濾器的執行優先順序還是高於異常過濾器，現在我們嘗試在操作內部引發異常
[Route("api/[controller]")]
[ApiController]
[CustomerResourceFilter]
[CustomerExceptionFilter]
public class HomeController : ControllerBase
{
// GET api/values
[HttpGet]
[CustomerActionFilter]
public async Task<ActionResult<IEnumerable<string>>> Get()
{
throw new Exception("Get操作發生了異常");
return new string[] { "value1", "value2" };
}
}5.4 再次啟動程式，訪問 http://localhost:5000/api/home，控制檯輸出結果如下
5.5 客戶端得到了一個友好的返回值
5.6 這是因為我們在異常過濾器內部將異常進行了出來，並通過設定 context.ExceptionHandled = true 來標記表示異常已經被處理，然後輸出友好資訊
public class CustomerExceptionFilter : Attribute, IExceptionFilter
{
public void OnException(ExceptionContext context)
{
Console.ForegroundColor = ConsoleColor.Red;
Console.WriteLine("發生了異常：{0}", context.Exception.Message);
Console.ForegroundColor = ConsoleColor.Gray;
context.Result = new JsonResult(new { code = 500, message = context.Exception.Message });
context.ExceptionHandled = true;
}
}異常過濾器的應用非常簡單，你可以在其內部將異常寫入日誌，或者執行其它需要處理的邏輯
6. 操作過濾器 ActionFilterAttribute 和 結果過濾器 IResultFilter
- 操作過濾器：當請求進入 API 介面的時候，操作過濾器提供了一個進入之前（before）和進入之後（after）介入功能，可以使用該過濾器對進入 API 的引數和結果進行干預
- 結果過濾器：這個過濾器的作用和操作過濾器非常相似，主要其作用範圍是有微小區別的，結果過濾器是在操作即將返回結果到客戶端之前（before）或者之後（after）執行干預，比如你可以在返回結果之後（after）去渲染檢視
6.1 之所以將這兩個過濾器放在一起講，是因為，這兩個過濾器就像一對孿生兄弟一樣，正所謂有始有終，首先來看操作過濾器
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)]
public abstract class ActionFilterAttribute : Attribute, IActionFilter, IFilterMetadata, IAsyncActionFilter, IResultFilter, IAsyncResultFilter, IOrderedFilter
{
protected ActionFilterAttribute();
//
public int Order { get; set; }
//
public virtual void OnActionExecuted(ActionExecutedContext context);
//
public virtual void OnActionExecuting(ActionExecutingContext context);
//
[AsyncStateMachine(typeof(<OnActionExecutionAsync>d__6))]
public virtual Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next);
//
public virtual void OnResultExecuted(ResultExecutedContext context);
//
public virtual void OnResultExecuting(ResultExecutingContext context);
//
[AsyncStateMachine(typeof(<OnResultExecutionAsync>d__9))]
public virtual Task OnResultExecutionAsync(ResultExecutingContext context, ResultExecutionDelegate next);
}
操作過濾器包含 6 個基礎方法，分別是執行前（before）執行後（after），寫入結果前（before）寫入後（after）
為什麼會這樣呢，因為操作過濾器實現的介面中包含了結果過濾器的介面
根據官方的提示，如果你需要重寫 ActionFilterAttribute 的方法以處理自定義的業務邏輯，那麼 OnActionExecutionAsync 這個非同步方法不應該和 執行前（before）執行後（after）同時共存
同樣，寫入結果前（before）寫入後（after）和 OnResultExecutionAsync 也是一樣
6.2 操作過濾器包含了 寫入結果前（before）寫入後（after）的方法，這使得我們可以不用去定義結果過濾器就可以實現對寫入結果的管理
當然，最好的做法是定義結果過濾器，這有助於業務分類，且邏輯清晰明瞭，但是如果你希望可以使用非同步操作，很遺憾，結果過濾器不支援該方法
6.3 下面來看結果過濾的定義
public class CustomerResultFilter : Attribute, IResultFilter
{
public void OnResultExecuted(ResultExecutedContext context)
{
Console.WriteLine("OnResultExecuted");
}
public void OnResultExecuting(ResultExecutingContext context)
{
Console.WriteLine("OnResultExecuting");
}
}程式碼非常簡單，就是實現介面 IResultFilter
IResultFilter 的工作原理和操作過濾器的寫入結果前（before）寫入後（after）的方法執行一致，可以看到，他們兩個方法和引數名稱都是一致的，因為他們都是實現同一個介面 IResultFilter
6.4 利用結果過濾器實現對輸出結果的干預
下面就簡單在結果過濾器內部去對已經組織好的資料進行干預，HomeController.Get 方法本應該輸出 一個數組，我們在Header 中增加一項輸出：Author=From Ron.liang
public class CustomerResultFilter : Attribute, IResultFilter
{
public void OnResultExecuted(ResultExecutedContext context)
{
// ToDo
}
public void OnResultExecuting(ResultExecutingContext context)
{
// 干預結果
context.HttpContext.Response.Headers.Add("Author", "From Ron.liang");
}
}6.5 輸出結果
7.在過濾器中使用依賴注入
在上面介紹的各種各樣的過濾器中，有時候我們可能需要讀取程式執行環境的資訊，根據不同的環境做出不同的響應內容
比如，上面的結果過濾器寫入作者資訊，可能我們只希望在開發環境輸出，而在產品環境忽略
7.1 使用 GetService，以支援依賴注入
public void OnResultExecuting(ResultExecutingContext context)
{
var env = (IHostingEnvironment)context.HttpContext.RequestServices.GetService(typeof(IHostingEnvironment));
Console.ForegroundColor = ConsoleColor.Blue;
Console.WriteLine("OnResultExecuting,{0}", env.EnvironmentName);
Console.ForegroundColor = ConsoleColor.Gray;
// 干預結果
if (env.IsDevelopment())
context.HttpContext.Response.Headers.Add("Author", "From Ron.liang");
}上面的從 context.HttpContext.RequestServices.GetService(typeof(IHostingEnvironment)) 獲取了環境變數，並判斷在開發環境下為響應頭新增內容
7.2 在過濾器中使用中介軟體
Asp.Net Core 提供了一個功能，使得我們在過濾器中可以使用中介軟體，實際上，這兩者的使用方式非常類似
如果你希望這麼做，可以定義一個包含 Configure(IApplicationBuilder applicationBuilder) 方法的類，在控制器或者操作中使用它
7.3 定義註冊管理管道類
public class RegisterManagerPipeline
{
public void Configure(IApplicationBuilder applicationBuilder)
{
CookieAuthenticationOptions options = new CookieAuthenticationOptions();
applicationBuilder.UseCors(config =>
{
config.AllowAnyOrigin();
});
}
}RegisterManagerPipeline 定義了一個 Configure 方法，在該方法內部執行一個跨域設定，表示允許任何來源訪問該站點；然後，我們在 UserController 中應用該管道
[Authorize]
[Route("api/[controller]")]
[MiddlewareFilter(typeof(RegisterManagerPipeline))]
public class UserController : Controller
{
// GET: api/<controller>
[AllowAnonymous]
[HttpGet]
public ActionResult<string> Get()
{
return "default";
}
}應用方式非常簡單，就像使用普通過濾器一樣對控制器進行特性標記即可
所不同的是，這裡使用的是 MiddlewareFilter 進行註冊 RegisterManagerPipeline
管道式過濾器的優先順序非常高，甚至比授權過濾器的優先順序還高，在使用的時候需要特別注意應用場景
8. 過濾器的執行順序
相同型別的過濾器其執行順序可以使用 Order 欄位進行指定，該值為一個 int32 型別，值越小表示優先順序越高，該值只能作用於相同型別的過濾器
比如，定義了兩個 ActionFilter ，UserNameActionFilter,UserAgeActionFilter，分別制定其 Order 欄位值為 10，5，那麼 UserAgeActionFilter 將會在呼叫 ，UserNameActionFilter 之前執行
但是，即使指定了 Order ，ActionFilter 的執行優先順序也不會超越授權管理器 AuthorizeAttribute，這是設計上的不同
8.1 Order 演示程式碼
[HttpPost]
[UserNameActionFilter(Order = 10)]
[UserAgeActionFilter(Order = 5)]
public void Post([FromBody] UserModel value)
{
}8.2 輸出結果
上圖輸出的黃色部分文字清晰的說明了過濾器的執行順序
顯示執行了資源過濾器，接著執行了 Order=5 的 UserAgeActionFilter ，最後執行了 Order=10 的 UserNameActionFilter 過濾器
可以看到，雖然操作過濾器設定了 Order=5，但其執行優先順序仍然不能超越授權過濾器，甚至無法超越資源過濾器
結束語
本文簡單介紹了 Asp.Net Core 下系統內建的各種各樣的過濾器，分別是
- 授權過濾器 AuthorizeAttribute
- 資源過濾器 IResourceFilter
- 異常過濾器 IExceptionFilter
- 操作過濾器 ActionFilterAttribute
- 結果過濾器 IResultFilter
- 還通過一些簡單說例項演示了過濾器的執行過程
最後介紹瞭如何在過濾器中使用中介軟體，以及對過濾器的執行順序進行了詳細的演示