Spring Framework 常用注解详解（按所属包分类整理）

在使用 Spring Framework 进行开发时，注解（Annotation）是实现 依赖注入（DI）、组件扫描、AOP 切面、事务管理 和 Web 请求映射 的核心手段。Spring 提供了丰富且结构清晰的注解体系，这些注解按照功能被组织在不同的包中。

本文 按注解所属的包（package）进行分类，详细说明每个包的用途，并列举该包下的常用注解及其功能。

1. `org.springframework.stereotype` —— 组件声明注解

🔹 用途说明：

该包提供了用于 声明 Spring 管理的组件（Bean） 的注解。Spring 容器通过组件扫描（@ComponentScan）自动发现这些类，并将其注册为 Bean 实例。这些注解主要用于类级别，实现分层架构的语义化标注。

✅ 常用注解：

注解	详细说明
`@Component`	通用组件注解，任何被 Spring 管理的类都可以使用。它是`@Service`、`@Repository`、`@Controller`的父注解。
`@Service`	专用于业务逻辑层（Service 层），语义更明确，便于代码维护和分层设计。
`@Repository`	专用于数据访问层（DAO/Repository），除了注册为 Bean 外，还能自动将数据库异常（如 SQLException）转换为 Spring 的`DataAccessException`，便于统一异常处理。
`@Controller`	用于 Web 层控制器，通常与`@RequestMapping`配合使用，处理 HTTP 请求。
`@RestController`	虽然实际位于`org.springframework.web.bind.annotation`包中，但功能上属于此分类。它是`@Controller + @ResponseBody`的组合注解，用于构建 RESTful API，返回 JSON/XML 数据，无需额外标注`@ResponseBody`。

💡 提示：使用这些注解后，需配合 @ComponentScan 启用组件扫描，Spring 才能自动发现并注册这些 Bean。

`2. org.springframework.beans.factory.annotation` —— 依赖注入（DI）核心注解

🔹 用途说明：

该包提供了 Spring 依赖注入（DI）的核心注解，用于实现 自动装配（Autowiring） 和 属性注入。它们可以作用于字段、方法、构造器等位置，是实现松耦合设计的关键。

✅ 常用注解：

注解	详细说明
`@Autowired`	自动装配 Bean，默认按类型（byType）查找并注入。可作用于字段、setter 方法、构造器等。若存在多个同类型 Bean，需配合`@Qualifier`使用。
`@Qualifier`	与`@Autowired`配合使用，通过指定 Bean 的名称（id）来解决类型冲突问题。例如：`@Qualifier("userServiceImpl")`。
`@Value`	用于注入基本类型或字符串值，支持从配置文件（如`application.properties`）读取属性值，语法为`${key}`；也支持 SpEL（Spring Expression Language）表达式，语法为`#{expression}`。例如： `@Value("${server.port}")` `@Value("#{systemProperties['os.name']}")`

💡 提示：@Value 是实现外部化配置（Externalized Configuration）的重要手段，常用于读取环境变量、配置项等。

3. `org.springframework.context.annotation` —— 配置与条件化注解

🔹 用途说明：

该包提供了基于 Java 的配置方式（Java Config），用于替代传统的 XML 配置文件。它支持 配置类定义、组件扫描、条件化加载、环境隔离 等高级功能，是构建现代化 Spring 应用的基础。

✅ 常用注解：

注解	详细说明
`@Configuration`	标记一个类为配置类，相当于一个 XML 配置文件。此类中通常包含`@Bean`方法。
`@Bean`	标注在方法上，表示该方法返回的对象将被注册为 Spring 容器中的 Bean。常用于配置第三方组件（如 DataSource、RedisTemplate 等）。
`@ComponentScan`	启用组件自动扫描，指定扫描的包路径。Spring 会自动发现并注册带有`@Component`及其衍生注解的类。
`@PropertySource`	用于加载`.properties`属性文件，通常与`@Configuration`一起使用。例如： `@PropertySource("classpath:app.properties")` 配合`@Value`注入属性值。
`@Import`	导入其他配置类，实现配置的模块化管理。例如： `@Import(DatabaseConfig.class)`
`@Profile`	指定某个 Bean 或配置类仅在特定环境下生效（如`dev`、`test`、`prod`）。例如： `@Profile("dev")` 结合`spring.profiles.active`属性控制环境切换。
`@Scope`	定义 Bean 的作用域，常见值有： -`singleton`（默认，单例） -`prototype`（每次获取都创建新实例） -`request`、`session`（Web 环境下）
`@Lazy`	标记 Bean 为延迟初始化，仅在首次使用时创建，可提升应用启动速度。
`@Primary`	当容器中存在多个相同类型的 Bean 时，标记该 Bean 为“首选”，避免`@Autowired`报错。

💡 提示：这些注解是实现“零 XML 配置”的关键，尤其在 Spring Boot 中被广泛使用。

4. `org.springframework.web.bind.annotation` —— Web 与 MVC 注解

🔹 用途说明：

该包是 Spring MVC 的核心注解集合，用于处理 HTTP 请求映射、参数绑定、响应处理 等 Web 层功能。适用于构建传统的 MVC 应用或 RESTful 风格的 Web 服务。

✅ 常用注解：

注解	详细说明
`@RequestMapping`	最基础的请求映射注解，可作用于类或方法，支持设置 URL 路径、请求方法（GET/POST）、参数、请求头等。
`@GetMapping`	快捷方式，等价于`@RequestMapping(method = RequestMethod.GET)`，用于映射 GET 请求。
`@PostMapping`	映射 POST 请求，常用于表单提交或创建资源。
`@PutMapping`	映射 PUT 请求，用于更新资源。
`@DeleteMapping`	映射 DELETE 请求，用于删除资源。
`@PatchMapping`	映射 PATCH 请求，用于部分更新资源。
`@RequestParam`	绑定请求参数（如`?name=张三`）到方法参数。支持设置是否必填（`required`）、默认值（`defaultValue`）。
`@PathVariable`	绑定 URL 路径中的变量（如`/users/{id}`），常用于 RESTful 风格接口。
`@RequestBody`	将 HTTP 请求体（如 JSON）反序列化为 Java 对象，常用于 POST/PUT 请求体数据绑定。
`@ResponseBody`	将方法返回值直接写入 HTTP 响应体（如返回 JSON），常用于 AJAX 或 REST 接口。
`@RestController`	组合注解，等价于`@Controller + @ResponseBody`，所有方法默认返回数据而非视图名。
`@RequestHeader`	获取 HTTP 请求头信息，如`User-Agent`、`Authorization`等。
`@CookieValue`	获取 Cookie 的值。
`@ModelAttribute`	用于绑定表单数据到对象，或在请求处理前向模型中添加属性。

💡 提示：@RestController 是构建前后端分离项目的核心注解，推荐用于 REST API 开发。

5. `org.springframework.transaction.annotation` —— 事务管理注解

🔹 用途说明：

该包提供了声明式事务管理的支持，通过注解方式控制数据库事务的边界，避免手动管理 Connection、commit、rollback，提升代码可读性和一致性。

✅ 常用注解：

注解	详细说明
`@Transactional`	标记方法或类需要事务管理。支持配置： - 传播行为（Propagation） - 隔离级别（Isolation） - 超时时间（timeout） - 是否只读（readOnly） - 回滚规则（rollbackFor）例如： `@Transactional(rollbackFor = Exception.class)`

⚠️ 注意：需在配置类上添加 @EnableTransactionManagement 启用事务支持（Spring Boot 自动配置）。

6. `org.aspectj.lang.annotation` —— AOP 切面编程注解

🔹 用途说明：

该包来自 AspectJ 框架，Spring 借助它实现 面向切面编程（AOP），用于处理日志、权限、性能监控、事务等横切关注点（Cross-cutting Concerns）。

✅ 常用注解：

注解	详细说明
`@Aspect`	定义一个切面类，该类中包含通知（Advice）方法。
`@Before`	前置通知，在目标方法执行前执行。
`@After`	最终通知，无论目标方法是否抛出异常，都会执行。
`@AfterReturning`	返回通知，在目标方法成功执行并返回后执行。
`@AfterThrowing`	异常通知，在目标方法抛出异常后执行。
`@Around`	环绕通知，最强大的通知类型，可以控制目标方法的执行（如前置逻辑 → 执行方法 → 后置逻辑）。
`@Pointcut`	定义切点表达式，用于复用切点逻辑。例如： `@Pointcut("execution(* com.example.service..(..))")`

⚠️ 注意：使用这些注解需引入 aspectjweaver 依赖，并启用 AOP 支持（如 @EnableAspectJAutoProxy）。

7. 测试相关注解（Spring Boot Test 模块）

虽然严格来说不属于纯 Spring Framework，但在实际开发中极为常用，特此补充。

🔹 所属包：

org.springframework.boot.test.context
org.springframework.boot.test.autoconfigure.web.servlet
org.springframework.boot.test.mock.mockito

✅ 常用注解：

注解	详细说明
`@SpringBootTest`	启动完整的 Spring 上下文，用于集成测试。
`@WebMvcTest`	仅加载 Web 层（Controller），用于测试控制器逻辑。
`@DataJpaTest`	仅加载 JPA 相关配置，常用于 Repository 层测试，自动配置内存数据库。
`@MockBean`	在测试中创建一个 Mock Bean（如 Mockito 对象），并注册到 Spring 容器中，用于模拟依赖。

💡 提示：这些注解属于 spring-boot-test 模块，适用于 Spring Boot 项目。

✅ 总结：Spring 注解体系概览

包名	主要功能	典型使用场景
`org.springframework.stereotype`	组件声明	分层架构 Bean 标注
`org.springframework.beans.factory.annotation`	依赖注入	自动装配、属性注入
`org.springframework.context.annotation`	配置管理	Java Config、条件化加载
`org.springframework.web.bind.annotation`	Web 请求处理	MVC、REST API 开发
`org.springframework.transaction.annotation`	事务管理	数据库操作一致性控制
`org.aspectj.lang.annotation`	AOP 切面	日志、权限、性能监控
`spring-boot-test`相关包	测试支持	单元测试、集成测试