SpringBoot @RestController注解用法及说明
更新时间：2025年10月30日 08:43:00 作者：cyforkk
@RestController是Spring Boot中用于构建RESTful Web服务的核心注解,它简化了RESTful服务的开发,该注解结合了@Controller和@ResponseBody的功能,使得控制器类中的所有请求处理方法的返回值会自动序列化为JSON/XML格式并写入HTTP响应体中
SpringBoot @RestController注解
@RestController 是 Spring Boot 中用于构建 RESTful Web 服务的核心注解，它将控制器类标记为 REST API 的入口点，简化了 RESTful 服务的开发。
概述
@RestController 是一个组合注解，它结合了 @Controller 和 @ResponseBody 的功能。
使用该注解的类中所有请求处理方法都会自动将返回值序列化为 JSON/XML 格式并写入 HTTP 响应体中。
基本语法结构
@RestController
@RequestMapping("基础路径")
public class ControllerName {
@GetMapping("/路径")
public ReturnType methodName(@RequestParam 参数类型 参数名) {
// 处理逻辑
return 返回值;
}
}
核心特性
1. 组合注解特性
@RestController 相当于同时使用了 @Controller 和 @ResponseBody：
// 使用 @RestController（推荐）
@RestController
public class RoomController {
@GetMapping("/room")
public RoomEntity getRoom() {
return new RoomEntity();
}
}
// 等价于下面的传统写法
@Controller
@ResponseBody
public class RoomController {
@GetMapping("/room")
public RoomEntity getRoom() {
return new RoomEntity();
}
}
2. 自动序列化返回值
所有方法返回值自动转换为 JSON/XML 格式：
@RestController
@RequestMapping("/api/rooms")
public class RoomController {
// 返回对象自动序列化为 JSON
@GetMapping("/{id}")
public RoomEntity getRoom(@PathVariable Long id) {
RoomEntity room = new RoomEntity();
room.setId(id);
room.setName("会议室");
return room; // 自动转换为 JSON: {"id": 1, "name": "会议室"}
}
// 返回集合也自动序列化
@GetMapping
public List<RoomEntity> getAllRooms() {
return Arrays.asList(new RoomEntity(), new RoomEntity());
}
}
常用详解
1. 基本使用方式
@RestController
@RequestMapping("/api/rooms")
public class RoomController {
@Autowired
private RoomService roomService;
// GET /api/rooms - 获取房间列表
@GetMapping
public ResponseEntity<List<RoomEntity>> getAllRooms() {
List<RoomEntity> rooms = roomService.findAll();
return ResponseEntity.ok(rooms);
}
// GET /api/rooms/1 - 获取特定房间
@GetMapping("/{id}")
public ResponseEntity<RoomEntity> getRoom(@PathVariable Long id) {
RoomEntity room = roomService.findById(id);
return ResponseEntity.ok(room);
}
// POST /api/rooms - 创建新房间
@PostMapping
public ResponseEntity<RoomEntity> createRoom(@RequestBody RoomEntity room) {
RoomEntity savedRoom = roomService.save(room);
return ResponseEntity.status(HttpStatus.CREATED).body(savedRoom);
}
}
2. 与 HTTP 方法注解配合
@RestController
@RequestMapping("/api/users")
public class UserController {
// GET 请求 - 查询数据
@GetMapping
public List<User> getUsers() {
return userService.findAll();
}
// GET 请求 - 根据 ID 查询
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
return userService.findById(id);
}
// POST 请求 - 创建资源
@PostMapping
public User createUser(@RequestBody User user) {
return userService.save(user);
}
// PUT 请求 - 更新整个资源
@PutMapping("/{id}")
public User updateUser(@PathVariable Long id, @RequestBody User user) {
return userService.update(id, user);
}
// PATCH 请求 - 部分更新资源
@PatchMapping("/{id}")
public User patchUser(@PathVariable Long id, @RequestBody Map<String, Object> updates) {
return userService.partialUpdate(id, updates);
}
// DELETE 请求 - 删除资源
@DeleteMapping("/{id}")
public void deleteUser(@PathVariable Long id) {
userService.deleteById(id);
}
}
关键说明
1. 与 @Controller 的区别
// @Controller - 通常用于返回视图名称
@Controller
public class WebController {
@GetMapping("/page")
public String getPage() {
return "index"; // 返回视图名称
}
}
// @RestController - 用于返回数据
@RestController
public class ApiController {
@GetMapping("/api/data")
public Map<String, Object> getData() {
return Map.of("message", "Hello World"); // 返回 JSON 数据
}
}
2. 返回值处理机制
@RestController
public class DataController {
// 1. 返回简单对象
@GetMapping("/string")
public String getString() {
return "Hello World"; // 返回字符串
}
// 2. 返回复杂对象（自动转 JSON）
@GetMapping("/object")
public User getUser() {
return new User("张三", 25); // 转换为 {"name": "张三", "age": 25}
}
// 3. 返回集合
@GetMapping("/list")
public List<User> getUsers() {
return List.of(new User("张三", 25), new User("李四", 30));
}
// 4. 使用 ResponseEntity 提供更精确的控制
@GetMapping("/response")
public ResponseEntity<User> getResponseUser() {
User user = new User("王五", 28);
return ResponseEntity.ok()
.header("Custom-Header", "Value")
.body(user);
}
}
注意事项
1. 不要与视图解析混用
// 错误示例 - 不要在 @RestController 中返回视图名称
@RestController
public class WrongController {
@GetMapping("/page")
public String getPage() {
return "index"; // 这会返回字符串 "index" 而不是视图
}
}
// 正确示例 - 使用 @Controller 处理视图
@Controller
public class ViewController {
@GetMapping("/page")
public String getPage() {
return "index"; // 返回视图名称
}
}
2. 异常处理
@RestController
public class RoomController {
@GetMapping("/{id}")
public RoomEntity getRoom(@PathVariable Long id) {
RoomEntity room = roomService.findById(id);
if (room == null) {
// 应使用统一异常处理机制
throw new RoomNotFoundException("Room not found: " + id);
}
return room;
}
}
// 统一异常处理
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(RoomNotFoundException.class)
public ResponseEntity<ErrorResponse> handleRoomNotFound(RoomNotFoundException e) {
ErrorResponse error = new ErrorResponse("ROOM_NOT_FOUND", e.getMessage());
return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
}
}
实用技巧
1. 统一响应格式
@RestController
public class RoomController {
// 定义统一响应结构
@GetMapping("/{id}")
public ApiResponse<RoomEntity> getRoom(@PathVariable Long id) {
RoomEntity room = roomService.findById(id);
return ApiResponse.success(room);
}
}
// 统一响应类
public class ApiResponse<T> {
private int code;
private String message;
private T data;
public static <T> ApiResponse<T> success(T data) {
ApiResponse<T> response = new ApiResponse<>();
response.code = 0;
response.message = "success";
response.data = data;
return response;
}
}
2. 版本控制
@RestController
@RequestMapping("/api/v1/rooms") // API 版本控制
public class RoomControllerV1 {
// v1 版本的实现
}
@RestController
@RequestMapping("/api/v2/rooms") // API 版本控制
public class RoomControllerV2 {
// v2 版本的实现
}
3. 分组管理
@RestController
@RequestMapping("/api/admin/rooms") // 管理员接口
public class AdminRoomController {
// 管理员专用接口
}
@RestController
@RequestMapping("/api/public/rooms") // 公共接口
public class PublicRoomController {
// 公共可访问接口
}
命名规范建议
1. 控制器类命名
// 推荐命名方式 - 资源名 + Controller
@RestController
public class RoomController { }
@RestController
public class UserController { }
@RestController
public class OrderController { }
2. 路径命名规范
@RestController
@RequestMapping("/api/v1/rooms") // 复数形式
public class RoomController { }
@RestController
@RequestMapping("/api/v1/room-types") // 多个单词使用连字符
public class RoomTypeController { }
总结：核心要点速览
| 特性 | 说明 |
|---|---|
| 主要用途 | 标记 RESTful API 控制器类 |
| 组合注解 | 等价于 @Controller + @ResponseBody |
| 自动序列化 | 方法返回值自动转换为 JSON/XML |
| 适用场景 | 构建 REST API，不适用于视图渲染 |
| 路径映射 | 通常与 @RequestMapping 配合使用 |
| 方法注解 | 配合 @GetMapping、@PostMapping 等 |
| 返回处理 | 支持对象、集合、ResponseEntity 等类型 |
| 最佳实践 | 遵循 RESTful 设计原则，统一响应格式 |
通过合理使用 @RestController 注解，可以快速构建功能完善、规范统一的 RESTful API 服务，是现代 Web 应用开发中不可或缺的重要组件。
以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。
相关文章
Springcloud整合stream,rabbitmq实现消息驱动功能
官方定义SpringCloud Stream 是一个构建消息驱动微服务的框架。我们只需要搞清楚如何与Spring Cloud Stream 交互就可以方便使用消息驱动的方式。本文将通过Springcloud整合stream,rabbitmq实现消息驱动功能，需要的可以参考一下2022-02-02
这篇文章主要介绍了理解Java面向对象编程设计，面向对象编程是一种编程思维方式和编码架构。下面详细内容，需要的小伙伴可以参考一下2022-01-01
这篇文章主要介绍了Spring.Net在MVC中实现注入的原理解析,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下2019-09-09
大数据量查询慢常因全表扫描、分页不当、索引缺失、内存占用高及ORM开销,优化措施包括分页查询、流式读取、SQL优化、批处理、多数据源、结果集二次处理及配置调优2025-09-09
shrio中hashedCredentialsMatcher密码匹配示例详解
shrio是一个轻量级权限管理框架，密码的匹配由框架内部完成。密码是否匹配由接口CredentialsMatcher定义实现类完成，CredentialsMatcher实现类有SimpleCredentialsMatcher和HashedCredentialsMatcher两个2021-10-10
在本篇文章里小编给各位整理一篇关于java中如何实现对类的对象进行排序知识点内容，有兴趣的朋友们可以学习下。2020-02-02
这篇文章主要为大家详细介绍了Java2 JDK安装和配置教程,具有一定的参考价值，感兴趣的小伙伴们可以参考一下2016-11-11
这篇文章主要介绍了关于ReentrantLock的原理解析，文章通过代码示例介绍的非常详细，具有一定的参考价值,需要的朋友可以参考下2023-07-07
这篇文章主要介绍了Java之Error与Exception的区别案例详解,本篇文章通过简要的案例,讲解了该项技术的了解与使用,以下就是详细内容,需要的朋友可以参考下2021-09-09
SpringBoot配置优先级按来源排序,15种类型中命令行参数最高,配置文件次之,classpath下config目录的配置优先级高于jar内文件,配置中心如Nacos的配置则插入列表前端,所有配置最终存入Environment的propertySources,通过顺序遍历实现覆盖2025-07-07
最新评论