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相关包	测试支持	单元测试、集成测试