asp.net?core?中優(yōu)雅的進(jìn)行響應(yīng)包裝的實(shí)現(xiàn)方法

更新時(shí)間：2022年01月10日 10:21:34 作者：huiyuanai709

本文介紹了 Asp.Net Core 中的通用響應(yīng)包裝的實(shí)現(xiàn)，以及如何讓 Swagger 識(shí)別響應(yīng)包裝，由于異常處理難以做到通用和一致，本文不處理異常情況下的響應(yīng)包裝，讀者可以自定義實(shí)現(xiàn) ExceptionFilter

摘要

在 asp.net core 中提供了 Filter 機(jī)制，可以在 Action 執(zhí)行前后進(jìn)行一些特定的處理，例如模型驗(yàn)證，響應(yīng)包裝等功能就可以在此基礎(chǔ)上實(shí)現(xiàn)，同時(shí)也提供了 ApplicationModel API, 我們可以在此基礎(chǔ)上實(shí)現(xiàn)選擇性的添加 Filter，滿足部分接口需要響應(yīng)特定的結(jié)構(gòu)，我們常見的 [AllowAnonymous] 正是基于這種機(jī)制。同時(shí)也將介紹如何讓 Swagger 展示正確的包裝響應(yīng)體，以滿足第三方對(duì)接或前端的代碼生成

效果圖

正常響應(yīng)包裝

首先我們定義包裝體的接口，這里主要分為正常響應(yīng)和模型驗(yàn)證失敗的響應(yīng)，其中正常響應(yīng)分為有數(shù)據(jù)返回和沒有數(shù)據(jù)返回兩種情況，使用接口的目的是為了方便自定義包裝體。

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

然后根據(jù)接口實(shí)現(xiàn)我們具體的包裝類

沒有數(shù)據(jù)返回的包裝體：

/// <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);
    }
}

有數(shù)據(jù)返回的包裝體：

/// <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);
    }
}

然后實(shí)現(xiàn)我們的響應(yīng)包裝 Filter，這里分為正常響應(yīng)包裝，和模型驗(yàn)證錯(cuò)誤包裝兩類 Filter，在原本的響應(yīng)結(jié)果 context.Result 的基礎(chǔ)上加上我們的包裝體

正常響應(yīng)包裝 Filter，注意處理一下 EmptyResult 的情況，就是常見的返回 Void 或 Task 的場(chǎng)景：

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;
        }
    }
}

模型驗(yàn)證錯(cuò)誤的 Filter，這里我們將 ErrorMessage 提取出來(lái)放在包裝體中，并返回 400 客戶端錯(cuò)誤的狀態(tài)碼

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
            };
        }
    }
    ...
}

這里基本的包裝結(jié)構(gòu)和 Filter 已經(jīng)定義完成，但如何實(shí)現(xiàn)按需添加 Filter，以滿足特定情況下需要返回特定的結(jié)構(gòu)呢？

實(shí)現(xiàn)按需禁用包裝

回想 asp.net core 中的權(quán)限驗(yàn)證，只有添加了 [AllowAnonymous] 的 Controller/Action 才允許匿名訪問(wèn)，其它接口即使不添加 [Authorize] 同樣也會(huì)有基礎(chǔ)的登錄驗(yàn)證，我們這里同樣可以使用這種方法實(shí)現(xiàn)，那么這一功能是如何實(shí)現(xiàn)的呢？

Asp.net core 提供了 ApplicationModel 的 API，會(huì)在程序啟動(dòng)時(shí)掃描所有的 Controller 類，添加到了 ApplicationModelProviderContext 中，并公開了 IApplicationModelProvider 接口，可以選擇性的在 Controller/Action 上添加 Filter，上述功能正是基于該接口實(shí)現(xiàn)的，詳細(xì)代碼見 AuthorizationApplicationModelProvider 類，我們可以參照實(shí)現(xiàn)自定義的響應(yīng)包裝 Provider 實(shí)現(xiàn)在特定的 Controller/Action 禁用包裝，并默認(rèn)給其它接口加上包裝 Filter 的功能。

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

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

自定義 Provider 實(shí)現(xiàn)，這里實(shí)現(xiàn)了選擇性的添加 Filter，以及后文提到的如何讓 Swagger 正確的識(shí)別響應(yīng)包裝（詳細(xì)代碼見 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 識(shí)別正確的響應(yīng)包裝

通過(guò)查閱文檔可以發(fā)現(xiàn)，Swagger 支持在 Action 上添加 [ProducesResponseType] Filter 來(lái)顯示地指定響應(yīng)體類型。我們可以通過(guò)上邊的自定義 Provider 動(dòng)態(tài)的添加該 Filter 來(lái)實(shí)現(xiàn) Swagger 響應(yīng)包裝的識(shí)別。

需要注意這里我們通過(guò) ActionModel 的 ReturnType 來(lái)取得原響應(yīng)類型，并在此基礎(chǔ)上添加到我們的包裝體泛型中，因此我們需要關(guān)于 ReturnType 足夠多的元數(shù)據(jù) (metadata)，因此這里推薦返回具體的結(jié)構(gòu)，而不是 IActionResult，當(dāng)然 Task 這種在這里是支持的。

關(guān)鍵代碼如下：

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

禁用默認(rèn)的模型驗(yàn)證錯(cuò)誤包裝

默認(rèn)的模型驗(yàn)證錯(cuò)誤是如何添加的呢，答案和 [AllowAnonymous] 類似，都是通過(guò) ApplicationModelProvider 添加上去的，詳細(xì)代碼可以查看 ApiBehaviorApplicationModelProvider 類，關(guān)鍵代碼如下：

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

可以看見提供了選項(xiàng)可以阻止默認(rèn)的模型驗(yàn)證錯(cuò)誤慣例，關(guān)閉后我們自定義的模型驗(yàn)證錯(cuò)誤 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;
}

使用方法以及自定義返回結(jié)構(gòu)體

安裝 Nuget 包

dotnet add package AspNetCore.ResponseWrapper --version 1.0.1

使用方法：

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

如何實(shí)現(xiàn)自定義響應(yīng)體呢，首先自定義響應(yīng)包裝類，并實(shí)現(xiàn)上面提到的響應(yīng)包裝接口，并且需要提供無(wú)參的構(gòu)造函數(shù)

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

自定義響應(yīng)體：

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

總結(jié)

本文介紹了 Asp.Net Core 中的通用響應(yīng)包裝的實(shí)現(xiàn)，以及如何讓 Swagger 識(shí)別響應(yīng)包裝，由于異常處理難以做到通用和一致，本文不處理異常情況下的響應(yīng)包裝，讀者可以自定義實(shí)現(xiàn) ExceptionFilter。

到此這篇關(guān)于asp.net core 中優(yōu)雅的進(jìn)行響應(yīng)包裝的文章就介紹到這了,更多相關(guān)asp.net core 響應(yīng)包裝內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: