当前位置：首页 > news >正文

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

news 来源：原创 2025/9/20 16:15:59

在这里插入图片描述

@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 {@Beanpublic 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> {@Overridepublic 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 的注解和配置进一步优化。