ASP.NET Core Web API 响应格式化示例解析

概述

本文深入解析 ASP.NET Core Web API 中的响应格式化机制，通过一个待办事项(Todo)控制器的示例代码，展示如何配置不同的 JSON 响应格式。

控制器基础配置

首先我们来看控制器的基础配置：

[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class TodoItemsController : ControllerBase

这段代码定义了控制器类并添加了几个重要特性：

• [ApiController]：标识这是一个API控制器，启用API特定的行为和约定
• [Route]：定义控制器的基本路由模板
• [Produces]：指定控制器默认产生JSON格式的响应

默认JSON响应

第一个GET方法展示了如何使用System.Text.Json返回JSON响应：

[HttpGet]
public IActionResult Get() =>
    new JsonResult(
        _todoItemStore.GetList(),
        new JsonSerializerOptions
        {
            PropertyNamingPolicy = null
        });

关键点：

• 使用JsonResult返回格式化后的JSON数据
• 通过JsonSerializerOptions配置序列化选项
• PropertyNamingPolicy = null表示保持属性名称原样输出，不进行任何命名策略转换

使用Newtonsoft.Json响应

第二个GET方法展示了如何使用Newtonsoft.Json库返回JSON响应：

[HttpGet]
public IActionResult GetNewtonsoftJson() =>
    new JsonResult(
        _todoItemStore.GetList(),
        new JsonSerializerSettings
        {
            ContractResolver = new DefaultContractResolver()
        });

关键点：

• 使用Newtonsoft.Json的JsonSerializerSettings配置
• DefaultContractResolver保持属性名称原样输出
• 这种方式适用于需要Newtonsoft.Json特有功能的场景

按ID获取单项

第三个方法展示了直接返回模型对象的简单方式：

[HttpGet("{id:long}")]
public TodoItem? GetById(long id) =>
    _todoItemStore.GetById(id);

关键点：

• 直接返回TodoItem对象，框架会自动序列化为JSON
• 路由模板包含{id:long}参数约束，确保id为长整型
• 返回类型为可空类型TodoItem?，表示可能返回null

实际应用建议

1. 命名策略选择：

   • 默认情况下，ASP.NET Core使用小驼峰命名(camelCase)
   • 通过设置PropertyNamingPolicy = null可以保持原样输出
   • 也可以自定义命名策略以满足特定需求

2. 序列化库选择：

   • System.Text.Json是ASP.NET Core默认的JSON库，性能更好
   • Newtonsoft.Json功能更丰富，适合复杂场景
   • 项目应保持一致的序列化库选择

3. 直接返回模型：

   • 对于简单场景，直接返回模型对象是最简洁的方式
   • 框架会自动处理序列化和状态码(200 OK)

4. 错误处理：

   • 考虑添加适当的错误处理，如找不到项目时返回404
   • 可以通过返回ActionResult<T>类型来明确可能的返回类型

通过这个示例，我们可以看到ASP.NET Core提供了多种灵活的方式来格式化API响应，开发者可以根据项目需求选择最适合的方式。