Springboot3 | 核心注解实战教程

Spring Boot 核心注解实战教程

你是否在使用 Spring Boot 开发时，对着一堆注解不知所措？不清楚它们各自的职责、该在什么场景下使用？这篇教程将通过可直接运行的完整案例，带你吃透 Spring Boot 核心注解的作用与使用方式，让你真正做到学以致用。

在开始之前，你需对注解有初步认识，希望Java | 一文读懂Java注解：从生活标签到代码魔法可以帮到你。

一、教程概述

我们将先逐个拆解核心注解的作用，再搭建一个完整的 Spring Boot 3 Web 项目，把这些注解串联起来实战使用，最终实现一个支持跨域的用户信息查询与新增接口。

技术前置

• JDK 17 及以上（Spring Boot 3 最低要求 JDK 17）
• Maven 3.6 及以上
• Spring Boot 3.2.x（稳定版，本教程使用 3.2.1）

二、核心注解作用详解

1.@SpringBootApplication

• 作用：Spring Boot 项目的入口注解，用于标记主启动类。它是一个复合注解，整合了@Configuration（配置类标记）、@EnableAutoConfiguration（自动配置）、@ComponentScan（组件扫描）三个注解的功能，无需手动配置这三个注解即可开启 Spring Boot 3 的核心特性。
• 使用场景：唯一作用就是标注在 Spring Boot 项目的主类上，作为项目启动的入口标识。

2.@Configuration

• 作用：标记一个类为Spring 配置类，相当于传统 Spring 中的applicationContext.xml配置文件。在该类中，可以通过@Bean注解将自定义对象注入到 Spring 容器中，交由 Spring 统一管理（单例默认）。
• 使用场景：需要手动配置自定义 Bean（如工具类、第三方服务客户端等）时使用。

3.@Autowired

• 作用：实现自动依赖注入，Spring 会自动从容器中查找对应的 Bean 实例，并注入到当前类的字段、构造方法或 setter 方法中，无需手动创建对象，实现解耦。
• 使用场景：当一个类需要依赖另一个被 Spring 管理的 Bean 时（如 Service 依赖 Repository、Controller 依赖 Service），使用该注解自动注入。

4.@Controller

• 作用：标记一个类为Spring MVC 控制器类，负责接收前端发送的请求，进行请求分发和业务逻辑处理。默认情况下，该注解标记的方法返回值是视图名称（用于页面跳转）。
• 使用场景：传统前后端不分离项目（需要返回页面）时，标记控制器类。

5.@RestController

• 作用：复合注解，整合了@Controller和@ResponseBody。标记该注解的类，所有方法的返回值都会直接转换为 JSON/XML 格式的数据响应给前端，而不是视图名称。
• 使用场景：前后端分离项目（前端通过 Ajax/axios 请求数据）时，标记 API 接口控制器类（最常用）。

6.@ResponseBody

• 作用：将方法的返回值转换为 JSON/XML 格式的响应体，直接返回给前端，而不进行视图解析和页面跳转。
• 使用场景：在@Controller标记的类中，若某个方法需要返回数据而非页面时，可在该方法上添加此注解（补充@Controller的功能）。

7.@GetMapping

• 作用：用于映射GET 类型的 HTTP 请求，是@RequestMapping(method = RequestMethod.GET)的简化写法。指定前端请求的 URL 路径，当前端以 GET 方式请求该路径时，对应的方法会处理请求。
• 使用场景：查询数据（如查询用户列表、查询单个用户信息）时使用，GET 请求具有幂等性。

8.@PostMapping

• 作用：用于映射POST 类型的 HTTP 请求，是@RequestMapping(method = RequestMethod.POST)的简化写法。
• 使用场景：新增数据（如新增用户、新增订单）、提交表单（非幂等操作）时使用。

9.@RequestBody

• 作用：将前端发送的JSON/XML 格式的请求体数据，自动绑定到后端方法的参数对象中（需保证请求体字段与参数对象属性名一致，支持驼峰命名匹配）。
• 使用场景：前后端分离项目中，前端通过 POST/PUT 等方式提交 JSON 格式数据时，用于接收请求体数据。

10.@CrossOrigin

• 作用：解决跨域请求问题（当前端项目与后端项目不在同一域名、端口或协议时，会出现跨域拦截）。该注解可标注在类上（所有方法生效）或方法上（单个方法生效）。
• 使用场景：前后端分离项目（如前端 Vue 项目部署在http://localhost:8080，后端 Spring Boot 项目部署在http://localhost:9090），需要允许前端跨域请求时使用。

三、完整实战案例

步骤 1：创建 Maven 项目，添加依赖

在pom.xml中添加 Spring Boot 3 Web 核心依赖，Maven 会自动管理 Spring Boot 3 相关依赖版本。

<?xml version="1.0" encoding="UTF-8"?><projectxmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><!-- Spring Boot 3 父工程依赖 --><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.2.1</version><relativePath/></parent><groupId>com.example</groupId><artifactId>springboot3-annotation-demo</artifactId><version>1.0-SNAPSHOT</version><properties><java.version>17</java.version></properties><!-- 核心依赖：Spring Boot 3 Web --><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency></dependencies><!-- Spring Boot 3 打包插件 --><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><version>3.2.1</version></plugin></plugins></build></project>

步骤 2：编写主启动类（使用@SpringBootApplication）

创建com.example.AnnotationDemoApplication类，作为 Spring Boot 3 项目入口，使用@SpringBootApplication注解标记。

packagecom.example;importorg.springframework.boot.SpringApplication;importorg.springframework.boot.autoconfigure.SpringBootApplication;/** * Spring Boot 3 主启动类 * @SpringBootApplication：入口注解，整合 @Configuration、@EnableAutoConfiguration、@ComponentScan */@SpringBootApplicationpublicclassAnnotationDemoApplication{publicstaticvoidmain(String[]args){// 启动 Spring Boot 3 项目SpringApplication.run(AnnotationDemoApplication.class,args);System.out.println("Spring Boot 3 项目启动成功！访问地址：http://localhost:8080");}}

步骤 3：编写配置类（使用@Configuration）

创建com.example.config.UserConfig类，作为配置类，通过@Configuration标记，并用@Bean注入一个工具类 Bean。

packagecom.example.config;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;/** * 自定义配置类 * @Configuration：标记为 Spring 3 配置类，替代传统 xml 配置 */@ConfigurationpublicclassUserConfig{/** * @Bean：将方法返回值注入到 Spring 容器中，Bean 名称默认是方法名 * 此处注入一个用户编号生成工具 Bean */@BeanpublicUserIdGeneratoruserIdGenerator(){returnnewUserIdGenerator();}/** * 自定义用户编号生成工具类 */publicstaticclassUserIdGenerator{privatestaticlongid=1000L;// 生成自增用户编号publiclonggenerateId(){returnid++;}}}

步骤 4：编写用户实体类

创建com.example.entity.User类，用于接收和返回用户数据，兼容 Spring Boot 3 的 JSON 序列化/反序列化。

packagecom.example.entity;/** * 用户实体类 * 用于封装用户信息，对应前端请求体和后端响应体数据 */publicclassUser{privateLongid;// 用户编号privateStringusername;// 用户名privateIntegerage;// 年龄privateStringemail;// 邮箱// 无参构造器（@RequestBody 绑定数据时必须提供，Spring Boot 3 严格要求）publicUser(){}// 有参构造器publicUser(Longid,Stringusername,Integerage,Stringemail){this.id=id;this.username=username;this.age=age;this.email=email;}// Getter 和 Setter 方法（必须提供，否则 JSON 序列化/反序列化失败）publicLonggetId(){returnid;}publicvoidsetId(Longid){this.id=id;}publicStringgetUsername(){returnusername;}publicvoidsetUsername(Stringusername){this.username=username;}publicIntegergetAge(){returnage;}publicvoidsetAge(Integerage){this.age=age;}publicStringgetEmail(){returnemail;}publicvoidsetEmail(Stringemail){this.email=email;}// toString 方法（便于打印日志）@OverridepublicStringtoString(){return"User{"+"id="+id+", username='"+username+'\''+", age="+age+", email='"+email+'\''+'}';}}

步骤 5：编写服务层（使用@Autowired）

创建com.example.service.UserService类，用于处理业务逻辑，通过@Autowired注入配置类中的 Bean，兼容 Spring Boot 3 的依赖注入机制。

packagecom.example.service;importcom.example.config.UserConfig;importcom.example.entity.User;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.stereotype.Service;importjava.util.HashMap;importjava.util.Map;/** * 用户服务层 * @Service：标记为 Spring 3 服务层 Bean，会被 @ComponentScan 扫描并注入容器 */@ServicepublicclassUserService{// 模拟用户数据库存储privatestaticMap<Long,User>userMap=newHashMap<>();/** * @Autowired：自动注入 Spring 容器中的 UserIdGenerator Bean * Spring Boot 3 支持字段注入、构造器注入（推荐）、setter 注入 */@AutowiredprivateUserConfig.UserIdGeneratoruserIdGenerator;/** * 新增用户 * @param user 前端传入的用户信息（不含 id） * @return 新增后的完整用户信息（包含自动生成的 id） */publicUseraddUser(Useruser){// 生成自增用户编号longuserId=userIdGenerator.generateId();user.setId(userId);// 存入模拟数据库userMap.put(userId,user);returnuser;}/** * 根据用户编号查询用户 * @param userId 用户编号 * @return 对应的用户信息 */publicUsergetUserById(LonguserId){returnuserMap.get(userId);}}

步骤 6：编写控制器层（使用 Web 相关注解）

创建com.example.controller.UserController类，作为 API 接口层，使用 Spring Boot 3 支持的 Web 注解处理前端请求。

packagecom.example.controller;importcom.example.entity.User;importcom.example.service.UserService;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.web.bind.annotation.*;/** * 用户接口控制器 * @RestController：复合注解（@Controller + @ResponseBody），所有方法返回 JSON 数据 * @CrossOrigin：允许跨域请求，标注在类上表示所有方法都支持跨域 */@RestController@CrossOrigin(origins="*")// 允许所有域名跨域（开发环境使用，生产环境可指定具体域名）@RequestMapping("/api/user")// 统一接口前缀publicclassUserController{/** * @Autowired：自动注入 UserService Bean */@AutowiredprivateUserServiceuserService;/** * 新增用户接口 * @PostMapping：映射 POST 请求，路径为 /add（完整路径：/api/user/add） * @RequestBody：将前端 JSON 请求体绑定到 User 参数对象 */@PostMapping("/add")publicUseraddUser(@RequestBodyUseruser){System.out.println("接收前端新增用户请求："+user);UsernewUser=userService.addUser(user);System.out.println("新增用户成功："+newUser);returnnewUser;}/** * 根据用户编号查询用户接口 * @GetMapping：映射 GET 请求，路径为 /get/{userId}（完整路径：/api/user/get/{userId}） * @PathVariable：获取 URL 路径中的 userId 参数 */@GetMapping("/get/{userId}")publicUsergetUserById(@PathVariableLonguserId){System.out.println("接收前端查询用户请求，用户编号："+userId);Useruser=userService.getUserById(userId);System.out.println("查询用户结果："+user);returnuser;}/** * 演示 @Controller + @ResponseBody 组合使用 * （若使用 @Controller 注解，单个方法返回 JSON 需添加 @ResponseBody） */// @Controller// @RequestMapping("/api/user")// public class TestController {// @Autowired// private UserService userService;//// @GetMapping("/get/{userId}")// @ResponseBody// public User getUserById(@PathVariable Long userId) {// return userService.getUserById(userId);// }// }}

四、运行与测试

步骤 1：启动项目

1. 确保你的开发环境已配置 JDK 17 及以上
2. 运行AnnotationDemoApplication类的main方法
3. 控制台输出Spring Boot 3 项目启动成功！访问地址：http://localhost:8080即表示启动成功

步骤 2：测试接口（两种方式可选）

方式 1：使用 Postman 测试

1. 测试新增用户接口（POST 请求）

   • 请求地址：http://localhost:8080/api/user/add
   • 请求方式：POST
   • 请求头：Content-Type: application/json
   • 请求体（JSON 格式）：

     {"username":"张三","age":25,"email":"zhangsan@example.com"}

   • 响应结果（自动生成 id=1000）：

     {"id":1000,"username":"张三","age":25,"email":"zhangsan@example.com"}

2. 测试查询用户接口（GET 请求）

   • 请求地址：http://localhost:8080/api/user/get/1000
   • 请求方式：GET
   • 响应结果：

     {"id":1000,"username":"张三","age":25,"email":"zhangsan@example.com"}

方式 2：使用 curl 命令测试

1. 新增用户（终端执行）：

   curl-XPOST-H"Content-Type: application/json"-d'{"username":"李四","age":28,"email":"lisi@example.com"}'http://localhost:8080/api/user/add

2. 查询用户（终端执行）：

   curlhttp://localhost:8080/api/user/get/1001

步骤 3：验证注解效果

• @SpringBootApplication：成功启动 Spring Boot 3 项目，无需额外配置；
• @Configuration+@Bean：成功注入UserIdGenerator工具类，实现 id 自增；
• @Autowired：成功注入UserIdGenerator和UserService，无需手动创建对象；
• @RestController：接口直接返回 JSON 数据，无需页面跳转；
• @PostMapping+@RequestBody：成功接收 JSON 请求体，新增用户；
• @GetMapping：成功接收 GET 请求，查询用户信息；
• @CrossOrigin：前端跨域请求时无拦截（可通过 Vue/React 项目测试）；
• @ResponseBody：若将@RestController替换为@Controller，添加该注解后同样返回 JSON 数据。

五、总结

通过本教程，你已经掌握了 Spring Boot 3 核心注解的核心作用与实战用法：

1. 项目入口：@SpringBootApplication（Spring Boot 3 主启动类必备）；
2. 配置管理：@Configuration（自定义 Bean 注入，替代 xml 配置）；
3. 依赖注入：@Autowired（自动获取 Spring 容器中的 Bean，实现解耦）；
4. Web 控制器：@Controller（返回页面）、@RestController（返回 JSON，前后端分离首选）；
5. 数据响应：@ResponseBody（将方法返回值转为 JSON 格式）；
6. 请求映射：@GetMapping（查询操作）、@PostMapping（新增操作）；
7. 数据接收：@RequestBody（接收 JSON 格式请求体）；
8. 跨域解决：@CrossOrigin（允许前端跨域请求）。

所有代码均基于 Spring Boot 3 构建，可直接复制运行，你可以在此基础上扩展修改用户、删除用户等接口，进一步巩固注解的使用。