隔壁倒霉孩子1. 为什么我们需要区分RestController和Controller？
在Spring Boot开发中，Controller和RestController是两个最常用的注解，但很多开发者在使用时存在困惑。我刚开始接触Spring Boot时，也曾因为混用这两个注解导致接口返回了奇怪的视图名称而不是预期的JSON数据。经过多次踩坑后，我逐渐理解了它们的设计初衷和使用场景。
Spring框架最初是为传统的MVC web应用设计的，Controller注解就是这一时期的产物。随着RESTful API的流行，Spring团队发现开发者在使用Controller编写API时需要频繁添加@ResponseBody注解，于是创造了RestController这个组合注解来简化开发。
关键区别：Controller返回的是视图名称，而RestController默认将方法返回值作为响应体（相当于自动添加@ResponseBody）
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 源码层面的深度解析
2.1 Controller注解的本质
查看Spring源码(org.springframework.stereotype.Controller)可以看到：
java复制@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Component
public @interface Controller {
@AliasFor(annotation = Component.class)
String value() default "";
}
这只是一个标准的组件注解，它的核心作用是将类标记为Spring MVC控制器。当请求到达DispatcherServlet时，Spring会查找带有@Controller注解的类来处理请求。
2.2 RestController的魔法
RestController的源码(org.springframework.web.bind.annotation.RestController)揭示了它的本质：
java复制@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Controller
@ResponseBody
public @interface RestController {
@AliasFor(annotation = Controller.class)
String value() default "";
}
关键点在于它组合了@Controller和@ResponseBody两个注解。这意味着：
- 它具备Controller的所有功能
- 所有处理器方法的返回值都会自动经过HttpMessageConverter转换后写入响应体
3. 实际开发中的行为对比
3.1 返回类型处理差异
假设我们有以下两个控制器：
java复制@Controller
public class TraditionalController {
@GetMapping("/traditional")
public String traditional() {
return "hello"; // 会被解析为视图名
}
}
@RestController
public class RestStyleController {
@GetMapping("/rest")
public String rest() {
return "hello"; // 直接作为响应体返回
}
}
访问/traditional会尝试查找名为"hello"的视图模板，而访问/rest会直接得到"hello"字符串。
3.2 异常处理的不同表现
当方法抛出异常时：
- Controller中：可以通过@ExceptionHandler返回ModelAndView
- RestController中：@ExceptionHandler方法默认也会被视为@ResponseBody
3.3 内容协商机制
RestController自动支持内容协商(content negotiation)，根据请求的Accept头自动选择合适的消息转换器：
java复制@RestController
public class UserController {
@GetMapping("/user")
public User getUser() {
return new User("John", 30);
}
}
这个接口会根据客户端请求的Accept头(application/json, application/xml等)自动返回不同格式的数据。
4. 高级应用场景与最佳实践
4.1 混合使用场景
有时我们可能需要在一个控制器中同时支持视图返回和API响应。这时可以：
java复制@Controller
public class HybridController {
// 返回视图
@GetMapping("/page")
public String page() {
return "view-name";
}
// 返回API响应
@GetMapping("/api")
@ResponseBody
public ApiResponse api() {
return new ApiResponse();
}
}
4.2 性能考量
由于RestController默认使用消息转换器，在处理大量请求时需要注意：
- 避免在转换过程中创建不必要的中间对象
- 对于大型对象，考虑使用流式响应
- 选择合适的HttpMessageConverter实现（如Jackson vs GSON）
4.3 测试策略差异
测试Controller和RestController的方式也有所不同：
java复制// 测试Controller
@Test
void testTraditionalController() throws Exception {
mockMvc.perform(get("/traditional"))
.andExpect(status().isOk())
.andExpect(view().name("hello"));
}
// 测试RestController
@Test
void testRestController() throws Exception {
mockMvc.perform(get("/rest"))
.andExpect(status().isOk())
.andExpect(content().string("hello"));
}
5. 常见误区与排查技巧
5.1 为什么我的Controller返回字符串变成了下载？
这是因为缺少合适的视图解析器配置，Spring将返回值直接写入响应体时，默认Content-Type可能是application/octet-stream。解决方案：
- 确保配置了InternalResourceViewResolver
- 或者明确添加@ResponseBody注解
5.2 日期格式不一致问题
RestController自动使用Jackson序列化时，日期格式可能不符合预期。解决方法：
java复制@RestController
public class DateController {
@GetMapping("/date")
public Map<String, Object> getDate() {
return Map.of("date", new Date());
}
@Bean
public Jackson2ObjectMapperBuilderCustomizer jsonCustomizer() {
return builder -> builder.dateFormat(new SimpleDateFormat("yyyy-MM-dd"));
}
}
5.3 循环引用问题
当返回的对象存在双向引用时，Jackson会抛出异常。解决方案：
- 使用@JsonIgnore忽略一方
- 或者配置Mapper启用循环引用处理：
java复制@Bean
public MappingJackson2HttpMessageConverter mappingJackson2HttpMessageConverter() {
ObjectMapper mapper = new ObjectMapper();
mapper.configure(SerializationFeature.FAIL_ON_EMPTY_BEANS, false);
mapper.enable(SerializationFeature.INDENT_OUTPUT);
return new MappingJackson2HttpMessageConverter(mapper);
}
6. 版本演进与未来趋势
从Spring 4.0引入RestController以来，它的功能不断增强：
- Spring Boot 1.x：基础功能
- Spring Boot 2.x：改进的内容协商机制
- Spring Boot 3.x：对Reactive编程的更好支持
在响应式编程中，WebFlux框架提供了类似的@RestController和@Controller注解，但底层实现完全不同。如果你开始使用WebFlux，需要重新理解这些注解在响应式环境中的行为。