.NET Core 如何实现统一通用API响应格式？附最佳实践建议

一、定义通用响应模型 #

先创建一个泛型类匹配你需要的格式，兼容不同类型的返回数据：

public class ApiResponse<T>
{
    public T? Payload { get; set; }
    public string? ErrorMessage { get; set; }
    public Dictionary<string, object>? MetaData { get; set; }

    // 基础成功响应构造
    public ApiResponse(T payload)
    {
        Payload = payload;
        ErrorMessage = null;
        MetaData = null;
    }

    // 带元数据的成功响应构造
    public ApiResponse(T payload, Dictionary<string, object> metaData)
    {
        Payload = payload;
        ErrorMessage = null;
        MetaData = metaData;
    }

    // 错误响应构造
    public ApiResponse(string errorMessage)
    {
        Payload = default;
        ErrorMessage = errorMessage;
        MetaData = null;
    }
}

二、全局自动包装响应 #

用结果过滤器实现全API自动包装，不用每个接口手动实例化响应模型：

1. 实现结果过滤器 #

public class ApiResponseFilter : IAsyncResultFilter
{
    public async Task OnResultExecutionAsync(ResultExecutingContext context, ResultExecutionDelegate next)
    {
        if (context.Result is ObjectResult objectResult)
        {
            var apiResponse = new ApiResponse<object>(objectResult.Value);
            
            // 示例：给列表接口自动添加总数元数据
            if (objectResult.Value is IEnumerable<object> collection)
            {
                apiResponse.MetaData = new Dictionary<string, object>
                {
                    ["totalCount"] = collection.Count()
                };
            }

            context.Result = new OkObjectResult(apiResponse);
        }
        else if (context.Result is NotFoundResult)
        {
            context.Result = new OkObjectResult(new ApiResponse<object>("请求的资源不存在"));
        }
        // 可扩展处理BadRequest、Unauthorized等其他状态码

        await next();
    }
}

2. 注册全局过滤器 #

在Program.cs中添加配置：

builder.Services.AddControllers(options =>
{
    options.Filters.Add<ApiResponseFilter>();
});

三、异常统一处理 #

用全局异常过滤器捕获未处理异常，返回标准错误响应：

public class GlobalExceptionFilter : IExceptionFilter
{
    private readonly ILogger<GlobalExceptionFilter> _logger;

    public GlobalExceptionFilter(ILogger<GlobalExceptionFilter> logger)
    {
        _logger = logger;
    }

    public void OnException(ExceptionContext context)
    {
        _logger.LogError(context.Exception, "API未捕获异常");
        var apiResponse = new ApiResponse<object>("服务器内部错误，请稍后重试");
        context.Result = new ObjectResult(apiResponse)
        {
            StatusCode = StatusCodes.Status500InternalServerError
        };
        context.ExceptionHandled = true;
    }
}

同样在Program.cs注册：

builder.Services.AddControllers(options =>
{
    options.Filters.Add<GlobalExceptionFilter>();
    options.Filters.Add<ApiResponseFilter>();
});

四、API响应最佳实践补充内容 #

除了你定义的字段，以下内容是行业通用的优化项：

• HTTP状态码：不要固定返回200，根据场景返回对应状态码（400参数错误、401未授权、403禁止访问等），配合errorMessage提供细节。
• 业务错误码：在响应中添加ErrorCode字段（如1001代表参数校验失败，2001代表资源不存在），方便前端快速判断错误类型。
• 请求ID：给每个请求生成唯一ID，放在MetaData或响应头中，便于日志排查问题。
• 分页元数据：列表接口的MetaData补充pageIndex、pageSize、totalPages、totalCount，帮助前端处理分页逻辑。
• 时间戳：添加Timestamp字段记录响应生成时间，便于排查时序相关问题。
• 本地化错误信息：根据请求头的Accept-Language返回对应语言的错误提示，适配多语言场景。

内容的提问来源于stack exchange，提问作者Fahad Subzwari