Spring常用注解总结(持续更新)

0. 引言

因为我的个人习惯，我会从： 是什么(What)，为什么(Why)，怎么用(How)三个方面来分析这些技术和知识点，便于我加深理解和记忆。

注解名称	注解作用
@SpringBootApplication	Spring Boot 的核心组合注解，包含配置、自动装配和组件扫描。
@Autowired	Spring 的自动依赖注入注解。
@Component	通用组件。
@Repository	数据库层。
@Service	业务逻辑层。
@Controller	接口层（Web 层）。
@RestController	把一个类标记为 控制器（Controller） ，并且该类下所有方法默认都以 JSON / XML 等格式返回数据，而不是返回视图（JSP/Thymeleaf 等）。
@Scope	Spring 提供的一个 Bean 作用域（Scope）声明注解。 (单例/多例)
@Component	用来声明配置类，里面的方法用 @Bean 定义 Bean。
@PathVariable	用于 URL 路径变量（资源定位）。
@RequestParam	用于 URL 查询参数或表单参数（条件、筛选）。
@RequestBody	用来把请求体中的 JSON 数据转成 Java 对象，特别适合前后端分离的场景。
@Value	读取单个配置属性。
@ConfigurationProperties	将配置文件中的属性绑定到一个 Java Bean 上，支持嵌套对象和集合。
@PropertySource	指定读取某个 properties 文件（不常用，多用于老项目）。
@Null	被注释的元素必须为 null
@NotNull	不能为 null
@NotEmpty	字符串或集合不能为空
@NotBlank	字符串不能为空且必须有非空白字符
@Email	必须是合法邮箱
@Size(min=, max=)	字符串或集合长度/大小限制
@Digits (integer, fraction)	被注释的元素必须是一个数字，其值必须在可接受的范围内
@Pattern(regex=,flag=)	必须符合指定正则
@Min/@Max	数值最小/最大值
@DecimalMin/@DecimalMax	小数最小/最大值
@Past/@Future	日期必须为过去/将来
@AssertTrue/@AssertFalse	布尔值必须为 true/false
@Transactional	事务

各种主键生成策略对照表

策略名	对应类	说明	适用场景
uuid2	UUIDGenerator	使用 Java UUID v2 生成	推荐，分布式环境
guid	GUIDGenerator	GUID，全局唯一标识	Windows/SQL Server
uuid / uuid.hex	UUIDHexGenerator	旧版 UUID	已废弃
assigned	Assigned	主键由应用代码手动赋值	业务系统已有主键
identity	IdentityGenerator	数据库自增主键	MySQL 常用
sequence	SequenceStyleGenerator	数据库序列	Oracle/PostgreSQL
seqhilo	SequenceHiLoGenerator	hi/lo 算法生成主键	大并发优化
increment	IncrementGenerator	自增计数器	单机测试用，不推荐生产
foreign	ForeignGenerator	使用外键作为主键	一对一关系
sequence-identity	SequenceIdentityGenerator	序列 + 自增	特殊数据库
enhanced-sequence	SequenceStyleGenerator	增强版序列	替代旧 sequence
enhanced-table	TableGenerator	通过表维护主键	无序列支持的数据库

JPA 常用注解速查表

分类	注解	说明
表相关	@Entity	标记一个类为 JPA 实体类，映射数据库表
	@Table(name = "xxx")	指定实体类对应的表名（默认类名）
	@Column(name = "xxx", nullable = false, length = 100)	指定字段名、长度、是否可空等约束
	@Id	标识 主键字段
主键策略	@GeneratedValue(strategy = GenerationType.IDENTITY)	自增主键（MySQL 常用）
	@GeneratedValue(strategy = GenerationType.SEQUENCE)	使用数据库序列生成主键（Oracle 常用）
	@GeneratedValue(strategy = GenerationType.UUID)	使用 UUID 作为主键（Spring Boot 3.0+ 支持）
字段控制	@Transient	该字段 不持久化（不会映射到表）
	@Lob	存储大字段（如 TEXT、BLOB）
	@Enumerated(EnumType.STRING)	枚举保存为 字符串
	@Enumerated(EnumType.ORDINAL)	枚举保存为 序号
审计功能	@EnableJpaAuditing	开启 JPA 审计功能（放在配置类上）
	@CreatedDate	自动填充 创建时间
	@LastModifiedDate	自动填充 修改时间
	@CreatedBy	自动填充 创建人
	@LastModifiedBy	自动填充 修改人
修改删除	@Modifying	标记 更新/删除 SQL 方法（配合 @Query）
	@Transactional	开启事务，保证修改/删除的原子性
关联关系	@OneToOne	一对一关系（如用户与身份证）
	@OneToMany	一对多关系（如用户与订单）
	@ManyToOne	多对一关系（如订单属于用户）
	@ManyToMany	多对多关系（如学生与课程）

一. @SpringBootApplication

1. 是什么（What）

@SpringBootApplication 是 Spring Boot 提供的一个 核心注解。

它是一个 组合注解，实际上包含了三个常用注解：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@SpringBootConfiguration   // 表示这是一个配置类，相当于@Configuration
@EnableAutoConfiguration   // 启动Spring Boot的自动配置功能
@ComponentScan             // 开启组件扫描，扫描当前包及子包下的Bean
public @interface SpringBootApplication {
}

也就是说：@SpringBootApplication = @SpringBootConfiguration + @EnableAutoConfiguration + @ComponentScan。

2. 为什么（Why）

为什么要用 @SpringBootApplication？原因有三个：

简化配置

过去写 Spring 程序，需要在启动类上写多个注解，比如：

@Configuration
@EnableAutoConfiguration
@ComponentScan
public class AppConfig { ... }

Spring Boot 把这些合并成一个 @SpringBootApplication，让启动类更简洁。

根据 SpringBoot 官网，这三个注解的作用分别是：

@EnableAutoConfiguration：启用 SpringBoot 的自动配置机制
@ComponentScan： 扫描被@Component (@Service,@Controller)注解的 bean，注解默认会扫描该类所在的包下所有的类。
@Configuration：允许在 Spring 上下文中注册额外的 bean 或导入其他配置类

统一入口

所有 Spring Boot 应用都有一个 入口类（main 方法所在的类），加上 @SpringBootApplication 就能告诉 Spring Boot：

“从我这里开始启动应用，自动配置并扫描组件”。

约定大于配置

@EnableAutoConfiguration 会根据 classpath 里的依赖和配置，自动装配 Spring Bean（例如加了 spring-boot-starter-web 就自动配置 Tomcat 和 SpringMVC）。
开发者只需要 专注业务逻辑，不用手动写繁琐的配置。

3.怎么用（How）

一般用法很简单：

在入口类上加注解

@SpringBootApplication
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

控制扫描范围（可选）
默认情况下，@ComponentScan 会扫描入口类所在包及其子包。
如果项目包结构复杂，可以手动指定：

@SpringBootApplication(scanBasePackages = "com.example.project")
public class MyApplication { ... }

排除某些自动配置（可选）
如果某些自动配置和你的业务冲突，可以排除：

@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })
public class MyApplication { ... }

4.总结

是什么：@SpringBootApplication 是 Spring Boot 的核心组合注解，包含配置、自动装配和组件扫描。

为什么：让项目入口简洁，减少配置，利用自动化机制提升开发效率。

怎么用：加在应用主类上，main 方法调用 SpringApplication.run(...)，可选指定扫描范围和排除配置。

二. Spring Bean 相关

1. @Autowired

1.1、是什么（What）

@Autowired 是 Spring 框架提供的一个 依赖注入（Dependency Injection, DI）注解。
它的作用是：自动装配 Bean —— Spring 容器会根据类型（byType）自动找到合适的 Bean，并注入到标注了 @Autowired 的变量、构造方法或 setter 方法中。

换句话说：@Autowired 就是告诉 Spring： “请帮我找一个合适的 Bean 注入到这里” 。

---

1.2、为什么（Why）

为什么要用 @Autowired 而不是自己 new 对象？原因有三个：

降低耦合度

如果你手动 new 对象，代码强依赖具体实现。
用 @Autowired，对象由 Spring 容器统一管理，方便替换和扩展。

依赖注入自动化

传统 XML 配置需要 <bean> 配置和 <property ref="xxx"> 注入，非常繁琐。
@Autowired 可以省去大量配置，提升开发效率。

支持多种注入方式

支持 字段注入、构造器注入、Setter 方法注入，灵活方便。

---

1.3、怎么用（How）

常见用法有三种：

1.3.1. 字段注入（最常见，但不推荐在大项目中）

@Service
public class UserService {
    @Autowired
    private UserRepository userRepository;

    public void doSomething() {
        userRepository.save(...);
    }
}

1.3.2. 构造器注入（推荐，最安全，利于单元测试）

@Service
public class UserService {
    private final UserRepository userRepository;

    @Autowired  // Spring 5+ 单构造器时可以省略
    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }
}

1.3.3. Setter 注入（用于可选依赖）

@Service
public class UserService {
    private NotificationService notificationService;

    @Autowired(required = false)  // 表示注入可选
    public void setNotificationService(NotificationService notificationService) {
        this.notificationService = notificationService;
    }
}

1.3.4. 自动导入对象到类中，被注入进的类同样要被 Spring 容器管理

比如：Service 类注入到 Controller 类中。

@Service  
public class UserService {  
  ......  
}  
  
@RestController  
@RequestMapping("/users")  
public class UserController {  
   @Autowired  
   private UserService userService;  
   ......  
}

---

1.4、细节知识点

默认按类型装配

Spring 会根据依赖的类型（class/interface）去容器中找唯一匹配的 Bean。

多个候选 Bean 时怎么办？

如果有多个候选 Bean，会报错。解决方法：

用 @Qualifier("beanName") 指定 Bean 名称。
或者给其中一个 Bean 加 @Primary。

@Service("emailService")
public class EmailNotificationService implements NotificationService {}

@Service("smsService")
public class SmsNotificationService implements NotificationService {}

@Service
public class UserService {
    @Autowired
    @Qualifier("emailService")
    private NotificationService notificationService;
}

和 @Resource 的区别

@Autowired 默认按 类型 注入。
@Resource 默认按 名称 注入。

1.5、总结

是什么：@Autowired 是 Spring 的自动依赖注入注解。
为什么：减少手动创建对象，降低耦合，让 Bean 管理更灵活。
怎么用：加在字段、构造器、setter 上，默认按类型注入，必要时配合 @Qualifier 或 @Primary。

2.Component,@Repository,@Service, @Controller

2.1、是什么（What）

这四个注解都是 Spring 的组件注解，用于把类注册到 Spring 容器中，变成一个 Bean。

@Component

最基础的组件注解。
表示“这是一个 Spring 管理的 Bean”，通用的注解，可标注任意类为 Spring 组件。如果一个 Bean 不知道属于哪个层，可以使用@Component 注解标注。。

@Repository

作用在 DAO（数据访问层） ，比如操作数据库的类。
在 @Component 基础上扩展了 持久层异常转换功能（把 JDBC 异常转成 Spring 的统一异常）。

@Service

作用在 Service（业务逻辑层） 。
本质上还是 @Component，但语义更清晰，表示这是业务逻辑类。

@Controller

作用在 Controller（表现层 / Web 层） 。
搭配 @RequestMapping、@GetMapping、@PostMapping 等注解，用来处理 Web 请求，接受用户请求并调用 Service 层返回数据给前端页面。。

✅ 本质：这四个注解都是 @Component 的衍生注解，只是为了分层更清晰。

---

2.2、为什么（Why）

为什么要分成四个注解？

分层语义更清晰

@Component：通用组件。
@Repository：数据库层。
@Service：业务逻辑层。
@Controller：接口层（Web 层）。
这样别人一看就能知道类的用途。
<