下面继续沿用“拆解式”思路，把 `@RestController` 从“本质 → 作用 → 实战 → 坑点”四个维度拆干净，并给出一张“场景-代码-注意点”三列表，拿来即用。 >[info]一、它到底是什么 1. 复合注解：`@RestController = @Controller + @ResponseBody` - `@Controller`：把类注册为 Spring MVC 控制器（Bean 名称默认首字母小写类名）。 - `@ResponseBody`：把**返回值直接写到 HTTP 响应体**（默认用 Jackson 转成 JSON）。 2. 目的：在**前后端分离**场景下，**一键声明 REST 接口**，省去每个方法都写 `@ResponseBody`。 >[info]二、它能做什么 - 自动将 POJO 序列化为 JSON/XML/文本（取决于 `Accept` 头与消息转换器）。 - 与 `@RequestMapping`、`@GetMapping`、`@PostMapping` 等无缝配合。 - 天生支持 Spring Boot 的 HTTP 消息转换器、内容协商、异常处理、跨域、安全、文档（Swagger）等。 >[info]三、常用场景与示例 | 场景 | 经典代码 | 注意点/最佳实践 | |---|------|----------|-----------------| | 最简 REST 类 | `@RestController`<br>`public class HelloApi { @GetMapping("/hi") public String hi(){return "hi";} }` | 返回 `String` → JSON `"hi"`；中文默认 UTF-8 | | 返回对象 | `@GetMapping("/user/{id}") public UserVO get(@PathVariable Long id){...}` | UserVO → JSON；字段命名遵循驼峰 | | 返回集合 | `@GetMapping("/users") public List<UserVO> list(){...}` | Jackson 默认将 `List` 写成 `[]` | | 返回 Map | `@GetMapping("/dict") public Map<String,String> dict(){...}` | Map → `{}` | | 返回 ResponseEntity | `@GetMapping("/download") public ResponseEntity<byte[]> dl(){...}` | 自定义状态码/头/体 | | 统一前缀 | `@RestController`<br>`@RequestMapping("/api/v1")` | 类上再加路径前缀 | | 与 `@Validated` | `@RestController`<br>`public class UserController { @PostMapping("/user") public UserVO add(@Valid @RequestBody UserDTO dto){...} }` | 参数校验失败自动抛 `MethodArgumentNotValidException` | | 全局异常 | `@RestControllerAdvice` + `@ExceptionHandler` | 配合 `@RestController` 统一返回 JSON | | 跨域 | `@CrossOrigin(origins="*") @RestController` | 或全局 `WebMvcConfigurer#addCorsMappings` | | 安全 | `@PreAuthorize("hasRole('ADMIN')") @RestController` | Spring Security | | Swagger 文档 | `@Tag(name="用户接口") @RestController` | springdoc-openapi | | 文件上传 | `@PostMapping("/upload") public String up(@RequestPart MultipartFile file){...}` | 与 `@RestController` 无冲突 | | 异步/Callable | `@GetMapping("/async") public Callable<String> async(){...}` | 返回 `Callable` → 不会阻塞 Tomcat 线程 | | WebFlux 响应式 | `@RestController` 在 `spring-boot-starter-webflux` 中同样适用 | 方法返回 `Mono<T>` / `Flux<T>` | | 自定义序列化 | `@JsonFormat(pattern="yyyy-MM-dd") private LocalDate birthday;` | Jackson 注解生效 | | 自定义消息转换器 | 实现 `WebMvcConfigurer#extendMessageConverters` | 例如 ProtoBuf、Fastjson 替换 | | 返回纯文本 | `produces="text/plain"` | 例如验证码图片、HTML 片段 | | 多协议支持 | `produces={"application/json","application/xml"}` | 客户端 `Accept` 决定 | | 与 `@Controller` 并存 | 一个项目里可以同时存在 `@Controller`（页面）和 `@RestController`（接口） | 路径不冲突即可 | | 单元测试 | `@SpringBootTest + @AutoConfigureMockMvc` | MockMvc 直接调接口，断言 JSON | >[info]四、易踩的坑 - 误把 `@RestController` 当成 MVC 视图：写了 `return "hello"` 会直接把 **字符串 `"hello"`** 当成 JSON 返回，而不是跳转到 `hello.html`。 - 日期格式：默认 `LocalDateTime` → `2023-11-17T10:34:56`；如要 `yyyy-MM-dd HH:mm:ss` 需加 `@JsonFormat` 或全局配置。 - 循环引用：双向关联实体直接返回会触发 `StackOverflow`，需 `@JsonIgnore` / DTO。 - 文件下载时忘记设置 `Content-Disposition: attachment`，浏览器会直接展示。 - 返回 `ResponseEntity` 时，若指定了 `produces`，实际内容类型必须与其一致，否则会 406。 - WebFlux 与 MVC 的 `@RestController` 写法一样，但依赖不同（`webflux` vs `web`），不要混用。 >[info]五、速查口诀 “RestController 等于 Controller 加 ResponseBody，返回对象自动转 JSON；路径映射随便写，统一异常用 RestControllerAdvice；日期循环要小心，文件下载设置头，视图跳转别用它。”