asp.net core 中優雅的進行響應包裝的實現方法

Posted on by

摘要

在 asp.net core 中提供瞭 Filter 機制，可以在 Action 執行前後進行一些特定的處理，例如模型驗證，響應包裝等功能就可以在此基礎上實現，同時也提供瞭 ApplicationModel API, 我們可以在此基礎上實現選擇性的添加 Filter，滿足部分接口需要響應特定的結構， 我們常見的 [AllowAnonymous] 正是基於這種機制。同時也將介紹如何讓 Swagger 展示正確的包裝響應體，以滿足第三方對接或前端的代碼生成

效果圖

正常響應包裝

首先我們定義包裝體的接口， 這裡主要分為正常響應和模型驗證失敗的響應，其中正常響應分為有數據返回和沒有數據返回兩種情況，使用接口的目的是為瞭方便自定義包裝體。

public interface IResponseWrapper
{
    IResponseWrapper Ok();
    IResponseWrapper ClientError(string message);
}
public interface IResponseWrapper<in TResponse> : IResponseWrapper
{
    IResponseWrapper<TResponse> Ok(TResponse response);
}

然後根據接口實現我們具體的包裝類

沒有數據返回的包裝體：

/// <summary>
/// Default wrapper for <see cref="EmptyResult"/> or error occured
/// </summary>
public class ResponseWrapper : IResponseWrapper
{
    public int Code { get; }
    public string? Message { get; }
    ...
    public IResponseWrapper Ok()
    {
        return new ResponseWrapper(ResponseWrapperDefaults.OkCode, null);
    }
    public IResponseWrapper BusinessError(string message)
    {
        return new ResponseWrapper(ResponseWrapperDefaults.BusinessErrorCode, message);
    }
    public IResponseWrapper ClientError(string message)
    {
        return new ResponseWrapper(ResponseWrapperDefaults.ClientErrorCode, message);
    }
}

有數據返回的包裝體：

/// <summary>
/// Default wrapper for <see cref="ObjectResult"/>
/// </summary>
/// <typeparam name="TResponse"></typeparam>
public class ResponseWrapper<TResponse> : ResponseWrapper, IResponseWrapper<TResponse>
{
    public TResponse? Data { get; }
    public ResponseWrapper()
    {
    }
    private ResponseWrapper(int code, string? message, TResponse? data) : base(code, message)
    {
        Data = data;
    }
    public IResponseWrapper<TResponse> Ok(TResponse response)
    {
        return new ResponseWrapper<TResponse>(ResponseWrapperDefaults.OkCode, null, response);
    }
}

然後實現我們的響應包裝 Filter，這裡分為正常響應包裝，和模型驗證錯誤包裝兩類 Filter，在原本的響應結果 context.Result 的基礎上加上我們的包裝體

正常響應包裝 Filter， 註意處理一下 EmptyResult 的情況，就是常見的返回 Void 或 Task 的場景：

public class ResultWrapperFilter : IResultWrapperFilter
{
    private readonly IResponseWrapper _responseWrapper;
    private readonly IResponseWrapper<object?> _responseWithDataWrapper;
    ...
    public void OnActionExecuted(ActionExecutedContext context)
    {
        switch (context.Result)
        {
            case EmptyResult:
                context.Result = new OkObjectResult(_responseWrapper.Ok());
                return;
            case ObjectResult objectResult:
                context.Result = new OkObjectResult(_responseWithDataWrapper.Ok(objectResult.Value));
                return;
        }
    }
}

模型驗證錯誤的 Filter，這裡我們將 ErrorMessage 提取出來放在包裝體中， 並返回 400 客戶端錯誤的狀態碼

public class ModelInvalidWrapperFilter : IActionFilter
{
    private readonly IResponseWrapper _responseWrapper;
    private readonly ILogger<ModelInvalidWrapperFilter> _logger;
    ...
    public void OnActionExecuting(ActionExecutingContext context)
    {
        if (context.Result == null && !context.ModelState.IsValid)
        {
            ModelStateInvalidFilterExecuting(_logger, null);
            context.Result = new ObjectResult(_responseWrapper.ClientError(string.Join(",",
                context.ModelState.Values.SelectMany(v => v.Errors).Select(e => e.ErrorMessage))))
            {
                StatusCode = StatusCodes.Status400BadRequest
            };
        }
    }
    ...
}

這裡基本的包裝結構和 Filter 已經定義完成，但如何實現按需添加 Filter，以滿足特定情況下需要返回特定的結構呢？

實現按需禁用包裝

回想 asp.net core 中的 權限驗證，隻有添加瞭 [AllowAnonymous] 的 Controller/Action 才允許匿名訪問，其它接口即使不添加 [Authorize] 同樣也會有基礎的登錄驗證，我們這裡同樣可以使用這種方法實現，那麼這一功能是如何實現的呢？

Asp.net core 提供瞭 ApplicationModel 的 API，會在程序啟動時掃描所有的 Controller 類，添加到瞭 ApplicationModelProviderContext 中，並公開瞭 IApplicationModelProvider 接口，可以選擇性的在 Controller/Action 上添加 Filter，上述功能正是基於該接口實現的，詳細代碼見 AuthorizationApplicationModelProvider 類，我們可以參照實現自定義的響應包裝 Provider 實現在特定的 Controller/Action 禁用包裝，並默認給其它接口加上包裝 Filter 的功能。

定義禁止包裝的接口及 Attribute：

public interface IDisableWrapperMetadata
{
}
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
public class DisableWrapperAttribute : Attribute, IDisableWrapperMetadata
{
}

自定義 Provider 實現，這裡實現瞭選擇性的添加 Filter，以及後文提到的如何讓 Swagger 正確的識別響應包裝（詳細代碼見 Github）

public class ResponseWrapperApplicationModelProvider : IApplicationModelProvider
{
    ...
    public void OnProvidersExecuting(ApplicationModelProviderContext context)
    {
        if (context is null)
        {
            throw new ArgumentNullException(nameof(context));
        }
        foreach (var controllerModel in context.Result.Controllers)
        {
            if (_onlyAvailableInApiController && IsApiController(controllerModel))
            {
                continue;
            }
        
            if (controllerModel.Attributes.OfType<IDisableWrapperMetadata>().Any())
            {
                if (!_suppressModelInvalidWrapper)
                {
                    foreach (var actionModel in controllerModel.Actions)
                    {
                        actionModel.Filters.Add(new ModelInvalidWrapperFilter(_responseWrapper, _loggerFactory));
                    }
                }
                continue;
            }
            foreach (var actionModel in controllerModel.Actions)
            {
                if (!_suppressModelInvalidWrapper)
                {
                    actionModel.Filters.Add(new ModelInvalidWrapperFilter(_responseWrapper, _loggerFactory));
                }
                if (actionModel.Attributes.OfType<IDisableWrapperMetadata>().Any()) continue;
                actionModel.Filters.Add(new ResultWrapperFilter(_responseWrapper, _genericResponseWrapper));
                // support swagger
                AddResponseWrapperFilter(actionModel);
            }
        }
    }
    ...
}

如何讓 Swagger 識別正確的響應包裝

通過查閱文檔可以發現，Swagger 支持在 Action 上添加 [ProducesResponseType] Filter 來顯示地指定響應體類型。 我們可以通過上邊的自定義 Provider 動態的添加該 Filter 來實現 Swagger 響應包裝的識別。

需要註意這裡我們通過 ActionModel 的 ReturnType 來取得原響應類型，並在此基礎上添加到我們的包裝體泛型中，因此我們需要關於 ReturnType 足夠多的元數據 (metadata)，因此這裡推薦返回具體的結構，而不是 IActionResult，當然 Task 這種在這裡是支持的。

關鍵代碼如下：

actionModel.Filters.Add(new ProducesResponseTypeAttribute(_genericWrapperType.MakeGenericType(type), statusCode));

禁用默認的模型驗證錯誤包裝

默認的模型驗證錯誤是如何添加的呢，答案和 [AllowAnonymous] 類似，都是通過 ApplicationModelProvider 添加上去的，詳細代碼可以查看 ApiBehaviorApplicationModelProvider 類，關鍵代碼如下：

if (!options.SuppressModelStateInvalidFilter)
{
    ActionModelConventions.Add(new InvalidModelStateFilterConvention());
}

可以看見提供瞭選項可以阻止默認的模型驗證錯誤慣例，關閉後我們自定義的模型驗證錯誤 Filter 就能生效

public static IMvcBuilder AddResponseWrapper(this IMvcBuilder mvcBuilder, Action<ResponseWrapperOptions> action)
{
    mvcBuilder.Services.Configure(action);
    mvcBuilder.ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressModelStateInvalidFilter = true;
    });
    mvcBuilder.Services.TryAddEnumerable(ServiceDescriptor.Transient<IApplicationModelProvider, ResponseWrapperApplicationModelProvider>());
    return mvcBuilder;
}

使用方法以及自定義返回結構體

安裝 Nuget 包

dotnet add package AspNetCore.ResponseWrapper --version 1.0.1

使用方法：

// .Net5
services.AddApiControllers().AddResponseWrapper();
// .Net6
builder.Services.AddControllers().AddResponseWrapper();

如何實現自定義響應體呢，首先自定義響應包裝類，並實現上面提到的響應包裝接口，並且需要提供無參的構造函數

示例代碼: https://github.com/huiyuanai709/AspNetCore.ResponseWrapper/tree/main/samples/CustomResponseWrapper/ResponseWrapper

自定義響應體：

public class CustomResponseWrapper : IResponseWrapper
{
    public bool Success => Code == 0;
    public int Code { get; set; }
    public string? Message { get; set; }
    public CustomResponseWrapper()
    {
    }
    public CustomResponseWrapper(int code, string? message)
    {
        Code = code;
        Message = message;
    }
    public IResponseWrapper Ok()
    {
        return new CustomResponseWrapper(0, null);
    }
    public IResponseWrapper BusinessError(string message)
    {
        return new CustomResponseWrapper(1, message);
    }
    public IResponseWrapper ClientError(string message)
    {
        return new CustomResponseWrapper(400, message);
    }
}
public class CustomResponseWrapper<TResponse> : CustomResponseWrapper, IResponseWrapper<TResponse>
{
    public TResponse? Result { get; set; }
    public CustomResponseWrapper()
    {
    }
    
    public CustomResponseWrapper(int code, string? message, TResponse? result) : base(code, message)
    {
        Result = result;
    }
    public IResponseWrapper<TResponse> Ok(TResponse response)
    {
        return new CustomResponseWrapper<TResponse>(0, null, response);
    }
}

使用方法， 這裡以 .Net 6 為例， .Net5 也是類似的

// .Net6
builder.Services.AddControllers().AddResponseWrapper(options =>
{
    options.ResponseWrapper = new CustomResponseWrapper.ResponseWrapper.CustomResponseWrapper();
    options.GenericResponseWrapper = new CustomResponseWrapper<object?>();
});

SourceCode && Nuget package

SourceCode: https://github.com/huiyuanai709/AspNetCore.ResponseWrapper

Nuget Package: https://www.nuget.org/packages/AspNetCore.ResponseWrapper

總結

本文介紹瞭 Asp.Net Core 中的通用響應包裝的實現，以及如何讓 Swagger 識別響應包裝，由於異常處理難以做到通用和一致，本文不處理異常情況下的響應包裝，讀者可以自定義實現 ExceptionFilter。

到此這篇關於asp.net core 中優雅的進行響應包裝的文章就介紹到這瞭,更多相關asp.net core 響應包裝內容請搜索WalkonNet以前的文章或繼續瀏覽下面的相關文章希望大傢以後多多支持WalkonNet！

推薦閱讀：