Spring MVC 中 @ResponseBody 注解深度使用教程

一、注解核心作用

@ResponseBody 是 Spring MVC 中处理 响应体内容 的核心注解，主要功能：

• 跳过视图解析器：直接返回数据而非视图名称
• 自动数据转换：根据返回值类型自动转换响应格式（JSON/XML/纯文本）
• RESTful 支持：构建 Web API 时必备注解

---

二、基础使用场景

场景 1：返回纯文本内容

@Controller
public class TextController {

    @RequestMapping("/greet")
    @ResponseBody  // 直接写入响应体
    public String sayHello() {
        return "你好，Spring!"; 
    }
}

访问效果 ：
http://localhost:8080/greet → 浏览器显示纯文本内容

---

场景 2：返回 JSON 数据

@Controller
public class UserController {

    @GetMapping("/user")
    @ResponseBody
    public User getUser() {
        return new User("Alice", 28); // 自动转为JSON
    }
}

// 实体类
public class User {
    private String name;
    private int age;
    // 构造器/getters/setters省略
}

必要条件：

<!-- pom.xml 添加JSON转换依赖 -->
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.13.3</version>
</dependency>

---

三、工作原理详解

处理流程示意图

客户端请求 → DispatcherServlet → 控制器方法  
         ↑                        ↓
         └── @ResponseBody → MessageConverter（Jackson/Gson等） → 响应体

核心组件：

1. 消息转换器 (HttpMessageConverter)
   • 根据请求Accept头选择转换方式
   • 默认支持类型：JSON/XML/文本
2. 注解生效范围
   • 方法级：仅修饰的方法生效
   • 类级：所有方法默认使用

---

四、高级配置技巧

1. 强制指定响应格式

@RequestMapping(
    value = "/data", 
    produces = MediaType.APPLICATION_JSON_VALUE // 明确输出JSON
)
@ResponseBody
public Map<String, Object> getData() {
    return Map.of("code", 200);
}

2. 处理字符编码问题

// 配置类中添加字符过滤器
@Bean
public CharacterEncodingFilter encodingFilter() {
    CharacterEncodingFilter filter = new CharacterEncodingFilter();
    filter.setEncoding("UTF-8");
    filter.setForceEncoding(true);
    return filter;
}

3. 自定义消息转换器

@Configuration
public class WebConfig implements WebMvcConfigurer {
    
    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        // 添加自定义转换器
        converters.add(new CustomYamlConverter());
    }
}

---

五、最佳实践指南

方案对比表

方案	适用场景	特点
@Controller+@ResponseBody	混合型控制器（视图+API）	灵活但需要显式注解
@RestController	纯API接口开发	类级别自动应用@ResponseBody

推荐方案：使用 @RestController

@RestController  // 等效于 @Controller + @ResponseBody
@RequestMapping("/api")
public class ApiController {

    @GetMapping("/users")
    public List<User> listUsers() {
        return userService.findAll();
    }
}

---

六、常见问题排查

问题 1：返回字符串出现乱码

现象 ：中文显示为问号
解决方案：

# application.properties
spring.http.encoding.force=true
spring.http.encoding.charset=UTF-8

问题 2：返回对象报406错误

日志提示 ：
Could not find acceptable representation
根本原因：

• 缺少 Jackson 依赖
• 请求头未声明接受 JSON

验证步骤：

1. 检查请求头 Accept: application/json
2. 确认 jackson-databind 在依赖列表中

---

七、实战演练：构建天气API

完整代码示例

@RestController
public class WeatherController {

    private static final Map<String, String> WEATHER_DATA = Map.of(
        "shanghai", "晴转多云 25℃",
        "beijing", "阴天 18℃"
    );

    @GetMapping("/weather/{city}")
    public ResponseEntity<Object> getWeather(
            @PathVariable String city,
            @RequestParam(defaultValue = "json") String format) {

        String weather = WEATHER_DATA.getOrDefault(city.toLowerCase(), "城市不存在");
        
        if ("xml".equalsIgnoreCase(format)) {
            String xmlResponse = "<weather><city>"+city+"</city><info>"+weather+"</info></weather>";
            return ResponseEntity.ok()
                    .contentType(MediaType.APPLICATION_XML)
                    .body(xmlResponse);
        }
        
        return ResponseEntity.ok(Map.of(
            "city", city,
            "weather", weather
        ));
    }
}

测试用例

# 测试JSON输出
curl -H "Accept: application/json" http://localhost:8080/weather/shanghai

# 测试XML输出
curl -H "Accept: application/xml" http://localhost:8080/weather/beijing?format=xml

---

八、扩展知识：相关注解对比

注解	作用方向	典型应用场景
@RequestBody	请求 → 参数	接收 POST/PUT 的 JSON 数据
@ResponseBody	返回值 → 响应	输出API数据
@RequestParam	URL 参数	获取查询参数
@PathVariable	URL 路径片段	RESTful 资源定位

---

通过本教程，您已掌握：

✅ 核心作用与基础用法

✅ JSON数据处理与高级配置

✅ 生产环境问题排查技巧

✅ RESTful API 开发最佳实践

建议结合 Postman 等工具进行接口测试，加深对响应体处理机制的理解。