JAVA后端开发——Spring Boot 组件化自动配置机制

在做 Spring Boot 组件化 / Starter 开发 时，我们经常会看到以下配置：

@Configuration
@ComponentScan("com.test.cbb.cloud")
@MapperScan("com.test.cbb.cloud.mapper")
public class SecurityComponentConfig {
}

同时，组件包中会有一个文件：

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

内容是：

com.test.cbb.cloud.SecurityComponentConfig

很多人会有疑问：

1. 这三个注解分别干什么？
2. 为什么 AutoConfiguration.imports 里写类名就能被外部工程加载？
3. 这个文件路径和格式是固定的吗？应该放哪里？

本文就把这三个问题讲清楚。

---

一、SecurityComponentConfig 里面的三个注解

1. @Configuration

• 作用：告诉 Spring 这是一个配置类，Spring 启动时需要解析它。没有 @Configuration的话，Spring 不会把它当成配置类处理，后面的 @ComponentScan、@MapperScan 可能直接失效
• 解释：配置类可以包含 Bean、扫描配置、自动化逻辑

---

2. @ComponentScan("com.test.cbb.cloud")

• 作用：扫描指定包及其子包下所有 Spring 组件（@Component、@Service、@Controller 等），注册成 Bean

• 为什么写包名：

  • 在组件 / starter 中，外部工程的启动类包名可能不在这个包下
  • Spring 默认只扫描启动类所在包及子包

• 举例：
  EvidenceService、SecurityEventListener 等都能被自动注册

---

3. @MapperScan("com.test.cbb.cloud.mapper")

• 作用：扫描 MyBatis 的 Mapper 接口，生成代理 Bean 并注册到 Spring

• 为什么必须写：

  • Mapper 是接口，没有 @Component
  • Spring 自己不能实例化，需要 MyBatis 生成代理

---

总结

@Configuration     → 这是配置入口
@ComponentScan     → 扫 Spring Bean
@MapperScan        → 扫 MyBatis Mapper

整个配置类的作用就是：

告诉 Spring："这是组件入口，把我的 Bean 和 Mapper 都装进来"

---

二、AutoConfiguration.imports 文件的作用

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

内容：

com.test.cbb.cloud.SecurityComponentConfig

原理

• Spring Boot 启动时，会扫描所有 jar 的这个文件
• 读取里面的类名，相当于执行：

@Import(com.test.cbb.cloud.SecurityComponentConfig.class)

• 这就实现了自动加载组件配置类的效果
• 外部工程 无需任何扫描配置，jar 一引入，Spring 就自动把组件注册进来

---

三、文件路径和格式

1. 文件路径

resource/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

• 这是 Spring Boot 3.x 的固定路径

• Spring Boot 会在启动阶段扫描 classpath 下所有 jar 的这个路径

• Boot 2.x 用的旧方式是：

  resource/META-INF/spring.factories

2. 文件格式

• 每行写一个类的全限定名
• 支持多个自动配置类

示例：

com.test.cbb.cloud.SecurityComponentConfig
com.test.cbb.cloud.OtherAutoConfig

• 空行或注释行不会影响
• Spring Boot 会逐行 @Import 所有类

3. 为什么源码路径和打包后的路径不一样？

你本地源码路径可能是：

.../test-cbb-lib/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

这是 源码阶段，Maven / Gradle 的规则是：

（1）资源文件复制阶段

• src/main/resources 下的内容会原封不动复制到 target/classes

• 例如：

  target/classes/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

（2）打包阶段

• 打包成 jar 时，路径保持相对结构：

  META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

（3）Spring Boot 扫描阶段

• Spring Boot 扫描 jar 内 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
• 每行类名都会被 @Import
• 组件就能自动生效，外部工程无需额外配置

核心点：resources 下写的相对路径 = jar 内的路径 = Spring Boot 扫描路径

---

总结

内容	作用
SecurityComponentConfig	配置类，@ComponentScan 扫 Bean，@MapperScan 扫 Mapper
AutoConfiguration.imports	告诉 Spring Boot "自动 Import 这个配置类"，实现无感加载
路径与格式	META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports，每行写全限定类名，Spring Boot 启动时扫描

---

最终效果

1. 组件 jar 放到 classpath
2. Spring Boot 启动时扫描 AutoConfiguration.imports
3. 自动 @Import(SecurityComponentConfig)
4. @ComponentScan 和 @MapperScan 生效
5. 外部工程 零配置即可使用组件