asp.net core 中优雅的进行响应包装
目录
- 摘要
- 正常响应/模型验证错误包装
- 实现按需禁用包装
- 如何让 Swagger 识别正确的响应包装
- 禁用默认的模型验证错误包装
- 使用方法以及自定义返回结构体
- SourceCode && Nuget package
- 总结
摘要
在 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();
如何实现自定义响应体呢，首先自定义响应包装类，并实现上面提到的响应包装接口，并且需要提供无参的构造函数
自定义响应体：
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。
文章源自公众号：灰原同学的笔记，转载请联系授权
