Spring 中的 @RestController 注解详解

@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 示例

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

    返回结果为 JSON：

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

  • @Controller 示例

    @Controller
    public 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;
    @SpringBootApplication
    public 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 实现全局异常处理：

         @RestControllerAdvice
         public 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 是你学习的重要一环！