SpringBoot @RestController注解用法及說明
更新時間：2025年10月30日 08:43:00 作者：cyforkk
@RestController是Spring Boot中用于構建RESTful Web服務的核心注解,它簡化了RESTful服務的開發(fā),該注解結合了@Controller和@ResponseBody的功能,使得控制器類中的所有請求處理方法的返回值會自動序列化為JSON/XML格式并寫入HTTP響應體中
SpringBoot @RestController注解
@RestController 是 Spring Boot 中用于構建 RESTful Web 服務的核心注解，它將控制器類標記為 REST API 的入口點，簡化了 RESTful 服務的開發(fā)。
概述
@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();
}
}
// 等價于下面的傳統(tǒng)寫法
@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 - 創(chuàng)建新房間
@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 請求 - 創(chuàng)建資源
@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 的區(qū)別
// @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) {
// 應使用統(tǒng)一異常處理機制
throw new RoomNotFoundException("Room not found: " + id);
}
return room;
}
}
// 統(tǒng)一異常處理
@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. 統(tǒng)一響應格式
@RestController
public class RoomController {
// 定義統(tǒng)一響應結構
@GetMapping("/{id}")
public ApiResponse<RoomEntity> getRoom(@PathVariable Long id) {
RoomEntity room = roomService.findById(id);
return ApiResponse.success(room);
}
}
// 統(tǒng)一響應類
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 {
// 公共可訪問接口
}
命名規(guī)范建議
1. 控制器類命名
// 推薦命名方式 - 資源名 + Controller
@RestController
public class RoomController { }
@RestController
public class UserController { }
@RestController
public class OrderController { }
2. 路徑命名規(guī)范
@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 設計原則，統(tǒng)一響應格式 |
通過合理使用 @RestController 注解，可以快速構建功能完善、規(guī)范統(tǒng)一的 RESTful API 服務，是現代 Web 應用開發(fā)中不可或缺的重要組件。
以上為個人經驗，希望能給大家一個參考，也希望大家多多支持腳本之家。
相關文章
本文主要介紹了spring.datasource.schema配置，文中通過示例代碼介紹的非常詳細，具有一定的參考價值，感興趣的小伙伴們可以參考一下2022-05-05
這篇文章主要為大家詳細介紹了Java Spring Boot的一些高級用法，具有一定的參考價值，感興趣的小伙伴們可以參考一下，希望能夠給你帶來幫助2021-09-09
本文主要介紹了maven打包時配置多環(huán)境參數的實現,文中通過示例代碼介紹的非常詳細,對大家的學習或者工作具有一定的參考學習價值,需要的朋友們下面隨著小編來一起學習學習吧2025-04-04
這篇文章主要介紹了關于maven的用法和幾個常用的命令，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2022-10-10
這篇文章主要介紹了javaweb使用華為云短信通知公共類調用的操作，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2021-06-06
這篇文章主要介紹了java開源調度如何給xxljob加一個k8s執(zhí)行器，?xxljob?在設計上，抽象出了執(zhí)行器的接口，所以實現一個語言的執(zhí)行器并不復雜，這里主要探索下，如何利用k8s的pod?的能力，使用?xxljob?調度?pod?運行，實現一個通用的和語言無關的執(zhí)行器2022-02-02
java使用java.util.Date獲取指定日期的年、月、日、時、分、秒
在Java中獲取當前時間和日期是很常見的操作,也是很重要的操作,下面這篇文章主要給大家介紹了關于java使用java.util.Date獲取指定日期的年、月、日、時、分、秒的相關資料,需要的朋友可以參考下2024-01-01
Gradle是一個基于Apache Ant和Apache Maven概念的項目自動化構建開源工具。這篇文章主要介紹了Gradle 6.6.1 安裝配置的詳細教程,需要的朋友可以參考下2020-09-09
這篇文章主要介紹了使用自定義注解實現加解密及脫敏方式，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2021-12-12
如何自定義Mybatis-Plus分布式ID生成器(解決ID長度超過JavaScript整數安全范圍問題)
MyBatis-Plus默認生成的是 64bit 長整型,而 JS 的 Number 類型精度最高只有 53bit,這篇文章主要介紹了如何自定義Mybatis-Plus分布式ID生成器(解決ID長度超過JavaScript整數安全范圍問題),需要的朋友可以參考下2024-08-08