• SpringBoot自动配置坑了我三天原来漏了这个注解

痛点：在使用 SpringBoot 的自动配置时常常因为“约定大于配置”而不自觉地遗漏关键步骤。导致项目启动失败，排查成本高。

SpringBoot 的自动配置是其主要特性之一，极大地简化了 Spring 应用的开发流程。只是这种设计理念有时会让开发者在不经意间踩坑。最近，我在一个项目中就遇到了一个令人头疼的问题：自动配置未能按预期生效。导致服务无法正常启动，不过，经过三天的排查。后来发现是因为漏掉了一个关键注解——@Import。话说回来，

问题背景

场景描述

痛点：自定义 Starter 后功能未生效。却找不到明显错误提示，

在一个微服务项目中。我尝试自定义一个 SpringBoot Starter，用于封装一些公共功能。按照官方文档，我创建了 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 文件。并在其中指定了自动配置类。只是当其他服务引入这个 Starter 时配置类并未被加载，导致功能完全失效。

初步排查

1. 检查文件方法和名称：确认 AutoConfiguration.imports 文件方法和内容无误。
2. 验证依赖：确保 Starter 的依赖已正确引入，且版本无冲突。
3. 调试自动配置：通过 --debug 模式启动应用，发现自定义的配置类并未出现在日志中。按理说，

SpringBoot 自动配置的主要机制

痛点：对底层机制不了解时即使文件写对也会出现“看不见”的错误。

SpringBoot 的自动配置依赖于以下几个关键组件：

1. AutoConfiguration.imports 文件：SprintBoot 2.7 起取代传统的 spring.factories 文件，用于声明自动配置类。
2. @EnableAutoConfiguration 注解：通常由 @SpringBootApplication 间接引入，用于启用自动配置。
3. 条件注解：@ConditionalOnClass。@ConditionalOnProperty 等，用于控制配置类的加载条件。

关键问题这方面。漏掉 @Import 注解

痛点：SprintBoot 能找到声明，却找不到实际类入口，导致“隐形”失效。

虽然已经正确编写了 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` 文件，但自动配置类本身没有被 Spring 容器扫描到。原因是 Starter 模块与主应用模块的包方法不同，@ComponentScan` 未覆盖到自动配置类所在的包。

@Import` 注解，或者确保该类位于主应用的组件扫描方法下。例如这方面，

@Configuration
@Import // 显式导入
public class StarterConfig {
}

为什么 AutoConfiguration.imports` 不够？不过，

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` 文件只用于声明自动配置类的存在它并不负责将这些类注册到 Spring 容器中。真正的注册行为由 `@EnableAutoConfiguration`触发，但前提是这些类能够被 Spring 的类加载机制找到。如果自动配置类未被扫描到，即使已经在 imports 中声明也不会生效。

方法与验证

再看方案一，显式使用 @Import