spring mvc @ResponseBody 注解转换为 JSON 的原理与实现详解

---

@ResponseBody 注解转换为 JSON 的原理与实现详解

---

1. 核心作用

@ResponseBody 是 Spring MVC 的一个注解，用于将方法返回的对象直接序列化为 HTTP 响应体（如 JSON 或 XML），而不是通过视图解析器渲染为视图（如 HTML）。

• 关键作用：
  • 跳过视图解析阶段，直接返回数据。
  • 触发 消息转换器（HttpMessageConverter） 将对象转换为指定格式（如 JSON）。

---

2. 工作流程详解

步骤 1：方法返回对象

@RestController
public class UserController {
    @GetMapping("/user")
    public User getUser() {
        return new User("John", 25); // 返回 Java 对象
    }
}

步骤 2：触发消息转换

• Spring 检测到 @ResponseBody：跳过视图解析，直接进入消息转换阶段。
• 选择合适的 HttpMessageConverter：
  • 根据 返回对象类型 和 请求的 Accept 头（如 application/json）选择转换器。
  • 默认情况下，Spring Boot 自带的 Jackson 库 提供的 MappingJackson2HttpMessageConverter 会被选中。

步骤 3：Jackson 序列化对象

• Jackson 的 ObjectMapper：负责将 Java 对象转换为 JSON 字符串。
• 序列化过程：
  1. 遍历对象的 getter 方法 或 字段。
  2. 根据注解（如 @JsonProperty）和配置（如日期格式）处理属性。
  3. 忽略 transient 字段或 @JsonIgnore 标记的字段。

// 示例 JSON 输出
{
  "name": "John",
  "age": 25
}

---

3. 完整代码示例

---

3.1 实体类（User.java）

public class User {
    private String name;
    private int age;

    // 构造函数、getter 和 setter 方法
    public User(String name, int age) {
        this.name = name;
        this.age = age;
    }

    // 省略 getter/setter
}

3.2 控制器（UserController.java）

import org.springframework.web.bind.annotation.*;

@RestController // 等效于 @Controller + @ResponseBody
public class UserController {

    @GetMapping("/user")
    public User getUser() {
        return new User("John", 25); // 直接返回对象，由 @ResponseBody 触发转换
    }

    @PostMapping("/user")
    public User createUser(@RequestBody User user) {
        // 处理 POST 请求，将 JSON 反序列化为 User 对象
        return user;
    }
}

3.3 测试请求

# GET 请求获取 JSON
curl http://localhost:8080/user
# 输出：{"name":"John","age":25}

# POST 请求发送 JSON
curl -X POST -H "Content-Type: application/json" -d '{"name":"Jane","age":30}' http://localhost:8080/user

---

4. 消息转换器（HttpMessageConverter）详解

Spring MVC 通过 HttpMessageConverter 完成对象到 HTTP 响应的转换。

• 核心接口：HttpMessageConverter<T>

  • canRead()：判断是否支持反序列化（如 JSON → 对象）。
  • canWrite()：判断是否支持序列化（如对象 → JSON）。
  • write()：实际执行序列化操作。

• 常用实现类：

  类名	作用	默认支持格式
  MappingJackson2HttpMessageConverter	JSON 转换（依赖 Jackson 库）	application/json
  MappingJackson2XmlHttpMessageConverter	XML 转换（需额外配置）	application/xml
  StringHttpMessageConverter	字符串转换	text/plain

---

5. Jackson 配置与自定义

通过自定义 ObjectMapper 可控制 JSON 序列化行为：

5.1 配置示例

import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.text.SimpleDateFormat;

@Configuration
public class JacksonConfig {

    @Bean
    public ObjectMapper objectMapper() {
        ObjectMapper mapper = new ObjectMapper();
        // 设置日期格式
        mapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));
        // 忽略未找到的字段（反序列化时）
        mapper.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
        return mapper;
    }
}

5.2 常用注解

注解	作用
@JsonProperty	指定 JSON 键名（覆盖字段名）。
@JsonFormat	定制日期/数字格式。
@JsonInclude	控制字段是否参与序列化（如 @JsonInclude(JsonInclude.Include.NON_NULL)）。
@JsonIgnore	忽略字段。

---

6. 常见问题与解决方案

---

Q1：为什么 JSON 中没有某个字段？

• 可能原因：
  • 字段没有 getter 方法。
  • 字段被 @JsonIgnore 或 transient 修饰。
  • @JsonInclude 配置排除了该字段（如 NON_NULL 且值为 null）。

Q2：如何处理循环引用？

• 解决方案：

  @JsonManagedReference // 主对象（单向引用）
  @JsonBackReference // 被引用对象（忽略反向引用）
  

Q3：如何自定义序列化逻辑？

• 自定义序列化器：

  public class CustomSerializer extends JsonSerializer<Date> {
      @Override
      public void serialize(Date value, JsonGenerator gen, SerializerProvider serializers)
              throws IOException {
          gen.writeString(new SimpleDateFormat("yyyy-MM-dd").format(value));
      }
  }
  

Q4：如何禁用 HTML 转义？

• 配置：

  @Bean
  public MappingJackson2HttpMessageConverter jackson2HttpMessageConverter() {
      MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter();
      converter.getObjectMapper().disable(SerializationFeature.ESCAPE_NON_ASCII);
      return converter;
  }
  

---

7. 总结表格

环节	关键组件	职责
触发转换	@ResponseBody	告知 Spring 直接返回数据，跳过视图解析。
选择转换器	HttpMessageConverter	根据返回类型和 Accept 头选择合适的转换器。
序列化	Jackson（ObjectMapper）	将 Java 对象转换为 JSON 字符串。
配置扩展	自定义 ObjectMapper	精细控制序列化格式、日期、忽略策略等。

---

总结

@ResponseBody 通过结合 HttpMessageConverter 和 Jackson，将 Java 对象无缝转换为 JSON 响应。掌握其工作原理和配置方法，可以灵活处理 RESTful API 的数据格式化需求。对于复杂场景（如自定义序列化、处理循环引用），可通过 Jackson 的注解和配置进一步优化。