源本科技 | 码上会

logo
源本科技 码上会
一站式数字化转型技能学习平台

Spring Boot 核心注解

2026/03/25
32
0

学习目标

  • 掌握 Spring Boot 启动类核心注解 @SpringBootApplication 的组成与作用。

  • 理解并区分组件扫描、依赖注入及业务分层相关的常用注解（如 @Component, @Service, @Autowired）。

  • 熟练运用 Web 层注解构建 RESTful API，包括请求映射、参数绑定及异常处理。

  • 了解配置属性绑定、数据校验及 JPA 持久层的关键注解用法。

为什么使用注解

在 Spring Boot 出现之前，Spring 框架严重依赖复杂的 XML 文件进行配置。注解（Annotations）的引入彻底改变了这一局面。注解是提供元数据的一种形式，它们指示 Spring 框架在运行时或编译时执行特定操作。

使用注解的主要优势包括：

  • 减少 XML 配置：将配置直接嵌入 Java 代码中，实现“配置即代码”。

  • 提升可读性与可维护性：开发者无需在多个文件间切换，逻辑更加直观。

  • 启用自动配置：配合 Spring Boot 的自动装配机制，极大简化了环境搭建。

  • 简化依赖注入：通过声明式方式管理对象依赖，降低耦合度。

  • 加速开发进程：让开发者专注于业务逻辑而非基础设施配置。

核心启动注解

@SpringBootApplication

这是 Spring Boot 应用程序的入口标志。它是一个组合注解，封装了三个关键功能，是启动类的标准配置。

它等价于同时使用以下三个注解：

  1. @SpringBootConfiguration：标识该类为配置类。

  2. @EnableAutoConfiguration：启用自动配置机制。

  3. @ComponentScan：启用组件扫描。

示例代码：

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        // 启动 Spring Boot 应用
        SpringApplication.run(DemoApplication.class, args);
    }
}

@SpringBootConfiguration

该注解表明一个类为 Spring Boot 应用程序提供配置。它是 @Configuration 的特化版本。通常不需要单独使用，因为它已经包含在 @SpringBootApplication 中。

@SpringBootConfiguration
public class AppConfig {
    // 配置内容
}

@EnableAutoConfiguration

这是 Spring Boot “魔法”的核心。它告诉 Spring Boot 根据类路径中的依赖项（如引入了 mysql-connector 或 spring-webmvc）和应用程序属性，自动配置相应的 Bean。

@EnableAutoConfiguration
public class AppConfig {
    // 自动配置生效
}

@ComponentScan

该注解指示 Spring 在指定的包路径下搜索带有组件注解（如 @Controller, @Service, @Repository）的类，并将它们注册为 Spring 容器中的 Bean。

// 扫描 com.example 包及其子包
@ComponentScan("com.example")
public class AppConfig {
}

Bean 注解

这些注解用于定义和管理 Spring 容器中的对象（Bean）。

@Component

最通用的注解，用于标记一个类为 Spring 管理的组件。在组件扫描过程中，Spring 会自动检测并注册此类。

@Component
public class EmailService {
    // 通用组件逻辑
}

@Service

专用于服务层（Business Layer）。虽然功能上与 @Component 相同，但使用 @Service 能更清晰地表达类的业务意图，提升代码可读性。

@Service
public class UserService {
    // 业务逻辑实现
}

@Repository

专用于数据访问层（DAO Layer）。除了标记数据访问组件外，它还有一个重要特性：能够自动将数据库相关的异常（如 SQLException）转换为 Spring 统一的 DataAccessException 体系。

@Repository
public class UserRepository {
    // 数据库交互逻辑
}

@Configuration

标识一个类包含 Spring 的配置信息和 Bean 定义。它是传统 XML 配置文件的现代替代品。

@Configuration
public class AppConfig {
    // 配置类
}

@Bean

通常与 @Configuration 配合使用，用于在配置类中显式定义一个 Bean。这给予了开发者对 Bean 创建过程和生命周期的完全控制权。

@Configuration
public class AppConfig {

    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

依赖注入注解

依赖注入是 Spring 的核心特性，以下注解用于自动化装配过程。

@Autowired

自动将所需的依赖注入到类、构造函数、字段或 setter 方法中，消除了手动 new 对象的需要。

@Autowired
private UserService userService;

@Qualifier

当容器中存在多个相同类型的 Bean 时，@Autowired 可能会产生歧义。@Qualifier 用于指定具体需要注入哪一个 Bean。

@Autowired
@Qualifier("emailService") // 明确指定注入名为 emailService 的 Bean
private NotificationService service;

@Primary

当存在多个同类型 Bean 且未使用 @Qualifier 指定时，被标记为 @Primary 的 Bean 将作为默认首选被注入。

@Primary
@Component
public class SmsService implements NotificationService {
    // 默认优先注入此实现
}

REST API 注解

构建 RESTful 服务是 Spring Boot 最常见的应用场景，以下注解至关重要。

@RestController

用于创建 RESTful Web 服务。它是 @Controller 和 @ResponseBody 的组合，意味着该类中的所有方法返回值都会直接序列化为 JSON 或 XML 格式，而不是视图名称。

@RestController
public class HelloController {
    // REST 接口定义
}

@RequestMapping

用于将 HTTP 请求映射到控制器类或具体方法上，定义处理请求的基础 URL 路径。

@RequestMapping("/api")
public class ApiController {
    // 所有方法路径都以 /api 开头
}

HTTP 方法专用注解

为了简化代码，Spring 提供了针对特定 HTTP 方法的快捷注解：

注解

对应 HTTP 方法

说明

@GetMapping

GET

从服务器检索数据

@PostMapping

POST

向服务器发送数据以创建资源

@PutMapping

PUT

更新现有资源

@DeleteMapping

DELETE

删除资源

示例：

@GetMapping("/users")
public List<User> getUsers() {
    return userService.getAllUsers();
}

@PathVariable

用于从 URI 路径中提取变量值，并将其绑定到方法参数上。常用于获取特定资源的 ID。

@GetMapping("/users/{id}")
public User getUser(@PathVariable int id) {
    return userService.getUser(id);
}

@RequestParam

用于读取 URL 查询参数（Query Parameters）。常用于分页、搜索过滤等可选输入场景。

@GetMapping("/search")
public String search(@RequestParam String keyword) {
    return "搜索关键词：" + keyword;
}

@RequestBody

将 HTTP 请求体（Body）的内容绑定到一个 Java 对象上。通常与 POST 或 PUT 请求配合使用，接收 JSON 数据。

@PostMapping("/users")
public User saveUser(@RequestBody User user) {
    return userService.save(user);
}

配置与属性绑定注解

@Value

用于注入单个配置属性值，来源可以是 application.properties 或 application.yml 文件。

@Value("${server.port}")
private String port;

@ConfigurationProperties

以类型安全的方式将一组相关的配置属性绑定到一个 POJO（普通 Java 对象）中。适合管理复杂的配置结构。

@ConfigurationProperties(prefix = "app")
public class AppConfig {
    private String name;
    // getter 和 setter
}

数据校验注解

为了确保输入数据的正确性，Spring Boot 支持 JSR-303/JSR-380 标准校验注解。

  • @NotNull：字段值不能为 null。

  • @NotBlank：字符串必须包含至少一个非空白字符（不仅不为 null，也不能是空串或纯空格）。

  • @Email：验证字符串是否符合电子邮件格式。

  • @Size：限制字段长度或集合大小。

示例：

public class User {
    
    @NotBlank
    private String username;
    
    @Email
    private String email;
    
    // getters and setters
}

异常处理注解

优雅的异常处理是健壮系统的关键。

@ExceptionHandler

用于在控制器内部处理特定类型的异常。允许开发者为特定异常定义自定义的错误响应。

@ExceptionHandler(Exception.class)
public String handleException(Exception ex) {
    return "发生错误：" + ex.getMessage();
}

@ControllerAdvice

提供一个全局的异常处理机制，作用于所有的控制器。它将分散在各个控制器中的错误处理逻辑集中化管理。

@ControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<String> handleNotFound(ResourceNotFoundException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }
}

JPA 与数据库实体注解

在使用 Spring Data JPA 进行数据库操作时，以下注解用于定义对象与关系表之间的映射。

注解

用途说明

@Entity

标记一个类为 JPA 实体，对应数据库中的一张表

@Table

指定实体类对应的数据库表名（可选，默认使用类名）

@Id

定义实体的主键字段

@GeneratedValue

配置主键的自动生成策略（如自增、UUID 等）

@Column

将类字段映射到具体的数据库列，可自定义列名、长度等

综合示例：

@Entity
@Table(name = "users_table")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(name = "user_name", nullable = false)
    private String username;

    // getters and setters
}