SpringBoot-RestController

在 Java Spring Boot（或 Spring MVC）中，@RestController 是一个核心注解，用于定义 RESTful 风格的 API 控制器 ，本质是 @Controller + @ResponseBody 的组合注解，核心作用是接收客户端的 HTTP 请求，处理业务逻辑后，直接返回 JSON/XML 等数据格式的响应（而非视图页面），专门用于构建前后端分离、接口服务等场景。

简单说：@RestController 的核心使命是「数据接口服务」，而非传统 MVC 中的「页面渲染」。

一、核心作用拆解

1. 标识控制器，接收 HTTP 请求

@RestController 会告诉 Spring 容器：这是一个控制器组件，负责接收客户端（如前端、其他服务）的 HTTP 请求（GET/POST/PUT/DELETE 等）。

结合 @RequestMapping（或 @GetMapping/@PostMapping 等派生注解），可精准映射请求路径，例如：

java

运行

复制代码

@RestController // 标识为 REST 接口控制器
@RequestMapping("/api/users") // 根路径映射
public class UserController {

    // 映射 GET 请求：/api/users/{id}
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        // 业务逻辑：查询用户（模拟数据库查询）
        return new User(id, "张三", 25); // 直接返回对象（自动转 JSON）
    }
}

2. 自动将返回值转为响应数据（无需 @ResponseBody）

这是 @RestController 最关键的特性：方法的返回值会自动通过消息转换器（如 Jackson）序列化为 JSON/XML 等格式，直接写入 HTTP 响应体（Response Body） ，无需额外添加 @ResponseBody 注解。

对比传统 @Controller：

java

运行

复制代码

// 传统 MVC：返回视图（如 JSP/Thymeleaf），需手动加 @ResponseBody 才返回数据
@Controller
@RequestMapping("/api/users")
public class UserController {
    @GetMapping("/{id}")
    @ResponseBody // 必须加，否则会找名为 "user" 的视图页面
    public User getUserById(@PathVariable Long id) {
        return new User(id, "张三", 25);
    }
}

// @RestController 简化后（无需 @ResponseBody）
@RestController
@RequestMapping("/api/users")
public class UserController {
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        return new User(id, "张三", 25); // 直接返回对象 → 自动转 JSON
    }
}

3. 适配 RESTful 架构规范

RESTful 是一种 API 设计风格，核心是「资源为中心」，通过 HTTP 方法表达对资源的操作（GET 查询、POST 创建、PUT 更新、DELETE 删除）。@RestController 天然适配这种风格，配合 Spring 的 HTTP 方法注解（@GetMapping/@PostMapping/@PutMapping/@DeleteMapping），可快速构建规范的 RESTful API：

HTTP 方法	接口路径	功能	示例返回值
GET	/api/users	查询所有用户	List<User>
GET	/api/users/{id}	查询单个用户	User
POST	/api/users	创建用户	User（含新 ID）
PUT	/api/users/{id}	更新用户	String "成功"
DELETE	/api/users/{id}	删除用户	Boolean true

示例代码：

java

运行

复制代码

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

    // 查询所有用户（GET）
    @GetMapping
    public List<User> getAllUsers() {
        return Arrays.asList(new User(1, "张三", 25), new User(2, "李四", 30));
    }

    // 创建用户（POST，接收 JSON 参数）
    @PostMapping
    public User createUser(@RequestBody User user) { // @RequestBody 接收请求体 JSON
        user.setId(3L); // 模拟数据库生成 ID
        return user; // 返回创建后的用户（含 ID）
    }

    // 更新用户（PUT）
    @PutMapping("/{id}")
    public String updateUser(@PathVariable Long id, @RequestBody User user) {
        // 业务逻辑：更新数据库
        return "用户 " + id + " 更新成功";
    }

    // 删除用户（DELETE）
    @DeleteMapping("/{id}")
    public boolean deleteUser(@PathVariable Long id) {
        // 业务逻辑：删除数据库记录
        return true;
    }
}

4. 处理请求参数与响应状态

@RestController 支持 Spring 丰富的参数绑定注解，可灵活接收客户端请求参数：

@PathVariable：从 URL 路径中获取参数（如 /users/{id}）；
@RequestBody：接收请求体中的 JSON/XML 数据（POST/PUT 常用）；
@RequestParam：接收 URL 查询参数（如 /users?name=张三）；
@RequestHeader：接收 HTTP 请求头信息。

同时可通过 @ResponseStatus 注解指定响应状态码（如 201 创建成功、404 资源不存在）：

java

运行

复制代码

@PostMapping
@ResponseStatus(HttpStatus.CREATED) // 响应状态码 201（Created）
public User createUser(@RequestBody User user) {
    user.setId(3L);
    return user;
}

@GetMapping("/{id}")
public User getUserById(@PathVariable Long id) {
    if (id == 0) {
        // 抛出异常，Spring 自动转为 404 响应
        throw new ResponseStatusException(HttpStatus.NOT_FOUND, "用户不存在");
    }
    return new User(id, "张三", 25);
}

二、关键区别：@RestController vs @Controller

很多初学者会混淆两者，核心区别在于「返回结果的处理方式」：

特性	@RestController	@Controller
核心用途	提供 RESTful 数据接口	传统 MVC 页面渲染（如 JSP/Thymeleaf）
返回值处理	自动转 JSON/XML（无需 @ResponseBody）	默认返回视图名，需加 @ResponseBody 才返回数据
适用场景	前后端分离、微服务接口、APP 接口	单体应用页面渲染、模板引擎开发

三、总结

@RestController 是 Spring 为简化 RESTful API 开发提供的「一站式注解」，核心作用是：

标识控制器，接收客户端 HTTP 请求；
自动将业务方法的返回值序列化为 JSON/XML 等数据格式，直接返回给客户端；
天然适配 RESTful 架构，快速构建规范的资源操作接口。

使用它可以避免重复编写 @Controller + @ResponseBody，让代码更简洁，是开发前后端分离、微服务接口的首选注解。