网站导航
> 技术文档 > Spring 中的 @RestController 注解详解

Spring 中的 @RestController 注解详解

网友: 技术文档 2025-07-30 11:59:58

@RestController 是 Spring MVC 中常用的注解，通常用于构建 RESTful Web 服务。它是 @Controller 和 @ResponseBody 的组合，简化了开发 RESTful 接口的流程。

本文将详细介绍 @RestController 的使用场景、原理以及具体案例。

1. @RestController 的作用

@RestController 的主要作用是将类标记为一个 RESTful 控制器。

  • 类中的每个方法返回的数据会直接写入 HTTP 响应体（Response Body）。
  • 默认不需要额外使用 @ResponseBody 注解。

简而言之：@RestController 自动将方法返回的对象序列化为 JSON 或 XML 格式。

2. @RestController 与 @Controller 的区别

特性 @RestController @Controller 返回值默认行为 数据直接写入响应体（默认返回 JSON）。 视图解析，返回页面模板（如 JSP、HTML）。 是否需要 @ResponseBody 不需要额外标注，自动序列化返回值。 若需返回数据而非页面，需要加 @ResponseBody。

示例：

  • @RestController 示例

    @RestControllerpublic class UserController { @GetMapping(\"/user\") public User getUser() { return new User(\"John\", 25); }}

    返回结果为 JSON：

    { \"name\": \"John\", \"age\": 25}

  • @Controller 示例

    @Controllerpublic class PageController { @GetMapping(\"/page\") public String getPage() { return \"home\"; // 返回页面模板名称，如 home.html }}

3. 如何使用 @RestController

3.1 基本使用

以下是一个完整的使用案例，展示如何创建一个返回 JSON 数据的接口。

实体类
public class User { private String name; private int age; public User(String name, int age) { this.name = name; this.age = age; } // Getters and Setters public String getName() { return name; } public void setName(String name) { this.name = name; } public int getAge() { return age; } public void setAge(int age) { this.age = age; }}
控制器类
import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RestController;@RestController@RequestMapping(\"/api\")public class UserController { @GetMapping(\"/user\") public User getUser() { return new User(\"Alice\", 30); }}
启动类

确保项目启动时，Spring Boot 能扫描到 @RestController 标注的类。

import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;@SpringBootApplicationpublic class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); }}

结果：
访问 http://localhost:8080/api/user，将返回：

{ \"name\": \"Alice\", \"age\": 30}
3.2 参数传递
通过 URL 参数
@RestController@RequestMapping(\"/api\")public class UserController { @GetMapping(\"/user\") public String getUserByName(@RequestParam String name) { return \"Hello, \" + name; }}

访问 http://localhost:8080/api/user?name=Tom，返回：

Hello, Tom
通过路径变量
@RestController@RequestMapping(\"/api\")public class UserController { @GetMapping(\"/user/{id}\") public String getUserById(@PathVariable int id) { return \"User ID: \" + id; }}

访问 http://localhost:8080/api/user/123，返回：

User ID: 123
3.3 POST 请求

在 RESTful 接口中，POST 通常用于创建资源。以下是处理 POST 请求的示例：

import org.springframework.web.bind.annotation.*;@RestController@RequestMapping(\"/api\")public class UserController { @PostMapping(\"/user\") public String createUser(@RequestBody User user) { return \"User \" + user.getName() + \" created successfully!\"; }}

测试请求：
发送以下 JSON 数据到 http://localhost:8080/api/user：

{ \"name\": \"John\", \"age\": 28}

返回结果：

User John created successfully!

4. 常见注解组合

4.1 @RequestMapping

@RequestMapping 用于定义请求路径，可以与 @RestController 配合使用：

@RestController@RequestMapping(\"/api\")public class UserController { @GetMapping(\"/hello\") public String sayHello() { return \"Hello, World!\"; }}

访问路径为 http://localhost:8080/api/hello。

4.2 @GetMapping、@PostMapping 等

简化了 HTTP 方法的映射：

  • @GetMapping：映射 GET 请求。
  • @PostMapping：映射 POST 请求。
  • @PutMapping：映射 PUT 请求。
  • @DeleteMapping：映射 DELETE 请求。

5. 最佳实践

  1. 使用统一的 API 前缀
    为 REST 接口添加统一的前缀（如 /api），便于接口管理：

    @RestController@RequestMapping(\"/api/v1\")public class UserController { ... }

  2. 返回自定义响应格式
    使用统一响应结构，便于前后端协作：

    public class ApiResponse { private int code; private String message; private T data; public ApiResponse(int code, String message, T data) { this.code = code; this.message = message; this.data = data; } // Getters and Setters}@RestController@RequestMapping(\"/api\")public class UserController { @GetMapping(\"/user\") public ApiResponse getUser() { User user = new User(\"Alice\", 30); return new ApiResponse(200, \"Success\", user); }}

  3. 异常处理
    通过 @RestControllerAdvice 实现全局异常处理：

    @RestControllerAdvicepublic class GlobalExceptionHandler { @ExceptionHandler(Exception.class) public ApiResponse handleException(Exception e) { return new ApiResponse(500, \"Internal Server Error\", e.getMessage()); }}

6. 总结

@RestController 是 Spring 提供的 RESTful Web 开发核心注解，它大大简化了返回 JSON 数据的接口开发流程。通过结合其他注解（如 @GetMapping、@PostMapping），开发者可以快速构建强大、灵活的 RESTful API。

如果你刚开始接触 Spring MVC 或 RESTful 开发，@RestController 是你学习的重要一环！

网络标签：

相关问题