SpringBoot @RestController注解用法及說(shuō)明
更新時(shí)間：2025年10月30日 08:43:00 作者：cyforkk
@RestController是Spring Boot中用于構(gòu)建RESTful Web服務(wù)的核心注解,它簡(jiǎn)化了RESTful服務(wù)的開發(fā),該注解結(jié)合了@Controller和@ResponseBody的功能,使得控制器類中的所有請(qǐng)求處理方法的返回值會(huì)自動(dòng)序列化為JSON/XML格式并寫入HTTP響應(yīng)體中
SpringBoot @RestController注解
@RestController 是 Spring Boot 中用于構(gòu)建 RESTful Web 服務(wù)的核心注解，它將控制器類標(biāo)記為 REST API 的入口點(diǎn)，簡(jiǎn)化了 RESTful 服務(wù)的開發(fā)。
概述
@RestController 是一個(gè)組合注解，它結(jié)合了 @Controller 和 @ResponseBody 的功能。
使用該注解的類中所有請(qǐng)求處理方法都會(huì)自動(dòng)將返回值序列化為 JSON/XML 格式并寫入 HTTP 響應(yīng)體中。
基本語(yǔ)法結(jié)構(gòu)
@RestController
@RequestMapping("基礎(chǔ)路徑")
public class ControllerName {
@GetMapping("/路徑")
public ReturnType methodName(@RequestParam 參數(shù)類型 參數(shù)名) {
// 處理邏輯
return 返回值;
}
}
核心特性
1. 組合注解特性
@RestController 相當(dāng)于同時(shí)使用了 @Controller 和 @ResponseBody：
// 使用 @RestController（推薦）
@RestController
public class RoomController {
@GetMapping("/room")
public RoomEntity getRoom() {
return new RoomEntity();
}
}
// 等價(jià)于下面的傳統(tǒng)寫法
@Controller
@ResponseBody
public class RoomController {
@GetMapping("/room")
public RoomEntity getRoom() {
return new RoomEntity();
}
}
2. 自動(dòng)序列化返回值
所有方法返回值自動(dòng)轉(zhuǎn)換為 JSON/XML 格式：
@RestController
@RequestMapping("/api/rooms")
public class RoomController {
// 返回對(duì)象自動(dòng)序列化為 JSON
@GetMapping("/{id}")
public RoomEntity getRoom(@PathVariable Long id) {
RoomEntity room = new RoomEntity();
room.setId(id);
room.setName("會(huì)議室");
return room; // 自動(dòng)轉(zhuǎn)換為 JSON: {"id": 1, "name": "會(huì)議室"}
}
// 返回集合也自動(dòng)序列化
@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 請(qǐng)求 - 查詢數(shù)據(jù)
@GetMapping
public List<User> getUsers() {
return userService.findAll();
}
// GET 請(qǐng)求 - 根據(jù) ID 查詢
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
return userService.findById(id);
}
// POST 請(qǐng)求 - 創(chuàng)建資源
@PostMapping
public User createUser(@RequestBody User user) {
return userService.save(user);
}
// PUT 請(qǐng)求 - 更新整個(gè)資源
@PutMapping("/{id}")
public User updateUser(@PathVariable Long id, @RequestBody User user) {
return userService.update(id, user);
}
// PATCH 請(qǐng)求 - 部分更新資源
@PatchMapping("/{id}")
public User patchUser(@PathVariable Long id, @RequestBody Map<String, Object> updates) {
return userService.partialUpdate(id, updates);
}
// DELETE 請(qǐng)求 - 刪除資源
@DeleteMapping("/{id}")
public void deleteUser(@PathVariable Long id) {
userService.deleteById(id);
}
}
關(guān)鍵說(shuō)明
1. 與 @Controller 的區(qū)別
// @Controller - 通常用于返回視圖名稱
@Controller
public class WebController {
@GetMapping("/page")
public String getPage() {
return "index"; // 返回視圖名稱
}
}
// @RestController - 用于返回?cái)?shù)據(jù)
@RestController
public class ApiController {
@GetMapping("/api/data")
public Map<String, Object> getData() {
return Map.of("message", "Hello World"); // 返回 JSON 數(shù)據(jù)
}
}
2. 返回值處理機(jī)制
@RestController
public class DataController {
// 1. 返回簡(jiǎn)單對(duì)象
@GetMapping("/string")
public String getString() {
return "Hello World"; // 返回字符串
}
// 2. 返回復(fù)雜對(duì)象（自動(dòng)轉(zhuǎn) JSON）
@GetMapping("/object")
public User getUser() {
return new User("張三", 25); // 轉(zhuǎn)換為 {"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);
}
}
注意事項(xiàng)
1. 不要與視圖解析混用
// 錯(cuò)誤示例 - 不要在 @RestController 中返回視圖名稱
@RestController
public class WrongController {
@GetMapping("/page")
public String getPage() {
return "index"; // 這會(huì)返回字符串 "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) {
// 應(yīng)使用統(tǒng)一異常處理機(jī)制
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);
}
}
實(shí)用技巧
1. 統(tǒng)一響應(yīng)格式
@RestController
public class RoomController {
// 定義統(tǒng)一響應(yīng)結(jié)構(gòu)
@GetMapping("/{id}")
public ApiResponse<RoomEntity> getRoom(@PathVariable Long id) {
RoomEntity room = roomService.findById(id);
return ApiResponse.success(room);
}
}
// 統(tǒng)一響應(yī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 版本的實(shí)現(xiàn)
}
@RestController
@RequestMapping("/api/v2/rooms") // API 版本控制
public class RoomControllerV2 {
// v2 版本的實(shí)現(xiàn)
}
3. 分組管理
@RestController
@RequestMapping("/api/admin/rooms") // 管理員接口
public class AdminRoomController {
// 管理員專用接口
}
@RestController
@RequestMapping("/api/public/rooms") // 公共接口
public class PublicRoomController {
// 公共可訪問(wèn)接口
}
命名規(guī)范建議
1. 控制器類命名
// 推薦命名方式 - 資源名 + Controller
@RestController
public class RoomController { }
@RestController
public class UserController { }
@RestController
public class OrderController { }
2. 路徑命名規(guī)范
@RestController
@RequestMapping("/api/v1/rooms") // 復(fù)數(shù)形式
public class RoomController { }
@RestController
@RequestMapping("/api/v1/room-types") // 多個(gè)單詞使用連字符
public class RoomTypeController { }
總結(jié)：核心要點(diǎn)速覽
| 特性 | 說(shuō)明 |
|---|---|
| 主要用途 | 標(biāo)記 RESTful API 控制器類 |
| 組合注解 | 等價(jià)于 @Controller + @ResponseBody |
| 自動(dòng)序列化 | 方法返回值自動(dòng)轉(zhuǎn)換為 JSON/XML |
| 適用場(chǎng)景 | 構(gòu)建 REST API，不適用于視圖渲染 |
| 路徑映射 | 通常與 @RequestMapping 配合使用 |
| 方法注解 | 配合 @GetMapping、@PostMapping 等 |
| 返回處理 | 支持對(duì)象、集合、ResponseEntity 等類型 |
| 最佳實(shí)踐 | 遵循 RESTful 設(shè)計(jì)原則，統(tǒng)一響應(yīng)格式 |
通過(guò)合理使用 @RestController 注解，可以快速構(gòu)建功能完善、規(guī)范統(tǒng)一的 RESTful API 服務(wù)，是現(xiàn)代 Web 應(yīng)用開發(fā)中不可或缺的重要組件。
以上為個(gè)人經(jīng)驗(yàn)，希望能給大家一個(gè)參考，也希望大家多多支持腳本之家。
您可能感興趣的文章:
- springboot中@RestController注解實(shí)現(xiàn)
- SpringBoot中@RestControllerAdvice注解的使用
- SpringBoot中@RestControllerAdvice注解實(shí)現(xiàn)全局異常處理類
- SpringBoot常用注解@RestControllerAdvice詳解
- SpringBoot中的@RestControllerAdvice注解詳解
- SpringBoot?@RestControllerAdvice注解對(duì)返回值統(tǒng)一封裝的處理方法
- SpringBoot http請(qǐng)求注解@RestController原理解析
相關(guān)文章
Springcloud整合stream,rabbitmq實(shí)現(xiàn)消息驅(qū)動(dòng)功能
官方定義SpringCloud?Stream?是一個(gè)構(gòu)建消息驅(qū)動(dòng)微服務(wù)的框架。我們只需要搞清楚如何與Spring?Cloud?Stream?交互就可以方便使用消息驅(qū)動(dòng)的方式。本文將通過(guò)Springcloud整合stream,rabbitmq實(shí)現(xiàn)消息驅(qū)動(dòng)功能，需要的可以參考一下2022-02-02
這篇文章主要介紹了理解Java面向?qū)ο缶幊淘O(shè)計(jì)，面向?qū)ο缶幊淌且环N編程思維方式和編碼架構(gòu)。下面詳細(xì)內(nèi)容，需要的小伙伴可以參考一下2022-01-01
Spring.Net在MVC中實(shí)現(xiàn)注入的原理解析
這篇文章主要介紹了Spring.Net在MVC中實(shí)現(xiàn)注入的原理解析,文中通過(guò)示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友可以參考下2019-09-09
MyBatis Plus大數(shù)據(jù)量查詢慢原因分析及解決
大數(shù)據(jù)量查詢慢常因全表掃描、分頁(yè)不當(dāng)、索引缺失、內(nèi)存占用高及ORM開銷,優(yōu)化措施包括分頁(yè)查詢、流式讀取、SQL優(yōu)化、批處理、多數(shù)據(jù)源、結(jié)果集二次處理及配置調(diào)優(yōu)2025-09-09
shrio中hashedCredentialsMatcher密碼匹配示例詳解
shrio是一個(gè)輕量級(jí)權(quán)限管理框架，密碼的匹配由框架內(nèi)部完成。密碼是否匹配由接口CredentialsMatcher定義實(shí)現(xiàn)類完成，CredentialsMatcher實(shí)現(xiàn)類有SimpleCredentialsMatcher和HashedCredentialsMatcher兩個(gè)2021-10-10
java中如何實(shí)現(xiàn)對(duì)類的對(duì)象進(jìn)行排序
在本篇文章里小編給各位整理一篇關(guān)于java中如何實(shí)現(xiàn)對(duì)類的對(duì)象進(jìn)行排序知識(shí)點(diǎn)內(nèi)容，有興趣的朋友們可以學(xué)習(xí)下。2020-02-02
這篇文章主要為大家詳細(xì)介紹了Java2 JDK安裝和配置教程,具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2016-11-11
這篇文章主要介紹了關(guān)于ReentrantLock的原理解析，文章通過(guò)代碼示例介紹的非常詳細(xì)，具有一定的參考價(jià)值,需要的朋友可以參考下2023-07-07
Java之Error與Exception的區(qū)別案例詳解
這篇文章主要介紹了Java之Error與Exception的區(qū)別案例詳解,本篇文章通過(guò)簡(jiǎn)要的案例,講解了該項(xiàng)技術(shù)的了解與使用,以下就是詳細(xì)內(nèi)容,需要的朋友可以參考下2021-09-09
SpringBoot配置文件優(yōu)先級(jí)用法及解讀
SpringBoot配置優(yōu)先級(jí)按來(lái)源排序,15種類型中命令行參數(shù)最高,配置文件次之,classpath下config目錄的配置優(yōu)先級(jí)高于jar內(nèi)文件,配置中心如Nacos的配置則插入列表前端,所有配置最終存入Environment的propertySources,通過(guò)順序遍歷實(shí)現(xiàn)覆蓋2025-07-07