C#怎么实现WebAPI返回统一格式 C#如何封装统一的API响应格式包含状态码消息和数据【框架】

直接用 ActionResult 不够用，因其不提供统一的 code、message、data 响应结构，无法满足前端对业务状态码和标准化格式的需求。

为什么直接用 ActionResult 不够用

问题核心在于前端对稳定结构的硬性需求。每一次接口响应，前端都期望拿到一个包含 code（业务状态码）、message（提示信息）和 data（核心数据）的标准包裹。然而，原生的 ActionResult 或 IActionResult 返回的往往是“裸数据”或纯粹的HTTP状态码。这意味着，像“20001代表参数错误”这类业务状态码无处安放，统一的 message 字段也无从谈起。如果硬要在每个控制器里手动创建包装对象，不仅会产生大量重复代码，还容易遗漏、难以维护，这显然不是一种优雅的解决方案。

定义泛型响应类要避开三个坑

设计一个泛型响应类是第一步，但这里有几个常见的陷阱需要绕开：把 code 简单定义为 int 却没有统一的含义约定；将 data 声明为 object 导致序列化后丢失泛型信息，让前端难以推导类型；或者忽略了 data 为 null 时的默认值处理。

• code 字段：使用 int 类型没问题，但关键在于必须配套一个静态类（例如 ApiResultCode）来定义常量。这样做能彻底避免“魔法数字”散落在代码各处，让状态码的含义一目了然。
• data 字段：必须声明为泛型字段 TData，而不是 object。如果使用 object，在反序列化时，前端将无法获得真实的类型信息，失去了强类型带来的便利和安全性。
• 空值处理：在构造函数中，当 data 使用 default 关键字时，需要显式允许 null。特别是当 TData 是值类型时，可以考虑添加 where TData : class 约束，或者直接使用可空泛型约束（TData?）来优雅地处理这个问题。

下面是一个精简的示例代码，展示了如何实现：

public class ApiResult
{
    public int Code { get; set; }
    public string Message { get; set; } = string.Empty;
    public TData? Data { get; set; }

    public static ApiResult Success(TData? data = default, string message = "OK") =>
        new() { Code = 200, Message = message, Data = data };

    public static ApiResult Fail(int code, string message) =>
        new() { Code = code, Message = message };
}

全局统一包装需绕过 ObjectResult 的自动转换

定义了响应类之后，下一个挑战是如何让所有控制器方法的返回值自动套上这个“包装盒”。ASP.NET Core 默认会将返回值直接序列化为 JSON，它不会自动调用你写的 ApiResult.Success() 方法。我们的目标是让每一个 return Ok(xxx) 都自动变成 ApiResult.Success(xxx) 的格式。

这里的关键在于拦截时机：在模型绑定之后、结果序列化之前进行操作。使用中间件修改响应体往往为时已晚，因为那时数据可能已经被序列化了。更稳妥的方式是自定义一个 ActionFilter，并重写其 OnResultExecutionAsync 方法。

• 精准拦截：只针对 ObjectResult 和 OkObjectResult 进行包装。对于 EmptyResult、StatusCodeResult 等表示原生HTTP状态的响应，应该跳过，避免干扰。
• 避免套娃：必须判断 result.Value 是否已经是 ApiResult<*> 类型。如果是，就无需再次包装，防止出现“盒中盒”的嵌套结构。

以下是实现这一逻辑的关键代码节选：

if (result.Result is ObjectResult objectResult && 
    objectResult.Value != null && 
    objectResult.Value.GetType() != typeof(ApiResult<>))
{
    var genericType = typeof(ApiResult<>).MakeGenericType(objectResult.Value.GetType());
    var successMethod = typeof(ApiResult<>).GetMethod("Success").MakeGenericMethod(objectResult.Value.GetType());
    var wrapped = successMethod.Invoke(null, new[] { objectResult.Value, "OK" });
    context.Result = new OkObjectResult(wrapped);
}

异常也要进统一格式，但别吞掉 StatusCode

统一响应格式的最后一环，是确保异常情况也被标准化。通常我们会使用 UseExceptionHandler 中间件来捕获全局异常。但这里有一个极易被忽略的细节：如果直接在这个中间件里返回 ApiResult.Fail(500, ex.Message)，HTTP响应的状态码（StatusCode）很可能仍然是200。这是因为中间件默认使用了 OkObjectResult 来包装你的返回对象。

对于前端而言，HTTP状态码（如401、404、500）常用于网络层或框架级的通用判断（比如401自动跳转登录页），而业务 code（如40001表示Token过期）则用于具体的业务逻辑处理。两者必须共存，不可偏废。

• 手动设置状态码：在异常处理中，可以手动创建一个 ObjectResult，将 ApiResult