Springboot3 | 核心注解实战教程

张较瘦_2026-01-04 20:14

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 复制代码 
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="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 注解标记。

java 复制代码 
package com.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * Spring Boot 3 主启动类
 * @SpringBootApplication：入口注解，整合 @Configuration、@EnableAutoConfiguration、@ComponentScan
 */
@SpringBootApplication
public class AnnotationDemoApplication {
    public static void main(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。

java 复制代码 
package com.example.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * 自定义配置类
 * @Configuration：标记为 Spring 3 配置类，替代传统 xml 配置
 */
@Configuration
public class UserConfig {

    /**
     * @Bean：将方法返回值注入到 Spring 容器中，Bean 名称默认是方法名
     * 此处注入一个用户编号生成工具 Bean
     */
    @Bean
    public UserIdGenerator userIdGenerator() {
        return new UserIdGenerator();
    }

    /**
     * 自定义用户编号生成工具类
     */
    public static class UserIdGenerator {
        private static long id = 1000L;

        // 生成自增用户编号
        public long generateId() {
            return id++;
        }
    }
}

步骤 4：编写用户实体类

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

java 复制代码 
package com.example.entity;

/**
 * 用户实体类
 * 用于封装用户信息，对应前端请求体和后端响应体数据
 */
public class User {
    private Long id;         // 用户编号
    private String username; // 用户名
    private Integer age;     // 年龄
    private String email;    // 邮箱

    // 无参构造器（@RequestBody 绑定数据时必须提供，Spring Boot 3 严格要求）
    public User() {
    }

    // 有参构造器
    public User(Long id, String username, Integer age, String email) {
        this.id = id;
        this.username = username;
        this.age = age;
        this.email = email;
    }

    // Getter 和 Setter 方法（必须提供，否则 JSON 序列化/反序列化失败）
    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    // toString 方法（便于打印日志）
    @Override
    public String toString() {
        return "User{" +
                "id=" + id +
                ", username='" + username + '\'' +
                ", age=" + age +
                ", email='" + email + '\'' +
                '}';
    }
}

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

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

java 复制代码 
package com.example.service;

import com.example.config.UserConfig;
import com.example.entity.User;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.HashMap;
import java.util.Map;

/**
 * 用户服务层
 * @Service：标记为 Spring 3 服务层 Bean，会被 @ComponentScan 扫描并注入容器
 */
@Service
public class UserService {

    // 模拟用户数据库存储
    private static Map<Long, User> userMap = new HashMap<>();

    /**
     * @Autowired：自动注入 Spring 容器中的 UserIdGenerator Bean
     * Spring Boot 3 支持字段注入、构造器注入（推荐）、setter 注入
     */
    @Autowired
    private UserConfig.UserIdGenerator userIdGenerator;

    /**
     * 新增用户
     * @param user 前端传入的用户信息（不含 id）
     * @return 新增后的完整用户信息（包含自动生成的 id）
     */
    public User addUser(User user) {
        // 生成自增用户编号
        long userId = userIdGenerator.generateId();
        user.setId(userId);
        // 存入模拟数据库
        userMap.put(userId, user);
        return user;
    }

    /**
     * 根据用户编号查询用户
     * @param userId 用户编号
     * @return 对应的用户信息
     */
    public User getUserById(Long userId) {
        return userMap.get(userId);
    }
}

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

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

java 复制代码 
package com.example.controller;

import com.example.entity.User;
import com.example.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

/**
 * 用户接口控制器
 * @RestController：复合注解（@Controller + @ResponseBody），所有方法返回 JSON 数据
 * @CrossOrigin：允许跨域请求，标注在类上表示所有方法都支持跨域
 */
@RestController
@CrossOrigin(origins = "*") // 允许所有域名跨域（开发环境使用，生产环境可指定具体域名）
@RequestMapping("/api/user") // 统一接口前缀
public class UserController {

    /**
     * @Autowired：自动注入 UserService Bean
     */
    @Autowired
    private UserService userService;

    /**
     * 新增用户接口
     * @PostMapping：映射 POST 请求，路径为 /add（完整路径：/api/user/add）
     * @RequestBody：将前端 JSON 请求体绑定到 User 参数对象
     */
    @PostMapping("/add")
    public User addUser(@RequestBody User user) {
        System.out.println("接收前端新增用户请求：" + user);
        User newUser = userService.addUser(user);
        System.out.println("新增用户成功：" + newUser);
        return newUser;
    }

    /**
     * 根据用户编号查询用户接口
     * @GetMapping：映射 GET 请求，路径为 /get/{userId}（完整路径：/api/user/get/{userId}）
     * @PathVariable：获取 URL 路径中的 userId 参数
     */
    @GetMapping("/get/{userId}")
    public User getUserById(@PathVariable Long userId) {
        System.out.println("接收前端查询用户请求，用户编号：" + userId);
        User user = userService.getUserById(userId);
        System.out.println("查询用户结果：" + user);
        return user;
    }

    /**
     * 演示 @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 格式）：

      json 复制代码 
      {
    "username": "张三",
    "age": 25,
    "email": "zhangsan@example.com"
}

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

      json 复制代码 
      {
    "id": 1000,
    "username": "张三",
    "age": 25,
    "email": "zhangsan@example.com"
}

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

    • 请求地址：http://localhost:8080/api/user/get/1000

    • 请求方式：GET

    • 响应结果：

      json 复制代码 
      {
    "id": 1000,
    "username": "张三",
    "age": 25,
    "email": "zhangsan@example.com"
}
方式 2：使用 curl 命令测试

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

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

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

    bash 复制代码 
    curl http://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 构建，可直接复制运行，你可以在此基础上扩展修改用户、删除用户等接口，进一步巩固注解的使用。

相关推荐
太理摆烂哥1 天前
C++之异常
java·开发语言·jvm
pe7er1 天前
如何阅读英文文档
java·前端·后端
期待のcode1 天前
java异常
java·开发语言
勇往直前plus1 天前
Python 类与实例对象的内存存储
java·开发语言·python
java_t_t1 天前
Java属性解析映射到Json
java·json
先做个垃圾出来………1 天前
Python位运算及操作
java·前端·python
你怎么知道我是队长1 天前
C语言---字符串
java·c语言·算法
rannn_1111 天前
【Java项目】中北大学Java大作业|电商平台
java·git·后端·课程设计·中北大学
资生算法程序员_畅想家_剑魔1 天前
Java常见技术分享-26-事务安全-锁机制-常见的锁实现
java·开发语言
热门推荐
01GitHub 镜像站点02手把手教你通过Gemini3 pro 学生认证，白用一年，手慢无！03安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）04Linux下V2Ray安装配置指南05Labelme从安装到标注：零基础完整指南06jdk21下载、安装（Windows、Linux、macOS）072025 最新教程：注册并切换到美区 Apple ID08GitLab 零基础入门指南：从安装到项目管理全流程09Figma MCP + Cursor 完全配置与使用指南：实现设计到代码的智能转换10Claude Code Skills 实用使用手册