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<T> {
        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<User> getUser() {
            User user = new User("Alice", 30);
            return new ApiResponse<>(200, "Success", user);
        }
    }
  3. 异常处理

    通过 @RestControllerAdvice 实现全局异常处理:

    复制代码
    @RestControllerAdvice
    public class GlobalExceptionHandler {
        @ExceptionHandler(Exception.class)
        public ApiResponse<String> 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 是你学习的重要一环!

相关推荐
nice_lcj52028 分钟前
【从零理解计算机网络 · 02】分层模型:别背 OSI 七层,看数据怎么被“打包“和“拆包“
java·后端·tcp/ip·计算机网络·面试·osi·分层模型
SimonKing1 小时前
给Deepseek Harness装上插件市场,从此插件无忧
java·后端·程序员
艾莉丝努力练剑2 小时前
【AI大模型接入SDK】C++的SessionManager 线程安全
java·开发语言·前端·c++·人工智能·学习·安全
aiotto资源分享2 小时前
Python 写 JSON 文件,程序中途退出会留下什么?
java·python·json·jsondecodeerror
利威尔xu2 小时前
Go Mutex 饥饿模式:正常模式等待者饿死,1ms 阈值自动切换崩溃
开发语言·后端·面试·golang·并发编程
一条Go2 小时前
边缘 Agent:为什么是它连出来,而不是平台连进去
后端·架构·github
RuoyiOffice3 小时前
SpringBoot3+Vue3 采购到付款:ERP、WMS与财务如何按同一来源协同
java·spring boot·架构·vue
huangfuyk3 小时前
前端融入/转后端避坑指南:AI 时代的安全边界、数据防线与实战细节
后端·ai编程
文丑颜不良啊3 小时前
LeetCode3261~3280题目解析
java·leetcode
代码不停3 小时前
Spring 原理
java·spring