有段时间我一直想不通一个问题我明明没有配置Redis的数据源也没手动写任何RedisTemplate的Bean为什么项目一启动就自动能用RedisTemplate后来跟到Spring Boot启动的Debug调用链才发现幕后黑手是一个叫spring.factories的小文件。正是它告诉Spring Boot该去扫描哪些自动配置类从而把一堆内部组件“悄无声息”地装配好。spring.factories是Spring框架里一个非常朴素、但威力巨大的配置文件通常放在jar包的META-INF目录下。它的格式就是一个标准的properties文件而它承载的能力却一点不标准它把Spring Boot的自动配置、环境后处理、失败分析、监听器扩展这些核心机制全部统一成一行行键值对。换句话说理解了spring.factories你就拿到了Spring Boot“默认就能用”的钥匙。这篇文章适合正在用Spring Boot但没系统研究过自动配置的开发者也适合准备手写Starter、公共组件或者想排查“为什么我的Bean没生效”的同事。我会从加载原理、源码调用链、手写自动配置实操再到多版本适配与典型问题排查一条线全部梳理清楚尽量让你读完就能直接在自己的项目里复现。1. 打开一个jar包你会发现自动配置的“总调度室”原来在这里1.1 什么是spring.factories它解决的三个真实痛点META-INF/spring.factories是Spring Boot沿用Spring Framework SPI机制设计出来的扩展点文件。你可以把它的作用理解成一份“服务注册表”所有希望被Spring Boot容器自动发现和装配的类都统一登记在这个文件里。它解决的三个实际痛点非常直接让框架组件能被自动加载。没有它Spring Boot就不知道该扫描哪些自动配置类启动器就退化成单纯依赖坐标、毫无加工能力的普通jar包。把“有哪些自动配置”这个信息从代码中剥离。新增一个自动配置类不需要改任何启动类、不需要写ComponentScan、也不需要挨个Import只要在文件里登记一行重启就生效。给外部扩展留出标准入口。第三方框架只需要打进一个spring.factoriesSpring Boot就会在启动阶段统一读取实现了“代码负责能力、配置负责登记”的分离。你打开spring-boot-autoconfigure这个jar包就能在META-INF目录下找到它。里面经常可以看到几百行配置大部分是自动配置类的全限定名每行一个末尾不加分号。看到这种文件结构你基本就能明白Spring Boot启动时为什么能“什么都知道”它先读这份总名单再逐一筛选出符合条件的配置类。1.2 三个必须重点关注的关键EnableAutoConfiguration与另外两类配置入口在spring.factories里配置项非常多但如果你是为了研究自动配置只需要死死盯住下面表格里的几类关键。配置Key作用最终会被谁使用org.springframework.boot.autoconfigure.EnableAutoConfiguration自动配置类的候选名单AutoConfigurationImportSelectororg.springframework.context.ApplicationContextInitializer容器刷新前的初始化回调SpringApplicationorg.springframework.boot.env.EnvironmentPostProcessor环境准备阶段的后置处理器EnvironmentPostProcessorApplicationListener其中EnableAutoConfiguration是自动配置的绝对核心。SpringBootApplication里的EnableAutoConfiguration注解最终会通过AutoConfigurationImportSelector去读取spring.factories里这个Key对应的值然后把全部候选类交给后续的条件判断环节。有同学会混淆既然叫做EnableAutoConfiguration是不是必须显式开启实际上SpringBootApplication本身就包含了这个注解所以你不需要额外做任何事Spring Boot就已经在使用这个Key扫描你的classpath了。1.3 加载链条拆解SpringFactoriesLoader是如何读完这份名单的spring.factories的读取者叫SpringFactoriesLoader它是Spring Framework在spring-core中提供的一个内部工具类名字很直白加载Spring的工厂类。核心调用链大致是SpringApplication.run()启动项目。刷新容器之前EnableAutoConfiguration导入的AutoConfigurationImportSelector会被执行。selectImports()方法内部调用SpringFactoriesLoader.loadFactoryNames(EnableAutoConfiguration.class, classLoader)。loadFactoryNames会遍历classpath里所有META-INF/spring.factories文件按Key过滤出对应的配置类名返回一个ListString。这些类名随后会被转换为AutoConfigurationEntry再交给条件注解处理。值得注意的一个细节是SpringFactoriesLoader底层会对文件内容做合并聚合。也就是说它不是只读一个jar包里的文件而是会把classpath下所有jar包的spring.factories都扫描一遍然后把同一个Key的值追加到一个列表里。这个设计非常聪明意味着多个Starter的自动配置可以共存而不是后加载的覆盖前加载的。2. 为什么Spring Boot要把“默认行为”写进配置文件而不是写代码2.1 显式配置的麻烦很早以前在没有Spring Boot的年代你引入一个第三方组件基本逃不过这命运自己写一个Configuration在里面手工声明各种Bean再通过Import或XML把配置类引进来。组件版本一多这种“人肉装配”很快就变成负担。更棘手的是你根本不可能提前知道所有组件的默认配置。Redis需要序列化器Kafka需要消费者工厂每个组件的默认行为五花八门。如果都让用户自己组装配置类的数量会呈指数级增长使用门槛也直线上升。2.2 让“约定优于配置”落地spring.factories配合条件注解正好解决了“默认行为”这档事。框架作者把自己认为合理的默认配置写进自动配置类然后在spring.factories里登记。启动时Spring Boot把这份默认配置类名单读出来再用一堆ConditionalOnClass、ConditionalOnMissingBean来判断当前classpath里有没有相关依赖用户有没有已经自定义的Bean如果条件都不冲突默认配置就被激活。我常用的一个类比是spring.factories像一份餐馆的“推荐菜单”条件注解是服务员的一句询问——“您已经有自带菜了吗没有的话我就按招牌菜上”。这样既保证了开箱即用又不会强行覆盖用户自己的选择。2.3 spring.factories不止服务于自动配置环境后置处理、HealthIndicator、监听器都走了这条路很多教程会把spring.factories和自动配置完全画等号这就把它的能力说小了。在自动配置之外它还被多个基础设施用来收集扩展点EnvironmentPostProcessor用于在Spring环境对象准备好后追加自定义配置。比如spring-boot-devtools里的DevToolsPropertyDefaultsPostProcessor就走这个通道。ApplicationContextInitializer在容器刷新之前执行初始化逻辑适合做一些全局性的早期设置。FailureAnalyzer把启动异常翻译成可读性更高的建议。例如端口被占用时你会看到那句经典的“APPLICATION FAILED TO START”背后的分析器也是通过spring.factories注册的。ApplicationListener允许外部模块向Boot注册自定义事件监听器。这就解释了为什么很多框架的官方Starter明明只让用户引了一个依赖却能同时协调环境变量、监听器、自动配置等多条逻辑。不是它神通广大而是它在一个统一文件里把多个扩展Key都登记好了。3. 手写一个自己的自动配置从零到可以发布的完整过程纸上谈兵没有意义我直接带你手写一个小型自动配置。假设我们现在要做一个极其简单的组件输出问候语的GreetingService并希望引入依赖后项目里直接就能注入它。3.1 搭建工程并确定被自动配置的Bean创建一个普通的Maven工程这个工程将来会作为独立组件发布。它的职责很简单提供一个GreetingService类并提供一个自动配置类让引入方无需手动声明即可获得Bean。下面是被自动配置的类没什么花哨就是带一个属性public class GreetingService { private final String prefix; public GreetingService(String prefix) { this.prefix prefix; } public String greet(String name) { return String.format(%s, %s, prefix, name); } }prefix这里设计成可配置项是为了后面演示ConditionalOnProperty的用法。组件使用者可以在配置文件里通过greeting.prefix这个属性覆盖默认值也符合“约定优于配置”的思路。3.2 编写自动配置类和条件装配注解自动配置类就是一个普通的Configuration类但比较讲究的是必须搭配条件注解。这里有几个原则能用ConditionalOnMissingBean就用它给用户留后路。能用ConditionalOnProperty控制开关的就用属性开关方便用户随时关闭。跨模块判断依赖是否存在时用ConditionalOnClass避免类不存在的场景报错。我们的自动配置类写起来大概是这样的AutoConfiguration ConditionalOnProperty(prefix greeting, name enabled, havingValue true, matchIfMissing true) public class GreetingAutoConfiguration { Bean ConditionalOnMissingBean public GreetingService greetingService( Value(${greeting.prefix:hello}) String prefix) { return new GreetingService(prefix); } }这里用了AutoConfiguration注解它是Spring Boot 2.7之后推荐的写法本质上是一个组合注解包含Configuration和一些与自动配置相关的声明。如果你用的是老版本可以直接换成Configuration不影响Spring Boot 2.6及更早版本的理解。三个条件注解配合起来的效果是用户没有显式定义GreetingService的时候才注入缺省Bean。用户只要在配置里写了greeting.enabledfalse整个自动配置就不生效。没写greeting.enabled时默认生效方便用户无脑用。3.3 创建spring.factories并测试前面的类准备好之后关键一步就是创建META-INF/spring.factories文件内容如下org.springframework.boot.autoconfigure.EnableAutoConfiguration\ com.example.greeting.autoconfigure.GreetingAutoConfiguration注意格式反斜杠是properties文件的行连接符如果后面还有多个自动配置类每个全限定名用逗号分隔。如果你的文件里只有一行也可以不写反斜杠但推荐保留统一风格。然后写一个普通的Spring Boot测试工程引入这个组件依赖并在测试类里直接注入GreetingServiceSpringBootTest class GreetingAutoConfigurationTest { Autowired private GreetingService greetingService; Test void testAutoConfiguredBean() { Assertions.assertEquals(hello, world, greetingService.greet(world)); } }跑一下测试如果GreetingService能注入成功说明spring.factories链路已经通了。这里我想强调一个很常被忽略的做法最好给自动配置单独开一个测试工程而不是让示例工程和组件工程混在一起。因为自动配置只在“引入方”环境下才能被验证自己工程里能跑通不代表第三方项目里也能跑通。3.4 打包后手动验证移除starter依赖后观察生效情况把组件工程mvn install到本地仓库再回到一个干净的新Spring Boot工程里只添加这个组件依赖不写任何Import。启动项目后观察控制台日志如果能看到自动配置类被匹配的记录说明配置生效。如果在Autowired处直接报NoSuchBeanDefinitionException大概率是spring.factories没被扫描到或者AutoConfiguration没有被处理。也可以直接在启动类里临时打印SpringBootApplication public class DemoApplication { public static void main(String[] args) throws Exception { SpringApplication app new SpringApplication(DemoApplication.class); app.addInitializers(ctx - { GreetingService service ctx.getBean(GreetingService.class); System.out.println(service.greet(spring.factories)); }); app.run(args); } }当然这个打印方式比较粗暴只是为了让你直观看到Bean确实存在。正式项目里不建议用初始化器玩这种操作测试里验证即可。3.5 排序与覆盖如何控制多个自动配置的执行顺序一旦组件多了自动配置类的执行顺序就变得很重要。比如你的配置类要依赖另一个配置类创建的Bean作为前置条件顺序不对就会导致条件判断失败。Spring Boot提供了两组方式控制顺序在自动配置类上标注AutoConfigureBefore、AutoConfigureAfter直接声明相对顺序。通过AutoConfigureOrder指定一个排序值值越小优先级越高。下面是一个示意AutoConfiguration AutoConfigureAfter(OtherAutoConfiguration.class) public class GreetingAutoConfiguration { // ... }这种顺序声明的背后Spring Boot会在解析完所有自动配置类后做一次拓扑排序保证依赖方向的配置类后加载。如果你的组件之间没有先后依赖建议不要乱写顺序注解减少不必要的耦合。4. 常见问题与排查技巧实录自动配置不生效的四个根因这部分是我最想分享的。自动配置的原理很多人讲得明白但真正遇到生产环境问题能把排查链路走通的人不多。4.1 排名第一的原因SpringFactoriesLoader根本没读到你的文件自动配置不生效我遇到最多的情况不是条件不满足而是META-INF/spring.factories没有出现在最终classpath里。常见的原因有以下几种组件模块的pom.xml被打成了非jar包或者被maven的jar插件排除掉了META-INF内容。多个模块合在一个工程里目录结构不对spring.factories放在src/main/resources之外的位置打包后找不到。使用了Spring Boot 3.x但还按照2.x的方式配置EnableAutoConfiguration这个后面会细说。排查方法很简单把最终构建出来的jar包解开直接看META-INF目录下有没有对应文件。很多时候你Debug半天代码其实只是文件根本没进jar。jar tf your-starter.jar | grep spring.factories如果输出为空就要去检查构建配置了这个问题和源码逻辑无关。4.2 条件注解被误杀ConditionalOnClass与类加载器的坑ConditionalOnClass的原理基于类加载器探测它会尝试加载指定的类。如果类不存在条件就不匹配配置类被跳过。这个机制本身很合理但实际环境里埋着一个坑当你需要判断的类在某个可选依赖里而该依赖并不是所有环境都存在时条件判断的结果会受classpath影响。更隐蔽的情况是某些应用服务器会用更复杂的类加载器。比如同一个类被父加载器加载但子模块看不到就会导致ConditionalOnClass的判断结果和预期不符。虽然Spring Boot的内嵌容器环境很少踩这个但如果你在做非嵌入式部署或二次开发框架就得多留个心眼。遇到条件不满足时可以使用Spring Boot的自动配置报告来查看具体跳过原因。在配置文件中加入debugtrue启动后控制台会输出CONDITIONS EVALUATION REPORT里面会列出每个自动配置类的匹配状态是匹配通过、还是不匹配且标注了原因。看到这个报告大部分“为什么没生效”的问题能迎刃而解。4.3 版本差异带来的影响Spring Boot 2.7前后与Spring Boot 3.x时代很多老项目还在用Spring Boot 2.6甚至更早而新项目已经跑在Spring Boot 3.x上这两者之间spring.factories的用法是有明显差异的踩坑频率极高。在Spring Boot 2.6及之前自动配置类写在spring.factories的EnableAutoConfiguration键下完全没问题。从Spring Boot 2.7开始官方建议新建的自动配置类使用META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件并采用AutoConfiguration注解旧的spring.factories方式仍然支持但已经标记为过度方案。到Spring Boot 3.0自动配置类不再从spring.factories加载必须使用新的imports文件。这是硬切换不是可选推荐。新文件内容极其简单不需要写Key直接列出自动配置类全限定名即可com.example.greeting.autoconfigure.GreetingAutoConfiguration如果你想做一套兼容Spring Boot 2.x和3.x的组件比较稳妥的做法是同时维护spring.factories和新的AutoConfiguration.imports文件。在Spring Boot 3.x下自动配置走imports文件在2.7之前的老版本下自动配置走spring.factories。这块官方迁移文档有明确说明实际做组件时建议测试矩阵覆盖多版本。4.4 调试自动配置的几个实用手段除了开debugtrue看条件评估报告还有几个手段在排查时特别管用在spring.factories或imports文件里临时删掉某个配置类观察行为变化能快速定位配置类本身的问题。在自动配置类的静态方法或构造器里打日志如果类被加载但条件不匹配你在启动早期就能看到日志迹象。直接查看Spring容器中已注册的Bean名称确认配置类是否真的生成过对应Bean。下面这段代码可以在测试里打印所有GreetingService类型的BeanTest void listBeans() { MapString, GreetingService beans context.getBeansOfType(GreetingService.class); beans.forEach((name, bean) - System.out.println(name - bean)); }如果Bean存在说明自动配置注册成功如果Bean不存在但条件报告里又显示匹配通过那就说明你的Bean方法可能写错了包路径或者Autowired用在静态字段上。4.5 避坑清单最后我把自己实际遇到过的坑整理成了一张清单这些不一定都能从官方文档里直接看到但每一条都来自真实项目。不要在spring.factories里放Configuration但没标AutoConfiguration的类。虽然以前能跑但新版本会提示你迁移后续维护成本高。不要在自动配置类里使用高频率扫描逻辑。自动配置在启动阶段执行性能敏感如果你在里面扫包、查数据库往往会把启动时间拉长到不可接受。ConditionalOnMissingBean不要滥用。它可以防止兜底Bean覆盖用户Bean但如果多个Starter都用它判断同一个类型容易造成全部不装配的相对死锁问题。多环境场景下避免把环境相关属性写死在自动配置类里。优先用ConfigurationProperties绑定让用户可在外部配置中覆盖。打好你的自动配置依赖坐标。如果组件内部还依赖了某个可选模块建议把该依赖声明为optional避免自动配置因为一个不存在的类导致整个容器刷新失败。在实际做公共组件时我会把自动配置类的数量控制在最少。一个功能对应一个配置类否则条件报告会变得很长排查问题也更容易迷路。不要在自动配置里堆太多条件注解条件越多组合状态越多出问题的概率越高。我个人的体会是spring.factories虽然只是一个文件但它背后贯穿着Spring Boot最核心的“自动装配”思想。你把它的加载机制、条件匹配逻辑和版本差异都吃透之后再看那些眼花缭乱的Starter就会发现它们不过是同一套扩展机制在不同场景下的重复应用。以后你写的不是“能用的配置”而是一个别人引入后就能直接开工的稳定组件。