@RestController

引言

@RestController 是 Spring Boot 开发 RESTful API 的核心注解，专门用于构建前后端分离、微服务架构中的接口服务。该注解会将类标记为 Spring MVC 控制器，自动将所有方法的返回值序列化为 JSON/XML 并写入 HTTP 响应体，无需跳转视图页面，是现代 Spring 开发的标准用法。

核心概念

组合注解

@RestController 是复合注解，等价于： @Controller + @ResponseBody

@Controller：将类注册为 Spring 控制器，接收 HTTP 请求
@ResponseBody：全局生效，所有方法返回值直接作为响应数据，不解析视图

极简示例

// 推荐写法（Spring Boot 标准）
@RestController
public class RoomController {
    // 返回对象自动转为 JSON
    @GetMapping("/room")
    public Room getRoom() {
        return new Room(1L, "标准间", 299);
    }
}

// 等价传统写法（冗余，不推荐）
@Controller
@ResponseBody
public class RoomController {
    @GetMapping("/room")
    public Room getRoom() {
        return new Room(1L, "标准间", 299);
    }
}

与 @Controller 区别

特性	@RestController	@Controller
返回值处理	自动序列化为 JSON/XML 数据	返回视图名称（页面跳转）
核心组合	@Controller + @ResponseBody	原生 Spring MVC 控制器注解
适用场景	RESTful API、前后端分离、微服务	传统服务端渲染（JSP/Thymeleaf）
@ResponseBody	全局自动生效	需手动添加在方法上才返回数据
典型返回值	对象、集合、ResponseEntity	字符串视图名（如 `index`）

HTTP 请求映射注解

@RestController 必须配合请求映射注解使用，用于绑定接口地址与请求方式：

基础注解

@RequestMapping：通用映射，可指定所有请求方式（类上统一前缀）
@GetMapping：处理 GET 请求（查询资源）
@PostMapping：处理 POST 请求（创建资源）
@PutMapping：处理 PUT 请求（全量更新资源）
@PatchMapping：处理 PATCH 请求（部分更新资源，原文补充）
@DeleteMapping：处理 DELETE 请求（删除资源）

最佳实践

类上统一前缀

@RestController
@RequestMapping("/api/users") // 所有接口统一前缀
public class UserController { }

请求参数绑定

Spring Boot 自动绑定 HTTP 请求参数，支持 4 种最常用方式：

`@PathVariable`

路径变量

从 URL 路径中提取参数（RESTful 标准用法）

@GetMapping("/{id}")
public User getUserById(@PathVariable Long id) { ... }
// 支持自定义名称：@PathVariable("userId") Long id

`@RequestParam`

请求参数

获取 URL 问号后的查询参数（?name=张三&age=20）

@GetMapping("/search")
public List<User> search(
    @RequestParam String name,
    @RequestParam(required = false, defaultValue = "0") Integer age
) { ... }

`@RequestBody`

请求体

接收 JSON 格式请求体，自动反序列化为 Java 对象

@PostMapping
public User createUser(@RequestBody User user) { ... }

`@RequestHeader`

请求头

获取 HTTP 请求头参数

@GetMapping("/header")
public String getToken(@RequestHeader("Authorization") String token) { ... }

响应处理

企业级标准用法

自动序列化

默认使用 Jackson 框架将 Java 对象 / 集合转为 JSON，无需手动处理。

精准控制响应

ResponseEntity<T>

推荐所有接口使用，可自定义：

HTTP 状态码
响应头
响应体

@PostMapping
public ResponseEntity<User> createUser(@RequestBody User user) {
    User savedUser = userService.save(user);
    // 201 状态码 + 响应数据
    return ResponseEntity.status(HttpStatus.CREATED).body(savedUser);
}

无返回值接口

@DeleteMapping("/{id}")
public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
    userService.delete(id);
    return ResponseEntity.noContent().build(); // 204 无内容
}

完整示例

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.List;

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

    // 依赖注入
    private final UserService userService;

    // 构造器注入（Spring 4.3+ 推荐）
    public UserController(UserService userService) {
        this.userService = userService;
    }

    // 1. 查询所有用户
    @GetMapping
    public ResponseEntity<List<User>> list() {
        return ResponseEntity.ok(userService.listAll());
    }

    // 2. 根据ID查询用户
    @GetMapping("/{id}")
    public ResponseEntity<User> getById(@PathVariable Long id) {
        return ResponseEntity.ok(userService.getById(id));
    }

    // 3. 新增用户
    @PostMapping
    public ResponseEntity<User> create(@RequestBody User user) {
        return ResponseEntity.status(HttpStatus.CREATED).body(userService.save(user));
    }

    // 4. 全量更新用户
    @PutMapping("/{id}")
    public ResponseEntity<User> update(@PathVariable Long id, @RequestBody User user) {
        return ResponseEntity.ok(userService.update(id, user));
    }

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

总结

@RestController = @Controller + @ResponseBody，自动返回 JSON 数据
核心配套：请求映射注解、参数绑定、ResponseEntity 响应
企业开发必须搭配：统一响应体、全局异常处理、参数校验
是 Spring Boot 构建 RESTful API 的唯一标准注解