利用過濾器Filter和特性Attribute實現對Web API返回結果的封裝和統一異常處理

在我們開發Web API應用的時候，我們可以借鑒ABP框架的過濾器Filter和特性Attribute的應用，實現對Web API返回結果的封裝和統一異常處理，本篇隨筆介紹利用AuthorizeAttribute實現Web API身份認證，利用ActionFilterAttribute實現對常規Web API返回結果進行統一格式的封裝，利用ExceptionFilterAttribute實現對接口異常的統一處理，實現我們Web API常用到的幾個通用處理過程。

1、Asp.net的Web API過濾器介紹

過濾器主要有這么幾種：AuthorizationFilterAttribute 權限驗證、ActionFilterAttribute 日志參數驗證等、ExceptionFilterAttribute 異常處理捕獲。

ActionFilter 主要實現執行請求方法體之前（覆蓋基類方法OnActionExecuting），和之后的事件處理（覆蓋基類方法OnActionExecuted）；ExceptionFilter主要實現觸發異常方法（覆蓋基類方法OnException）。

ActionFilterAttrubute提供了兩個方法進行攔截：

• OnActionExecuting和OnActionExecuted，他們都提供了同步和異步的方法。
• OnActionExecuting方法在Action執行之前執行，OnActionExecuted方法在Action執行完成之后執行。

在使用MVC的時候，ActionFilter提供了一個Order屬性，用戶可以根據這個屬性控制Filter的調用順序，而Web API卻不再支持該屬性。Web API的Filter有自己的一套調用順序規則：

所有Filter根據注冊位置的不同擁有三種作用域：Global、Controller、Action：

• 通過HttpConfiguration類實例下Filters.Add()方法注冊的Filter（一般在App_Start\WebApiConfig.cs文件中的Register方法中設置）就屬於Global作用域；

• 通過Controller上打的Attribute進行注冊的Filter就屬於Controller作用域；

• 通過Action上打的Attribute進行注冊的Filter就屬於Action作用域；

他們遵循了以下規則：

• 在同一作用域下，AuthorizationFilter最先執行，之后執行ActionFilter
• 對於AuthorizationFilter和ActionFilter.OnActionExcuting來說，如果一個請求的生命周期中有多個Filter的話，執行順序都是Global->Controller->Action；
• 對於ActionFilter，OnActionExecuting總是先於OnActionExecuted執行；
• 對於ExceptionFilter和ActionFilter.OnActionExcuted而言執行順序為Action->Controller->Global；
• 對於所有Filter來說，如果阻止了請求:即對Response進行了賦值，則后續的Filter不再執行。

另外，值得注意的是，由於Web API的過濾器無法改變其順序，那么它是按照 AuthorizationFilterAttribute -> ActionFilterAttribute -> ExceptionFilterAttribute 這個執行順序來處理的，也就是說授權過濾器執行在前面，再次到自定義的ActionFilter，最后才是異常的過濾器處理。

 

2、Web API的身份授權過濾器處理

我們通過AuthorizationFilterAttribute 過濾器來處理用戶Web API接口身份，比每次在代碼上進行驗證省事很多。

一般情況下，我們只要定義類繼承於AuthorizeAttribute即可，由於AuthorizeAttribute是繼承於AuthorizationFilterAttribute，如下所示。

    /// <summary>
    /// 驗證Web Api接口用戶身份
    /// </summary>
    public class ApiAuthorizeAttribute : AuthorizeAttribute
    {
            ...........
     }

 而一般情況下，我們只需要重寫bool IsAuthorized(HttpActionContext actionContext) 方法，實現授權處理邏輯即可。

 我們在CheckToken的主要邏輯里面，主要對token令牌進行反向解析，並判斷用戶身份是否符合，如果不符合拋出異常，就會切換到異常處理器里面了。

  然后在Web API控制器中，需要授權訪問的Api控制器定義即可，我們可以把它放到基類里面聲明這個過濾器特性。

 那么所有Api接口的訪問，都會檢查用戶的身份了。

 

2、自定義過濾器特性ActionFilterAttribute 的處理

這個ActionFilterAttribute 主要用於攔截用戶訪問控制器方法的處理過程，前面說到，OnActionExecuting方法在Action執行之前執行，OnActionExecuted方法在Action執行完成之后執行。

那么我們可以利用它進行函數AOP的處理了，也就是在執行前，執行后進行日志記錄等，還有就是常規的參數檢查、結果封裝等，都可以在這個自定義過濾器中實現。

我們定義一個類WrapResultAttribute來標記封裝結果，定義一個類DontWrapResultAttribute來標記不封裝結果。

    /// <summary>
    /// 用於判斷Web API需要包裝返回結果.
    /// </summary>
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface | AttributeTargets.Method)]
    public class WrapResultAttribute : ActionFilterAttribute
{

}

    /// <summary>
    /// 用於判斷Web API不需要包裝返回結果.
    /// </summary>
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface | AttributeTargets.Method)]
    public class DontWrapResultAttribute : WrapResultAttribute
{

}

這個處理方式是借用ABP框架中這兩個特性的處理邏輯。

利用，對於獲取用戶身份令牌的基礎操作接口，我們可以不封裝返回結果，如下標記所示。

  那么執行后，返回的結果如下所示，就是正常的TokenResult對象的JSON信息

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIxIiwiaWF0IjoxNjE3MjY0MDQ4LCJqdGkiOiI0NTBjZmY3OC01OTEwLTQwYzUtYmJjMC01OTQ0YzNjMjhjNTUiLCJuYW1lIjoiYWRtaW4iLCJjb3JwaWQiOiI2IiwiY2hhbm5lbCI6IjAiLCJzaGFyZWRrZXkiOiIxMjM0YWJjZCJ9.Umv4j80Sj6BnoCCGO5LrnyddwtfqU5a8Jii92SjPApw",
    "expires_in": 604800
}

如果取消這個DontWrapResult的標記，那么它就繼承基類BaseApiController的WrapResult的標記定義了。

    /// <summary>
    /// 所有接口基類
    /// </summary>
    [ExceptionHandling]
    [WrapResult]
    public class BaseApiController : ApiController

那么接口定義不變，但是返回的okenResult對象的JSON信息已經經過包裝了。

{
    "result": {
        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIxIiwiaWF0IjoxNjE3MjY0NDQ5LCJqdGkiOiJmZTAzYzhlNi03NGVjLTRjNmEtYmMyZi01NTU3MjFiOTM1NDEiLCJuYW1lIjoiYWRtaW4iLCJjb3JwaWQiOiI2IiwiY2hhbm5lbCI6IjAiLCJzaGFyZWRrZXkiOiIxMjM0YWJjZCJ9.9B4dyoE9YTisl36A-w_evLs2o8raopwvDUIr2LxhO1c",
        "expires_in": 604800
    },
    "targetUrl": null,
    "success": true,
    "error": null,
    "unAuthorizedRequest": false,
    "__api": true
}

這個JSON格式是我們一個通用的接口返回，其中Result里面定義了返回的信息，而Error里面則定義一些錯誤信息（如果有錯誤的話），而success則用於判斷是否執行成功，如果有錯誤異常信息，那么success返回為false。

這個通用返回的定義，是依照ABP框架的返回格式進行調整的，可以作為我們普通Web API的一個通用返回結果的處理。

前面提到過ActionFilterAttribute自定義處理過程，在控制器方法完成后，我們對返回的結果進行進一步的封裝處理即可。

我們需要重寫邏輯實現OnActionExecuted的函數

 在做包裝返回結果之前，我們需要判斷是否方法或者控制器設置了不包裝的標記DontWrapResultAttribute。

        public override void OnActionExecuted(HttpActionExecutedContext actionExecutedContext)
        {
            //如果有異常，則退出交給Exception的通用處理
            if (actionExecutedContext.Exception != null)
                return;

            //正常完成，那么判斷是否需要包裝結果輸出，如果不需要則返回
            var dontWrap = false;
            var actionContext = actionExecutedContext.ActionContext;
            if (actionContext.ActionDescriptor is ReflectedHttpActionDescriptor actionDesc)
            {
                //判斷方法是否包含DontWrapResultAttribute
                dontWrap = actionDesc.MethodInfo.GetCustomAttributes(inherit: false)
                    .Any(a => a.GetType().Equals(typeof(DontWrapResultAttribute)));

                if (dontWrap) return;
            }
            if (actionContext.ControllerContext.ControllerDescriptor is HttpControllerDescriptor controllerDesc)
            {
                //判斷控制器是否包含DontWrapResultAttribute
                dontWrap = controllerDesc.GetCustomAttributes<Attribute>(inherit: true)
                  .Any(a => a.GetType().Equals(typeof(DontWrapResultAttribute)));

                if (dontWrap) return;
            }

上述代碼也就是如果找到方法或者控制器有定義DontWrapResultAttribute的，就不要包裝結果，否則下一步就是對結果進行封裝了

            //需要包裝，那么就包裝輸出結果
            AjaxResponse result = new AjaxResponse();
            // 狀態代碼
            var statusCode = actionContext.Response.StatusCode;
            // 讀取返回的內容
            var content = actionContext.Response.Content.ReadAsAsync<object>().Result;
            // 請求是否成功
            result.Success = actionContext.Response.IsSuccessStatusCode;

            // 重新封裝回傳格式
            actionExecutedContext.Response = new HttpResponseMessage(statusCode)
            {
                Content = new ObjectContent<AjaxResponse>(
                   new AjaxResponse(content), JsonFomatterHelper.GetFormatter())
            };

其中AjaxResponse是參考ABP框架里面返回結果的類定義處理的。

    public abstract class AjaxResponseBase
    {
        public string TargetUrl { get; set; }

        public bool Success { get; set; }

        public ErrorInfo Error { get; set; }

        public bool UnAuthorizedRequest { get; set; }

        public bool __api { get; } = true;
    }

    [Serializable]
    public class AjaxResponse<TResult> : AjaxResponseBase
    {
        public TResult Result { get; set; }

      }

 

 3、異常處理過濾器ExceptionFilterAttribute 

 前面介紹到，Web API的過濾器無法改變其順序，它是按照 AuthorizationFilterAttribute -> ActionFilterAttribute -> ExceptionFilterAttribute 這個執行順序來處理的，也就是說授權過濾器執行在前面，再次到自定義的ActionFilter，最后才是異常的過濾器處理。

異常處理過濾器，我們定義后，可以統一處理和封裝異常信息，而我們只需要實現OnException的方法即可。

    /// <summary>
    /// 自定義異常處理
    /// </summary>
    public class ExceptionHandlingAttribute : ExceptionFilterAttribute
    {
        /// <summary>
        /// 統一對調用異常信息進行處理，返回自定義的異常信息
        /// </summary>
        /// <param name="context">HTTP上下文對象</param>
        public override void OnException(HttpActionExecutedContext context)
        {
        }
    }

完整的處理過程代碼如下所示。

    /// <summary>
    /// 自定義異常處理
    /// </summary>
    public class ExceptionHandlingAttribute : ExceptionFilterAttribute
    {
        /// <summary>
        /// 統一對調用異常信息進行處理，返回自定義的異常信息
        /// </summary>
        /// <param name="context">HTTP上下文對象</param>
        public override void OnException(HttpActionExecutedContext context)
        {
            //獲取方法或控制器對應的WrapResultAttribute屬性
            var actionDescriptor = context.ActionContext.ActionDescriptor;
            var wrapResult = actionDescriptor.GetCustomAttributes<WrapResultAttribute>(inherit: true).FirstOrDefault()
                ?? actionDescriptor.ControllerDescriptor.GetCustomAttributes<WrapResultAttribute>(inherit: true).FirstOrDefault();

            //如設置，記錄異常信息
            if (wrapResult != null && wrapResult.LogError)
            {
                LogHelper.Error(context.Exception);
            }

            var statusCode = GetStatusCode(context, wrapResult.WrapOnError);
            if (!wrapResult.WrapOnError)
            {
                context.Response = new HttpResponseMessage(statusCode) { 
                    Content = new StringContent(context.Exception.Message.ToJson())
                };
                context.Exception = null; //Handled!
                return;
            }

            //使用AjaxResponse包裝結果
            var content = new ErrorInfo(context.Exception.Message/*, context.Exception.StackTrace*/);
            var isAuth = context.Exception is AuthorizationException;
            context.Response = new HttpResponseMessage(statusCode)
            {
                Content = new ObjectContent<AjaxResponse>(
                   new AjaxResponse(content, isAuth), JsonFomatterHelper.GetFormatter())
            };
            context.Exception = null; //Handled!
        }

這樣我們在BaseApiController里面聲明即可。

  這樣，一旦程序處理過程中，有錯誤拋出，都會統一到這里進行處理，有異常的返回JSON如下所示。

  

本篇隨筆介紹利用AuthorizeAttribute實現Web API身份認證，利用ActionFilterAttribute實現對常規Web API返回結果進行統一格式的封裝，利用ExceptionFilterAttribute實現對接口異常的統一處理，實現我們Web API常用到的幾個通用處理過程。