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: //github.com/huiyuanai709/AspNetCore.ResponseWrapper
Nuget Package: //www.nuget.org/packages/AspNetCore.ResponseWrapper
總結
本文介紹了 Asp.Net Core 中的通用響應包裝的實現，以及如何讓 Swagger 識別響應包裝，由於異常處理難以做到通用和一致，本文不處理異常情況下的響應包裝，讀者可以自定義實現 ExceptionFilter。
文章源自公眾號：灰原同學的筆記，轉載請聯繫授權
