ASP.NET Web API 2.0 统一响应格式
传统实现
在搭建 Web API 服务的时候，针对客户端请求，我们一般都会自定义响应的 JSON 格式，比如：
{
"Data" : {
"Id" : 100,
"Name" : "Robin"
},
"ErrorMessage" : "错误消息"
}
在基于 ASP.NET Web API 的应用程序，我们一般会创建一个相应结构的 C# 类，如下：
public class ApiResult
{
public string ErrorMessage { get; set; }
public object Data { get; set; }
}
这里约定， ErrorMessage 为空或null，即表示没有异常，这时 Data 就是需要的数据；反之如果 ErrorMessage 不为空或null， 则代表错误消息，这时 Data 为null。
接下来在 Action 中返回该类的一个实例， Web API 会在内部调用格式化器将对象序列化为 JSON 或 XML 等格式，如下：
public class UserController : ApiController
{
public IHttpActionResult GetUser()
{
return new ApiResult()
{
Data = new User{ Id = 100, Name = "Robin" },
ErrorMessage = string.Empty
};
}
}
public class User
{
public int Id {get; set;}
public string Name {get; set;}
}
好了，传统做法就是这样，也可以实现。但是再进一步考虑，如果有非常多的 Action 方法，每次都要写 reutrn new ApiResult(){......} 是不是特别繁琐呢？
问题
有没有办法在 Action 方法中只返回真正需要的数据，但是返回给客户端时又统一成约定的 JSON 结构呢？
解决方案
当然有办法，借助 Web API 提供的 ActionFilter 就可以实现。
首先我们新建一个 CustomActionFilter ：
public class CustomActionFilter : ActionFilterAttribute
{
public override void OnActionExecuted(HttpActionExecutedContext context)
{
var content = context.Response?.Content as ObjectContent;
if (content != null)
{
content.Value = new ApiResult
{
Data = content.Value,
};
}
}
}
然后 Action 方法这样写：
public User GetAll()
{
return new new User{Id = 100, Name = "Robin"};
}
这样实现的另一个好处是，由于返回值是强类型，可以据此生成 API 文档，方法的可读性也更好。
异常处理
前面提到的需求实现了，然后再进一步考虑，如何处理异常情况？
如果由于代码 BUG 抛出未处理的异常，Web API仍然会调用 CustomActionFilter 中的代码，但是这时 Response = null，也就无法给 content.Value 重新赋值。
这时 Web API 会将框架约定的 JSON 消息返回给客户端，而不是我们业务上需要的，如下是 Web API 抛出的未处理异常消息：
{
"Message": "An error has occurred.",
"ExceptionMessage": "No MessageException parameter",
"ExceptionType": "Framework.Common.MessageException",
"StackTrace": " 在 Controllers.FooController.GetAll() 位置......
}
这时如果还希望异常消息遵循业务约定的 JSON 格式，该如何做呢？
这里要分几种情况：
Action 内的异常
可以直接在 CustomActionFilter 的 OnActionExecuted 方法中处理，改造后的代码如下：
public override void OnActionExecuted(HttpActionExecutedContext context)
{
var content = context.Response?.Content as ObjectContent;
if (content != null)
{
content.Value = new ApiResult { Data = content.Value };
}
// 设置发生异常时的消息
if (context.Exception != null)
{
context.Response = new HttpResponseMessage(HttpStatusCode.InternalServerError)
{
Content = new StringContent(JsonConvert.SerializeObject(
new ApiResult
{
ErrorMessage = context.Exception.Message
}), Encoding.UTF8, "application/json")
};
}
}
同样也可以用自定义 ExceptionFilter 来达到同样的目的，这里为了简化不再贴代码。
其他异常
ActionFilterAttribute 和 ExceptionFilterAttribute 都只能处理部分异常，比如 Action 内的异常，但是譬如 以下的几种未处理异常，过滤器就爱莫能助了：
- 来自 Controller 构造器的异常。
- 来自 Message Handlers 的异常。
- 匹配路由过程中的异常
- 在序列化响应内容期间产生的异常
为了处理全局范围内的未处理异常，Web API 提供了 ExceptionHandler 和 ExceptionLogger。
详情可以参考我翻译的文档：ASP.NET Web API 2 中的全局错误处理
其中只有 ExceptionHandler 可以在捕捉到未处理异常并处理后，对响应消息进行重新设置，而 ExceptionLogger 则不能。
代码如下：
public class CollectServiceExceptionHandler : ExceptionHandler
{
public override Task HandleAsync(ExceptionHandlerContext context, CancellationToken cancellationToken)
{
context.Result = new ApiResult { ErrorMessage = context.Exception.Message };
return base.HandleAsync(context, cancellationToken);
}
}
注意：这里 ExceptionHandlerContext 的 Result 属性的类型是 IHttpActionResult，所以**ApiResult ** 类要实现 IHttpActionResult 接口。
ExceptionHandler 的用途就是：接收全局范围内未处理的异常，然后返回一个自定义的错误消息。
总结
实现开篇的需求，有三种实现方式：
- 自定义 ActionFilterAttribute
- 自定义 ExceptionFilterAttribute
- 自定义 ExceptionHandler
补充：经 @ichengzi 指出，『web api 2.0 之前的版本不支持这种处理方法』。
