asp.net core 中优雅的进行响应包装的实现方法

目录

摘要

在 asp.net core 中提供了 Filter 机制，可以在 Action 执行前后进行一些特定的处理，例如模型验证，响应包装等功能就可以在此基础上实现，同时也提供了 ApplicationModel API, 我们可以在此基础上实现选择性的添加 Filter，满足部分接口需要响应特定的结构， 我们常见的 [AllowAnonymous] 正是基于这种机制。同时也将介绍如何让 Swagger 展示正确的包装响应体，以满足第三方对接或前端的代码生成

效果图

wagger 正确的识别响应包装（详细代码见 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

使用方法：

// .Net5services.AddApiControllers().AddResponseWrapper();// .Net6builder.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 也是类似的

// .Net6builder.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。