ASP.NET Core Web API自定义响应格式及元数据扩展问询

我需要创建自定义JSON响应格式，要求把业务数据包裹在data字段里，同时返回Content-Type: vnd.myapi+json。目前我已经用一个包装类ApiResult<TValue>在控制器里手动实现了，但想改成底层自动处理，不用每个接口都手动实例化这个类。

现有实现代码 #

public class ApiResult<TValue> 
{ 
    [JsonProperty("data")] 
    public TValue Value { get; set; } 
    [JsonExtensionData] 
    public Dictionary<string, object> Metadata { get; } = new Dictionary<string, object>(); 
    public ApiResult(TValue value) { Value = value; } 
} 

[HttpGet("{id}")] 
public async Task<ActionResult<ApiResult<Bike>>> GetByIdAsync(int id) 
{ 
    var bike = _dbContext.Bikes.AsNoTracking().SingleOrDefault(e => e.Id == id); 
    if (bike == null) { return NotFound(); } 
    return new ApiResult(bike); 
} 

public static class ApiResultExtensions 
{ 
    public static ApiResult<T> AddMetadata<T>(this ApiResult<T> result, string key, object value) 
    { 
        result.Metadata[key] = value; 
        return result; 
    } 
}

期望的响应格式 #

我希望最终返回的JSON结构是这样的，分页、其他元数据和data同级：

{ 
    "data": { ... }, 
    "pagination": { ... }, 
    "someothermetadata": { ... } 
}

现在的问题是，分页这类元数据需要在控制器动作里手动添加到Metadata字典中。我已经参考了ASP.NET Core的内容协商相关文档，但想确认方向是否正确。

核心疑问 #

如果通过自定义格式化器在底层自动处理响应封装，该如何添加分页这类和data同级的元数据？而且使用自定义格式化器时，还要能从控制器或者其他机制灵活添加元数据，保证扩展性。

现有方案的优缺点 #

• 当前包装类方案：优点是能适配所有序列化器（XML、JSON、YAML等），只要序列化器支持JsonExtensionData或者类似特性，就能统一处理元数据；缺点是每个控制器动作都要手动创建ApiResult实例，不够自动化。
• 自定义格式化器方案：缺点是可能只支持JSON格式，如果要支持其他格式需要单独创建对应的格式化器；优点是能在底层自动封装，不用控制器手动处理。

解决方案建议 #

要实现自动封装+灵活添加元数据，可以结合Action Filter和自定义格式化器（或者保持包装类但用Filter自动包装），这里提供两种思路：

思路1：用Action Filter自动包装响应，保留元数据扩展性

1. 创建一个ApiResultFilter，在OnActionExecuted方法中，把控制器返回的原始结果（比如Bike对象、OkResult等）自动包装成ApiResult<T>。
2. 为了能在控制器中添加元数据，可以用HttpContext.Items来传递元数据，或者创建一个自定义的MetadataBag服务注入到控制器中，Filter再从这里读取元数据添加到ApiResult的Metadata里。

示例代码片段：

public class ApiResultFilter : IAsyncActionFilter
{
    public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
    {
        var resultContext = await next();
        
        // 处理成功的结果
        if (resultContext.Result is ObjectResult objectResult && objectResult.Value is not ApiResult<object>)
        {
            var apiResult = new ApiResult<object>(objectResult.Value);
            
            // 从HttpContext读取控制器添加的元数据
            if (resultContext.HttpContext.Items.TryGetValue("ApiMetadata", out var metadataObj) && metadataObj is Dictionary<string, object> metadata)
            {
                foreach (var kvp in metadata)
                {
                    apiResult.AddMetadata(kvp.Key, kvp.Value);
                }
            }
            
            resultContext.Result = new ObjectResult(apiResult)
            {
                StatusCode = objectResult.StatusCode,
                ContentTypes = { "vnd.myapi+json" }
            };
        }
    }
}

// 控制器中添加元数据的方式
[HttpGet]
public async Task<ActionResult<List<Bike>>> GetAllAsync([FromQuery] PaginationParams pagination)
{
    var bikes = await _dbContext.Bikes.AsNoTracking().Skip(pagination.Skip).Take(pagination.Take).ToListAsync();
    var total = await _dbContext.Bikes.CountAsync();
    
    // 添加分页元数据到HttpContext
    HttpContext.Items["ApiMetadata"] = new Dictionary<string, object>
    {
        ["pagination"] = new { Total = total, Skip = pagination.Skip, Take = pagination.Take }
    };
    
    return bikes;
}

思路2：自定义JSON格式化器，结合元数据提供者

如果只想针对JSON格式做自动封装，可以创建自定义的JsonOutputFormatter，同时定义一个IApiMetadataProvider服务，让控制器或者其他组件通过这个服务添加元数据，格式化器在序列化时把元数据和data字段合并。

1. 定义元数据提供者接口：

public interface IApiMetadataProvider
{
    Dictionary<string, object> GetMetadata(HttpContext context);
}

public class DefaultApiMetadataProvider : IApiMetadataProvider
{
    public Dictionary<string, object> GetMetadata(HttpContext context)
    {
        var metadata = new Dictionary<string, object>();
        // 从HttpContext或者其他地方读取元数据
        if (context.Items.TryGetValue("ApiMetadata", out var obj) && obj is Dictionary<string, object> items)
        {
            foreach (var kvp in items) metadata.Add(kvp.Key, kvp.Value);
        }
        return metadata;
    }
}

2. 创建自定义JSON格式化器：

public class CustomJsonFormatter : JsonOutputFormatter
{
    private readonly IApiMetadataProvider _metadataProvider;

    public CustomJsonFormatter(JsonSerializerOptions options, IApiMetadataProvider metadataProvider) : base(options)
    {
        _metadataProvider = metadataProvider;
        SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("vnd.myapi+json"));
    }

    public override async Task WriteResponseBodyAsync(OutputFormatterWriteContext context, Encoding selectedEncoding)
    {
        var responseObj = new Dictionary<string, object>();
        // 添加data字段
        responseObj["data"] = context.Object;
        // 添加元数据
        var metadata = _metadataProvider.GetMetadata(context.HttpContext);
        foreach (var kvp in metadata)
        {
            responseObj[kvp.Key] = kvp.Value;
        }
        
        context.Object = responseObj;
        await base.WriteResponseBodyAsync(context, selectedEncoding);
    }
}

3. 在Program.cs中注册服务和格式化器：

builder.Services.AddSingleton<IApiMetadataProvider, DefaultApiMetadataProvider>();

builder.Services.AddControllers(options =>
{
    var jsonOptions = options.JsonSerializerOptions;
    var metadataProvider = builder.Services.BuildServiceProvider().GetRequiredService<IApiMetadataProvider>();
    options.OutputFormatters.Insert(0, new CustomJsonFormatter(jsonOptions, metadataProvider));
});

总结 #

• 如果需要支持多格式（XML、YAML等），优先选择Action Filter自动包装的方案，因为它能复用现有的序列化器，只需要统一包装成ApiResult<T>即可。
• 如果只专注于JSON格式，自定义格式化器方案更轻量，直接在序列化阶段处理结构。
• 两种方案都能通过HttpContext.Items或者自定义服务来传递元数据，保证控制器能灵活添加分页、自定义信息等内容。

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