PM> Install-Package VMD.RESTApiResponseWrapper.Core -Version 1.0.3

安装之后，可以按照以下步骤开始将包装器集成到ASP.NET Core项目中：

using VMD.RESTApiResponseWrapper.Core.Extensions;

app.UseAPIResponseWrapperMiddleware();

注意：确保在“MVC中间件”之前注册它。

PM> Install-Package VMD.RESTApiResponseWrapper.Net -Version 1.0.3

安装之后，可以按照以下步骤开始将包装器集成到ASP.NET Web API项目中：

using VMD.RESTApiResponseWrapper.Net;
using VMD.RESTApiResponseWrapper.Net.Filters;

config.Filters.Add(new ApiExceptionFilter());
config.MessageHandlers.Add(new WrappingHandler());

{"Version": "1.0.0.0","StatusCode": 200,"Message": "Request successful.","Result": ["value1","value2"]
}

没有数据的成功响应格式：

{"Version": "1.0.0.0","StatusCode": 201,"Message": "Student with ID 6 has been created."
}

验证错误的响应格式：

{"Version": "1.0.0.0","StatusCode": 400,"Message": "Request responded with exceptions.","ResponseException": {"IsError": true,"ExceptionMessage": "Validation Field Error.","Details": null,"ReferenceErrorCode": null,"ReferenceDocumentLink": null,"ValidationErrors": [{"Field": "LastName","Message": "'Last Name' should not be empty."},{"Field": "FirstName","Message": "'First Name' should not be empty."}]}
}

错误的响应格式：

{"Version": "1.0.0.0","StatusCode": 404,"Message": "Unable to process the request.","ResponseException": {"IsError": true,"ExceptionMessage": "The specified URI does not exist. Please verify and try again.","Details": null,"ReferenceErrorCode": null,"ReferenceDocumentLink": null,"ValidationErrors": null}
}

定义自定义异常

throw new ApiException("Your Message",401, ModelStateExtension.AllErrors(ModelState));

该ApiException有可以设置以下参数：

ApiException(string message,int statusCode = 500,IEnumerable<ValidationError> errors = null,string errorCode = "",string refLink = "")

定义自己的响应对象

return new APIResponse(201,"Created");

该APIResponse有可以设置以下参数：

APIResponse(int statusCode,string message = "",object result = null,ApiError apiError = null,string apiVersion = "1.0.0.0")

包源代码

public class ValidationError
{[JsonProperty(NullValueHandling = NullValueHandling.Ignore)]public string Field { get; }public string Message { get; }public ValidationError(string field, string message){Field = field != string.Empty ? field : null;Message = message;}
}

ValidationError类包含一些用于存储字段及其相应消息的属性。注意[JsonProperty(NullValueHandling=NullValueHandling.Ignore)]特性上的Field属性。这是为了确保在有null值的情况下不会对该字段进行序列化。

public class ApiError
{public bool IsError { get; set; }public string ExceptionMessage { get; set; }public string Details { get; set; }public string ReferenceErrorCode { get; set; }public string ReferenceDocumentLink { get; set; }public IEnumerable<ValidationError> ValidationErrors { get; set; }public ApiError(string message){this.ExceptionMessage = message;this.IsError = true;}public ApiError(ModelStateDictionary modelState){this.IsError = true;if (modelState != null && modelState.Any(m => m.Value.Errors.Count > 0)){this.ExceptionMessage = "Please correct the specified validation errors and try again.";this.ValidationErrors = modelState.Keys.SelectMany(key => modelState[key].Errors.Select(x => new ValidationError(key, x.ErrorMessage))).ToList();}}
}

ApiError类是一种自定义序列化类型，用于通过JSON将错误信息返回给使用者。此类包含一些重要的特性，以提供有意义的信息给消费者，如ExceptionMessage，Details，ReferenceErrorCode，ReferenceDocumentLink和ValidationErrors。该类还具有一个重载构造函数，以传入ModelStateDictionary以将验证错误列表返回给使用者。

public class ApiException : System.Exception
{public int StatusCode { get; set; }public IEnumerable<ValidationError> Errors { get; set; }public string ReferenceErrorCode { get; set; }public string ReferenceDocumentLink { get; set; }public ApiException(string message,int statusCode = 500,IEnumerable<ValidationError> errors = null,string errorCode = "",string refLink = "") :base(message){this.StatusCode = statusCode;this.Errors = errors;this.ReferenceErrorCode = errorCode;this.ReferenceDocumentLink = refLink;}public ApiException(System.Exception ex, int statusCode = 500) : base(ex.Message){StatusCode = statusCode;}
}

ApiException类是用于抛出显示的和应用产生的错误的自定义异常。这些通常用于验证错误或可能具有已知负面响应（例如，失败的登录尝试）的常见操作。目的是返回明确定义的错误消息，以供使用者安全使用。

[DataContract]
public class APIResponse
{[DataMember]public string Version { get; set; }[DataMember]public int StatusCode { get; set; }[DataMember]public string Message { get; set; }[DataMember(EmitDefaultValue = false)]public ApiError ResponseException { get; set; }[DataMember(EmitDefaultValue = false)]public object Result { get; set; }public APIResponse(int statusCode, string message = "", object result = null, ApiError apiError = null, string apiVersion = "1.0.0.0"){this.StatusCode = statusCode;this.Message = message;this.Result = result;this.ResponseException = apiError;this.Version = apiVersion;}
}

APIResponse类是被用于为所有的API响应提供一致的数据结构的自定义包装响应对象。这包含了一些基本特性，例如Version、StatusCode、Message、ResponseException和Result。我们使用DataContract属性来定义要返回的属性，例如，ResponseException和Result属性不会返回，如果值为null。

public enum ResponseMessageEnum
{[Description("Request successful.")]Success,[Description("Request responded with exceptions.")]Exception,[Description("Request denied.")]UnAuthorized,[Description("Request responded with validation error(s).")]ValidationError,[Description("Unable to process the request.")]Failure
}

ResponseMessageEnum提供了枚举，用于响应描述，例如Success，Exception，UnAuthorize和ValidationError。

public class APIResponseMiddleware
{private readonly RequestDelegate _next;public APIResponseMiddleware(RequestDelegate next){_next = next;}public async Task Invoke(HttpContext context){if (IsSwagger(context))await this._next(context);else{var originalBodyStream = context.Response.Body;using (var responseBody = new MemoryStream()){context.Response.Body = responseBody;try{await _next.Invoke(context);if (context.Response.StatusCode == (int)HttpStatusCode.OK){var body = await FormatResponse(context.Response);await HandleSuccessRequestAsync(context, body, context.Response.StatusCode);}else{await HandleNotSuccessRequestAsync(context, context.Response.StatusCode);}}catch (System.Exception ex){await HandleExceptionAsync(context, ex);}finally{responseBody.Seek(0, SeekOrigin.Begin);await responseBody.CopyToAsync(originalBodyStream);}}}}private static Task HandleExceptionAsync(HttpContext context, System.Exception exception){ApiError apiError = null;APIResponse apiResponse = null;int code = 0;if (exception is ApiException){var ex = exception as ApiException;apiError = new ApiError(ex.Message);apiError.ValidationErrors = ex.Errors;apiError.ReferenceErrorCode = ex.ReferenceErrorCode;apiError.ReferenceDocumentLink = ex.ReferenceDocumentLink;code = ex.StatusCode;context.Response.StatusCode = code;}else if (exception is UnauthorizedAccessException){apiError = new ApiError("Unauthorized Access");code = (int)HttpStatusCode.Unauthorized;context.Response.StatusCode = code;}else{
#if !DEBUGvar msg = "An unhandled error occurred.";string stack = null;
#elsevar msg = exception.GetBaseException().Message;string stack = exception.StackTrace;
#endifapiError = new ApiError(msg);apiError.Details = stack;code = (int)HttpStatusCode.InternalServerError;context.Response.StatusCode = code;}context.Response.ContentType = "application/json";apiResponse = new APIResponse(code, ResponseMessageEnum.Exception.GetDescription(), null, apiError);var json = JsonConvert.SerializeObject(apiResponse);return context.Response.WriteAsync(json);}private static Task HandleNotSuccessRequestAsync(HttpContext context, int code){context.Response.ContentType = "application/json";ApiError apiError = null;APIResponse apiResponse = null;if (code == (int)HttpStatusCode.NotFound)apiError = new ApiError("The specified URI does not exist. Please verify and try again.");else if (code == (int)HttpStatusCode.NoContent)apiError = new ApiError("The specified URI does not contain any content.");elseapiError = new ApiError("Your request cannot be processed. Please contact a support.");apiResponse = new APIResponse(code, ResponseMessageEnum.Failure.GetDescription(), null, apiError);context.Response.StatusCode = code;var json = JsonConvert.SerializeObject(apiResponse);return context.Response.WriteAsync(json);}private static Task HandleSuccessRequestAsync(HttpContext context, object body, int code){context.Response.ContentType = "application/json";string jsonString, bodyText = string.Empty;APIResponse apiResponse = null;if (!body.ToString().IsValidJson())bodyText = JsonConvert.SerializeObject(body);elsebodyText = body.ToString();dynamic bodyContent = JsonConvert.DeserializeObject<dynamic>(bodyText);Type type;type = bodyContent?.GetType();if (type.Equals(typeof(Newtonsoft.Json.Linq.JObject))){apiResponse = JsonConvert.DeserializeObject<APIResponse>(bodyText);if (apiResponse.StatusCode != code)jsonString = JsonConvert.SerializeObject(apiResponse);else if (apiResponse.Result != null)jsonString = JsonConvert.SerializeObject(apiResponse);else{apiResponse = new APIResponse(code, ResponseMessageEnum.Success.GetDescription(), bodyContent, null);jsonString = JsonConvert.SerializeObject(apiResponse);}}else{apiResponse = new APIResponse(code, ResponseMessageEnum.Success.GetDescription(), bodyContent, null);jsonString = JsonConvert.SerializeObject(apiResponse);}return context.Response.WriteAsync(jsonString);}private async Task<string> FormatResponse(HttpResponse response){response.Body.Seek(0, SeekOrigin.Begin);var plainBodyText = await new StreamReader(response.Body).ReadToEndAsync();response.Body.Seek(0, SeekOrigin.Begin);return plainBodyText;}private bool IsSwagger(HttpContext context){return context.Request.Path.StartsWithSegments("/swagger");}
}

我们的定制中间件的主要方法是Invoke()。此方法接受HttpContext作为参数。上下文从管道对象中保持当前的Request和Response。这使我们可以截取上下文并进行一些自定义处理，在这种情况下：（a）处理异常（b）返回标准的自定义响应对象。

public static class ApiResponseMiddlewareExtension
{public static IApplicationBuilder UseAPIResponseWrapperMiddleware(this IApplicationBuilder builder){return builder.UseMiddleware<APIResponseMiddleware>();}
}

使用自定义中间件的最后一步是在Startup类的Configure()方法内调用我们在上面创建的扩展方法：

app.UseAPIResponseMiddleware();

标准ASP.NET Web API实现

public class ApiExceptionFilter : ExceptionFilterAttribute
{public override void OnException(HttpActionExecutedContext context){ApiError apiError = null;APIResponse apiResponse = null;int code = 0;if (context.Exception is ApiException){var ex = context.Exception as ApiException;apiError = new ApiError(ex.Message);apiError.ValidationErrors = ex.Errors;apiError.ReferenceErrorCode = ex.ReferenceErrorCode;apiError.ReferenceDocumentLink = ex.ReferenceDocumentLink;code = ex.StatusCode;}else if (context.Exception is UnauthorizedAccessException){apiError = new ApiError("Unauthorized Access");code = (int)HttpStatusCode.Unauthorized;}else{
#if !DEBUGvar msg = "An unhandled error occurred.";string stack = null;
#elsevar msg = context.Exception.GetBaseException().Message;string stack = context.Exception.StackTrace;
#endifapiError = new ApiError(msg);apiError.Details = stack;code = (int)HttpStatusCode.InternalServerError;}apiResponse = new APIResponse(code, ResponseMessageEnum.Exception.GetDescription(), null, apiError);HttpStatusCode c = (HttpStatusCode)code;context.Response = context.Request.CreateResponse(c, apiResponse);}
}

就像ASP.NET Core的HandleExceptionAsync()方法一样，自定义异常筛选器方法处理从应用程序引发的异常。筛选器的实现与ASP.NET Core HandleExceptionAsync()方法的实现几乎相同。

public class WrappingHandler : DelegatingHandler
{protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken){if (IsSwagger(request)){return await base.SendAsync(request, cancellationToken);}else{var response = await base.SendAsync(request, cancellationToken);return BuildApiResponse(request, response);}}private static HttpResponseMessage BuildApiResponse(HttpRequestMessage request, HttpResponseMessage response){dynamic content = null;object data = null;string errorMessage = null;ApiError apiError = null;var code = (int)response.StatusCode;if (response.TryGetContentValue(out content) && !response.IsSuccessStatusCode){HttpError error = content as HttpError;//handle exceptionif (error != null){content = null;if (response.StatusCode == HttpStatusCode.NotFound)apiError = new ApiError("The specified URI does not exist. Please verify and try again.");else if (response.StatusCode == HttpStatusCode.NoContent)apiError = new ApiError("The specified URI does not contain any content.");else{errorMessage = error.Message;#if DEBUGerrorMessage = string.Concat(errorMessage, error.ExceptionMessage, error.StackTrace);
#endifapiError = new ApiError(errorMessage);}data = new APIResponse((int)code, ResponseMessageEnum.Failure.GetDescription(), null, apiError);}elsedata = content;}else{if (response.TryGetContentValue(out content)){Type type;type = content?.GetType();if (type.Name.Equals("APIResponse")){response.StatusCode = Enum.Parse(typeof(HttpStatusCode), content.StatusCode.ToString());data = content;}else if (type.Name.Equals("SwaggerDocument"))data = content;elsedata = new APIResponse(code, ResponseMessageEnum.Success.GetDescription(), content);}else{if (response.IsSuccessStatusCode)data = new APIResponse((int)response.StatusCode, ResponseMessageEnum.Success.GetDescription());}}var newResponse = request.CreateResponse(response.StatusCode, data);foreach (var header in response.Headers){newResponse.Headers.Add(header.Key, header.Value);}return newResponse;}private bool IsSwagger(HttpRequestMessage request){return request.RequestUri.PathAndQuery.StartsWith("/swagger");}
}

上面的代码以不同的方式实现，但完成的功能与ASP.NET Core中间件中实现的功能相同。对于这种情况，我们使用委托处理程序来拦截当前上下文并为使用者构造一个自定义响应对象。我们使用Request.CreateResponse()方法使用适当的格式化程序创建了新的响应，然后在返回最终响应对象之前复制旧的未包装响应的任何头。

config.Filters.Add(new ApiExceptionFilter());
config.MessageHandlers.Add(new WrappingHandler());

总结