asp.net core 中优雅的进行响应包装

目录

  • 摘要
  • 正常响应/模型验证错误包装
  • 实现按需禁用包装
  • 如何让 Swagger 识别正确的响应包装
  • 禁用默认的模型验证错误包装
  • 使用方法以及自定义返回结构体
  • SourceCode && Nuget package
  • 总结

摘要

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

效果图
asp.net core 中优雅的进行响应包装
asp.net core 中优雅的进行响应包装

正常响应包装

首先我们定义包装体的接口, 这里主要分为正常响应和模型验证失败的响应,其中正常响应分为有数据返回和没有数据返回两种情况,使用接口的目的是为了方便自定义包装体。

public interface IResponseWrapper
{
    IResponseWrapper Ok();
    IResponseWrapper ClientError(string message);
}

public interface IResponseWrapper : IResponseWrapper
{
    IResponseWrapper Ok(TResponse response);
}

然后根据接口实现我们具体的包装类

没有数据返回的包装体:

/// 
/// Default wrapper for  or error occured
/// 
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);
    }
}

有数据返回的包装体:

/// 
/// Default wrapper for 
/// 
/// 
public class ResponseWrapper : ResponseWrapper, IResponseWrapper
{
    public TResponse? Data { get; }

    public ResponseWrapper()
    {
    }

    private ResponseWrapper(int code, string? message, TResponse? data) : base(code, message)
    {
        Data = data;
    }

    public IResponseWrapper Ok(TResponse response)
    {
        return new ResponseWrapper(ResponseWrapperDefaults.OkCode, null, response);
    }
}

然后实现我们的响应包装 Filter,这里分为正常响应包装,和模型验证错误包装两类 Filter,在原本的响应结果 context.Result 的基础上加上我们的包装体

正常响应包装 Filter, 注意处理一下 EmptyResult 的情况,就是常见的返回 Void 或 Task 的场景:

public class ResultWrapperFilter : IResultWrapperFilter
{
    private readonly IResponseWrapper _responseWrapper;
    private readonly IResponseWrapper _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 _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().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().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 action)
{
    mvcBuilder.Services.Configure(action);
    mvcBuilder.ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressModelStateInvalidFilter = true;
    });
    mvcBuilder.Services.TryAddEnumerable(ServiceDescriptor.Transient());
    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 : CustomResponseWrapper, IResponseWrapper
{
    public TResponse? Result { get; set; }

    public CustomResponseWrapper()
    {
    }
    
    public CustomResponseWrapper(int code, string? message, TResponse? result) : base(code, message)
    {
        Result = result;
    }

    public IResponseWrapper Ok(TResponse response)
    {
        return new CustomResponseWrapper(0, null, response);
    }
}

使用方法, 这里以 .Net 6 为例, .Net5 也是类似的

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

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 中优雅的进行响应包装


技术交流Q群: 1012481075 群内有各种流行书籍资料
原文链接:https://www.cnblogs.com/huiyuanai709/p/aspnetcore-response-wrapper.html

发表评论

您的电子邮箱地址不会被公开。

WeChat
WeChat
QQ
QQ
返回顶部