ASP.NET Core Web API 响应数据格式化详解

概述

在构建现代Web API时，数据格式的灵活性是一个重要考量。ASP.NET Core提供了强大的响应数据格式化功能，允许开发者以多种格式返回数据，包括JSON、XML等，并能根据客户端请求自动协商最佳响应格式。

基础格式化方式

特定格式的ActionResult

ASP.NET Core提供了一些专门用于特定格式的ActionResult类型：

1. JsonResult：强制返回JSON格式数据
2. ContentResult：返回纯文本格式数据

// 返回JSON格式数据
public IActionResult Get() 
{
    return Ok(new { Id = 1, Name = "示例" });
}

// 返回纯文本格式数据
public IActionResult GetVersion()
{
    return Content("1.0.0");
}

对象返回值

当控制器方法返回非IActionResult类型的对象时，ASP.NET Core会自动选择合适的输出格式化器进行序列化：

public TodoItem GetById(int id)
{
    var item = _repository.Find(id);
    return item ?? null;  // 返回null将产生204 No Content响应
}

内容协商机制

内容协商是Web API的核心特性之一，它允许客户端通过Accept请求头指定期望的响应格式。

工作原理

1. 客户端在请求中包含Accept头（如application/json）
2. 服务器检查支持的格式化器
3. 选择最匹配客户端请求的格式化器
4. 如果无法满足请求：
   • 当ReturnHttpNotAcceptable为true时返回406 Not Acceptable
   • 否则使用第一个可用的格式化器

浏览器特殊处理

由于浏览器通常会发送包含多种格式的Accept头，ASP.NET Core默认会忽略浏览器的Accept头，始终返回JSON格式。如需改变此行为：

builder.Services.AddControllers(options => 
{
    options.RespectBrowserAcceptHeader = true;
});

配置格式化器

添加XML支持

builder.Services.AddControllers()
    .AddXmlSerializerFormatters();

配置JSON格式化器

System.Text.Json配置

builder.Services.Configure<JsonOptions>(options =>
{
    options.JsonSerializerOptions.PropertyNamingPolicy = null; // 使用PascalCase
});

Newtonsoft.Json配置

如需使用Newtonsoft.Json：

builder.Services.AddControllers()
    .AddNewtonsoftJson(options =>
    {
        options.SerializerSettings.ContractResolver = 
            new DefaultContractResolver();
    });

高级控制

强制特定格式

使用[Produces]特性可以限制控制器或方法的响应格式：

[Produces("application/json")]
[ApiController]
public class TodoItemsController : ControllerBase
{
    // 所有方法将只返回JSON格式
}

特殊格式化器行为

默认情况下：

• 字符串返回类型格式化为text/plain
• 返回null对象会产生204 No Content响应

可以移除这些默认行为：

builder.Services.AddControllers(options =>
{
    options.OutputFormatters.RemoveType<StringOutputFormatter>();
    options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
});

URL路径格式映射

可以通过路由配置让URL路径包含格式信息：

[ApiController]
[Route("api/[controller]")]
[FormatFilter]
public class TodoItemsController : ControllerBase
{
    [HttpGet("{id}.{format?}")]
    public TodoItem GetById(int id)
    {
        // ...
    }
}

这样可以通过以下URL访问：

• /api/todoitems/5 - 使用默认格式
• /api/todoitems/5.json - 强制JSON格式
• /api/todoitems/5.xml - 强制XML格式

多态反序列化

虽然ASP.NET Core内置了有限的多态序列化支持，但反序列化需要自定义转换器。这通常需要实现自定义的JsonConverter来处理继承类型的反序列化。

最佳实践

1. 优先使用System.Text.Json，它在性能上优于Newtonsoft.Json
2. 保持API响应格式的一致性
3. 为特殊需求考虑自定义格式化器
4. 明确文档化API支持的格式
5. 考虑使用版本控制来处理格式变更

通过合理利用ASP.NET Core的格式化功能，可以构建出灵活、高效的Web API，满足各种客户端的需求。