@RestController 注解详解

1. 注解出处

@RestController 是 Spring 框架中用于简化 RESTful Web 服务开发的注解，首次出现在 Spring 4.0 版本中，属于 org.springframework.web.bind.annotation 包。它的设计初衷是简化基于 Spring MVC 构建 REST API 的代码编写。

---

2. 核心功能

@RestController 是一个组合注解，融合了以下两个注解的特性：
• @Controller：标识该类为 Spring MVC 的控制器，能够处理 HTTP 请求。
• @ResponseBody：自动将方法的返回值序列化为 JSON/XML 格式，直接写入 HTTP 响应体（而非跳转视图）。

通过合并这两个注解，@RestController 使得开发者无需在每个方法上单独添加 @ResponseBody，从而更高效地构建 REST API。

---

3. 使用场景

• 开发前后端分离的 RESTful API。
• 需要直接返回数据对象（如 JSON）而非 HTML 视图时。
• 配合 Spring Boot 快速搭建微服务接口。

---

4. 使用方法

4.1 基本声明

在类级别添加 @RestController，定义该类为 REST 控制器：

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

@RestController
public class UserController {
    // 方法实现
}

4.2 处理 HTTP 请求

使用 @GetMapping、@PostMapping 等注解映射请求路径和方法：

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

4.3 路径变量与请求参数

通过 @PathVariable 和 @RequestParam 获取 URL 中的动态参数：

@GetMapping("/users/{id}")
public User getUserById(@PathVariable Long id) {
    return userService.findById(id);
}

@PostMapping("/users/search")
public List<User> searchUsers(@RequestParam String keyword) {
    return userService.search(keyword);
}

4.4 返回复杂对象

方法返回的对象会被自动转换为 JSON：

@PostMapping("/users")
public User createUser(@RequestBody User user) {
    return userService.save(user);
}

---

5. 完整代码示例

@RestController
@RequestMapping("/api")
public class UserController {

    @Autowired
    private UserService userService;

    // 获取所有用户
    @GetMapping("/users")
    public List<User> getAllUsers() {
        return userService.findAll();
    }

    // 创建用户
    @PostMapping("/users")
    public User createUser(@RequestBody User user) {
        return userService.save(user);
    }

    // 删除用户
    @DeleteMapping("/users/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        userService.deleteById(id);
        return ResponseEntity.noContent().build();
    }
}

---

6. 注意事项

1. 依赖配置：确保项目中包含 JSON 序列化库（如 Jackson），使用 @RestController 后，Spring 不会进行视图解析，需避免与 @Controller 混用。
2. HTTP 状态码控制：使用 ResponseEntity 可自定义响应状态码和头信息。
3. 异常处理：建议配合 @ControllerAdvice 全局处理异常，返回统一的错误格式。

---

7. 总结

@RestController 是 Spring 生态中构建 REST API 的核心工具，通过减少样板代码显著提升开发效率。结合 Spring Boot 的自动配置，开发者可以快速搭建高性能的 Web 服务接口。在微服务架构和前后端分离项目中，该注解的应用尤为广泛。