做Spring Boot开发的人八成遇到过这种诡异的情况明明pom里加了某个公共组件的坐标项目也正常启动可该有的自动配置就是没生效。你翻依赖、改配置折腾半天最后打开组件jar发现Spring.factories里类名拼错了一个字母。这种问题太典型了因为很多人对Spring.factories的理解就停留在“自动配置清单”它到底被谁读、怎么读、能写哪些key却未必说得清楚。这篇文章不照官方文档的顺序念而是结合自己做Starter、维护公共组件时踩过的坑把Spring.factories的来龙去脉、启动加载机制、注册方式和排查技巧一次讲透。适合三类人打算在团队里封装公共组件的人、正在排查自动配置失效的人以及准备面试、想搞懂Spring Boot自动装配原理的人。1. Spring.factories到底是一张什么“表”1.1 没有这张登记表自动配置就无从谈起Spring Boot最大的卖点是约定大于配置你只要引入一个starter相关Bean就会被自动装配出来。可这里有个天然矛盾主应用不知道外部jar包提供了哪些配置类主程序所在包的ComponentScan也扫不到别的jar里的类。想让第三方配置类进入容器就必须有一个统一的地方登记让Spring Boot启动时主动去认领。META-INF/spring.factories就是这个地方。它在Spring Boot里承担SPIService Provider Interface的作用凡是参与Spring Boot启动流程的扩展点都可以把实现类登记到这份文件里框架启动时通过SpringFactoriesLoader统一读取。可以把它理解成一张酒店入住登记表每个jar包想获得Spring Boot的服务先在门口把名字和能做的事写清楚后面配不配提供服务再由Spring Boot按登记表逐一核实。这种设计还有个好处应用代码不需要import任何第三方配置类的类名新增一个组件只需要把它放进classpath自动配置就会通过扫描spring.factories被发现。依赖是代码层面的解耦配置是文件层面的插拔这也是Spring Boot生态能长出那么多starter的根本原因。1.2 可用的key不止自动配置一个很多人只见过org.springframework.boot.autoconfigure.EnableAutoConfiguration这个key但Spring.factories是一张多key的表不止自动配置在用。常见注册键如下Key解决什么问题org.springframework.boot.autoconfigure.EnableAutoConfiguration注册自动配置类触发自动装配org.springframework.context.ApplicationContextInitializer容器刷新前做的初始化逻辑org.springframework.boot.env.EnvironmentPostProcessor在Environment准备阶段修改配置源org.springframework.boot.SpringApplicationRunListener监听SpringApplication启动过程各阶段事件org.springframework.context.ApplicationListener注册通用ApplicationListenerorg.springframework.boot.autoconfigure.AutoConfigurationImportListener / AutoConfigurationImportFilter监听或过滤自动配置类的导入过程我刚接触这文件时以为它就是一份自动配置类清单这个理解明显窄了。它更像一个以字符串key为分类维度的SPI注册中心Spring Boot内部大量扩展点都靠它暴露包括启动时看到的banner、监听器、外置配置加载逻辑。不过普通业务开发里大家写Starter时使用频率最高的仍然是EnableAutoConfiguration。文件本身的格式非常简单就是Java Properties格式key对应扩展点类型value是逗号分隔的类名列表。写多个类时可以用反斜杠续行也可以用一行写多个如下org.springframework.boot.autoconfigure.EnableAutoConfiguration\ com.example.notify.NotifyAutoConfiguration,\ com.example.notify.NotifyRetryConfiguration org.springframework.boot.env.EnvironmentPostProcessor\ com.example.notify.CustomEnvironmentPostProcessor注意注释只能用#而且最好别直接写中文因为Properties在加载时对非ASCII字符的处理比较特殊容易出现乱码。1.3 为什么Spring Boot不直接用JDK的ServiceLoader了解SPI的人会想到JDK自带的ServiceLoader在META-INF/services/目录下按接口全名建文件写入实现类全名使用方通过ServiceLoader.load()读取。这套机制完全可行Spring Boot却还是自建了SpringFactoriesLoader主要是几个原因。JDK ServiceLoader每份文件对应一个接口一个服务的实现类只能写在固定路径下而Spring.factories通过一个文件管理所有接口的映射启动时只需要一次类路径扫描缓存一份Map之后所有扩展点按key查询。对Spring Boot这种启动链路很长的框架来说扫描成本低、组织更集中。另外SpringFactoriesLoader不仅能从spring.factories取类名还直接提供loadFactories方法帮你实例化对象实现了“按类型找实现”的完整流程而且支持多jar包同名文件合并去重。这套机制后来也覆盖到Spring Cloud等上层框架很多微服务组件的扩展点依旧沿用。2. 启动时它到底干了什么SpringFactoriesLoader的加载原理2.1 一次类路径扫描结果被缓存成Map先看核心类SpringFactoriesLoader这名字起得很直白工厂加载器。它不在Spring Boot里而在spring-core模块。Spring Boot启动后框架各处调用SpringFactoriesLoader.loadFactories或loadFactoryNames来获取实现类。具体时机上SpringApplication.run()发生的时候构造器里就会用SpringFactoriesLoader加载所有SpringApplicationRunListener接着在prepareEnvironment阶段会加载EnvironmentPostProcessor在prepareContext阶段应用ApplicationContextInitializer真正刷新容器时AutoConfigurationImportSelector才会从自动配置注册文件中拿自动配置类。明白了这个调用链你就知道不同key生效的早晚差别有多大。简化后的核心逻辑大概是这样的public static ListString loadFactoryNames(Class? factoryType, ClassLoader classLoader) { MapString, ListString result loadSpringFactories(classLoader); return result.getOrDefault(factoryType.getName(), Collections.emptyList()); } private static MapString, ListString loadSpringFactories(ClassLoader classLoader) { MapString, ListString result new HashMap(); EnumerationURL urls classLoader.getResources(META-INF/spring.factories); while (urls.hasMoreElements()) { URL url urls.nextElement(); Properties properties PropertiesLoaderUtils.loadProperties(new UrlResource(url)); for (Map.Entry?, ? entry : properties.entrySet()) { String factoryTypeName ((String) entry.getKey()).trim(); String[] factoryNames StringUtils.commaDelimitedListToStringArray((String) entry.getValue()); for (String factoryName : factoryNames) { String trimmed factoryName.trim(); if (!trimmed.isEmpty()) { result.computeIfAbsent(factoryTypeName, k - new ArrayList()).add(trimmed); } } } } return result; }这里有几个容易被忽略的细节。其一classLoader.getResources会返回classpath下所有jar包里匹配的文件URL也就是多个jar可以同时贡献spring.factories最终结果合并成一个Map其二真实源码里对这个Map加了缓存缓存键是ClassLoader避免每一次加载都重新扫描整个classpath。看明白这段逻辑很多问题就能解释你新增的spring.factories能不能被读到取决于打完包后文件在不在jar里的META-INF目录下如果你改了文件而依赖是通过Maven本地缓存里的旧jar提供的那读到的还是旧内容。这类“改了配置却不生效”的案例根源往往不是Spring代码而是打包和依赖缓存的细节。2.2 读到的类名只是候选名单配不配生效还看条件从spring.factories里拿到的EnableAutoConfiguration类名列表只是候选名单并不等于全部生效。Spring Boot会把它们交给AutoConfigurationImportSelector处理按照AutoConfigureOrder、AutoConfigureBefore、AutoConfigureAfter声明的顺序排序后逐个用ConditionalOnClass、ConditionalOnMissingBean等条件注解做匹配只有条件成立才注册对应配置。这也是自动配置为什么常常像变魔术的真正原因你在spring.factories里写了10个配置类可能只有3个最终生效。比如配置类里依赖StringRedisTemplate而当前项目没有引入redis那么配置类整体跳过且不报错。所以排查自动配置问题不能只看spring.factories里写了什么还要看条件评估报告。这里需要区分两个概念SpringFactoriesLoader负责加载类名自动配置的条件匹配由AutoConfigurationImportSelector和后续Bean注册逻辑负责二者不在同一个阶段。如果你用SpringFactoriesLoader加载自己的自定义SPI实现那就是纯粹类名加反射实例化条件注解不参与这一点后面讲进阶玩法时会再提到。2.3 2.7之后的新机制AutoConfiguration.importsSpring Boot 2.7发布了一个重要变化自动配置类除了可以写进spring.factories还能写进META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports这个文件里每行一个自动配置类全名启动时优先读取。引入它的原因很实际。spring.factories用的是Properties格式类名列表越来越长时要频繁处理转义续行而且不止自动配置各种框架都往里塞东西文件本身变得很杂。官方于是单独为自动配置开了一条更干净的通道新文件格式就是纯文本清单不用再解析key-value。Spring Boot 2.7里两种方式兼容Spring Boot 3.x之后spring.factories里的EnableAutoConfiguration键被彻底移除支持。如果你还在维护老组件迁移动作不只是换个文件写一遍还要把旧的条目从spring.factories删掉否则新老两种方式同时存在时依赖关系处理容易出问题而且Boot 3.x启动遇到旧写法会给出明确警告提示迁移。需要特别说明这次变化只涉及自动配置注册这一条路径Spring.factories本身没有被废弃。Spring Boot 3.x里EnvironmentPostProcessor、ApplicationContextInitializer、SpringApplicationRunListener等扩展点依旧从spring.factories加载你该用还得用。3. 手写一个自动配置StarterSpring.factories实战3.1 工程结构与必要依赖纸上谈兵没意思下面写一个有代表性的Notification Starter。需求很简单项目里如果引入了Redis自动提供一个基于Redis的消息通知服务通知渠道、是否启用等配置项通过properties绑定。工程结构如下notify-spring-boot-starter/ ├── pom.xml └── src/main/ ├── java/com/example/notify/ │ ├── NotifyProperties.java │ ├── NotifyService.java │ └── NotifyAutoConfiguration.java └── resources/META-INF/ ├── spring.factories └── spring/org.springframework.boot.autoconfigure.AutoConfiguration.importspom里最关键的是引入spring-boot-autoconfigure它提供AutoConfiguration、ConditionalOnXxx等注解配置处理器不是必须项但加上之后IDE里写配置有提示建议作为optional依赖带上。dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-autoconfigure/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-configuration-processor/artifactId optionaltrue/optional /dependency /dependencies别把starter自身做成对spring-boot-starter-data-redis的强依赖因为不是每个使用方都需要Redis。自动配置的基本思路就一句话你想在什么条件下现身就用对应的ConditionalOnXxx来控制。3.2 自动配置类怎么设计属性类负责读取配置。用ConfigurationProperties把notify前缀下的配置绑定成强类型对象ConfigurationProperties(prefix notify) public class NotifyProperties { private boolean enabled true; private String channel dingtalk; private String webhook; // getter / setter 方法省略 }服务类是一个普通的业务类不依赖Spring的注入机制方便单元测试public class NotifyService { private final NotifyProperties properties; private final StringRedisTemplate redisTemplate; public NotifyService(NotifyProperties properties, StringRedisTemplate redisTemplate) { this.properties properties; this.redisTemplate redisTemplate; } public void send(String target, String content) { redisTemplate.opsForList().leftPush(notify:queue: target, content); } }自动配置类是Spring Boot装配的核心我写成这样AutoConfiguration(after RedisAutoConfiguration.class) EnableConfigurationProperties(NotifyProperties.class) ConditionalOnProperty(prefix notify, name enabled, havingValue true, matchIfMissing true) public class NotifyAutoConfiguration { Bean ConditionalOnClass(StringRedisTemplate.class) ConditionalOnMissingBean(NotifyService.class) public NotifyService notifyService(NotifyProperties properties, StringRedisTemplate stringRedisTemplate) { return new NotifyService(properties, stringRedisTemplate); } }几个设计点值得展开说。AutoConfiguration是2.7以后推荐的自动配置注解比直接用Configuration更安全因为普通组件扫描默认不会扫到它还支持after/before指定排序确保依赖的配置类先注册。ConditionalOnProperty控制总开关matchIfMissing设为true表示不配配置也默认启用。ConditionalOnMissingBean是自动配置最该养成的习惯给用户留出覆盖的口子用户一旦自己定义了NotifyService自动配置就不再注册避免Bean冲突。3.3 注册写法与装配验证老项目或库类组件按旧的兼容方式在src/main/resources/META-INF/spring.factories里写org.springframework.boot.autoconfigure.EnableAutoConfiguration\ com.example.notify.NotifyAutoConfiguration面向新版本在META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports里写com.example.notify.NotifyAutoConfiguration两个文件可以同时保留兼容用2.7之前版本的应用。我把两种写法都放进去不是为了炫技而是很多公司的主项目还在Boot 2.6公共组件旧写法不能丢。验证自动配置是否生效最省事的办法是用ApplicationContextRunner在单元测试里模拟启动class NotifyAutoConfigurationTest { Test void shouldRegisterNotifyService() { new ApplicationContextRunner() .withConfiguration(AutoConfigurations.of(NotifyAutoConfiguration.class)) .run(context - { assertThat(context).hasSingleBean(NotifyService.class); }); } }ApplicationContextRunner会临时起一个最小容器跑完即销毁很适合反复试验不同条件组合。但上面这段测试没有Redis依赖进去后NotifyService大概率注册不上因为ConditionalOnClass(StringRedisTemplate.class)没通过。要让它通过还需要手写一个模拟的StringRedisTemplate注册到容器里或者直接引入相关依赖。这恰恰说明一个事实写Starter时测试都要连同条件注解一起考虑缺依赖导致的条件不匹配在测试里会原形毕露。4. 常见问题排查与避坑实录4.1 症状、原因和处理方法速查表我在实际工作中排查过不少自动配置失效的问题大部分都能归到下表这几类症状最可能的原因处理方法组件无任何效果启动不报错spring.factories没打包进jar或类名拼错解压jar检查META-INF/spring.factories启动报ClassNotFoundException自动配置类用到的类在optional依赖里使用方没引入调整依赖范围或换成ConditionalOnClass自定义Bean被自动配置的Bean覆盖自动配置没加ConditionalOnMissingBean给自动配置补充缺失条件注解升级Boot 3.x后自动配置失效EnableAutoConfiguration键不再支持把条目迁移到AutoConfiguration.imports自定义key读取不到任何实现只写了文件但代码没有用SpringFactoriesLoader读取在框架代码中显式加载先明确一点Spring.factories不生效时最常见的不是报错而是完全静默。因为条件注解不满足时框架会直接跳过连日志都没有这种问题最难查好在你还可以靠诊断开关定位。4.2 开启条件评估报告看到底哪些配置没通过Spring Boot启动时加--debug或者配置文件里设debugtrue控制台会打印一份CONDITIONS EVALUATION REPORT。这份报告把自动配置类分为Positive matches匹配成功和Negative matches匹配失败每个类下面会列出落选原因。我印象很深的一次排障是某个内部组件升级Boot 2.7后自动配置悄悄没了。当时第一反应是依赖没传过来折腾了半小时后来开启--debug看到Negative matches里写着“ConditionalOnClass did not find class org.springframework.data.redis.core.StringRedisTemplate”才意识到是版本升级后传递依赖发生了变化。另外如果启动应用里引入了spring-boot-starter-actuator还能通过conditions端点在线查看management.endpoints.web.exposure.includeconditions,configprops启动后请求/actuator/conditions返回JSON里同样包含正负匹配信息。configprops端点则可以确认NotifyProperties有没有正确绑定到配置前缀。我个人排查自动配置问题的流程基本固定先看Negative matches锁定类没匹配上的原因再看这些原因是不是依赖缺失、属性未设置、条件注解写错最后回到spring.factories确认类名有没有被成功加载。这三步能覆盖大多数场景。4.3 容易被忽略的细节坑格式层面的坑最隐蔽。spring.factories里用反斜杠续行时反斜杠后面不能有空格否则Properties解析会把“\”加空格当成转义符导致类名列表被分割错位。类名后面如果多打了一个逗号解析时会产生空字符串虽然不影响整体但排查时突然看到列表里多了一个空项很容易让人分心。再一个是类必须提供无参构造器。SpringFactoriesLoader.loadFactories在实例化时用的是无参构造反射如果你的实现类只定义了有参构造器框架在启动早期阶段无法完成实例化直接抛异常。比如注册SpringApplicationRunListener时这个坑很常见。还有一个容易被忽略的点如果项目用了Spring Boot 2.7自动配置同时存在于spring.factories和AutoConfiguration.imports时以imports文件为准即便两个文件里写了同一个类也不会重复注册框架内部做了去重。但如果你在spring.factories里写的是老key一些排查工具提示的加载来源可能不一致还是要尽早统一迁移。4.4 升级Boot 3.x时老配置怎么处理从Spring Boot 2.7升到3.x如果组件还依赖spring.factories里的EnableAutoConfiguration条目你会发现自动配置彻底失效。Spring Boot 3.x启动时对这条旧路径直接忽略不再兼容读取。迁移很简单把条目挪到META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports每行一个类名然后从spring.factories里删掉对应的EnableAutoConfiguration键。注意spring.factories其他键不用动比如EnvironmentPostProcessor在Boot 3里依然有效不要因为看到“spring.factories deprecated”的说法就全盘清理。如果组件要同时兼容Boot 2.6和3.x通常做法是运行时按Boot 3.x构建时提供imports文件发布时对老版本特殊处理像AutoConfiguration这种2.7才有的注解在Boot 2.6里需要回退用Configuration。要不要做双兼容得看使用者群体的版本分布两套方式同时维护确实会增加工作量。5. 值得一试的进阶玩法5.1 EnvironmentPostProcessor启动最早期的“修改环境”入口如果你需要在SpringApplication读取完配置、但容器还没启动之前对Environment做手脚比如注入兜底配置、动态加profileEnvironmentPostProcessor是合适的入口。public class CustomEnvironmentPostProcessor implements EnvironmentPostProcessor { Override public void postProcessEnvironment(ConfigurableEnvironment environment, SpringApplication application) { MapString, Object defaults new HashMap(); defaults.put(notify.channel, wechat); environment.getPropertySources().addLast(new MapPropertySource(notify-default-config, defaults)); } }注册到spring.factoriesorg.springframework.boot.env.EnvironmentPostProcessor\ com.example.notify.CustomEnvironmentPostProcessor这个机制的典型场景是应用连不上配置中心时给某些关键配置提供本地默认值或者根据环境变量动态改变Spring Boot profile。注意它发生在Bean容器创建之前所以不能用Autowired或Value所有配置只能从getPropertySources里手动读取。5.2 自定义SPI键把插件能力开放给外部Spring.factories最被人低估的价值是自定义SPI扩展。你可以定义自己的扩展接口然后要求插件方在spring.factories里注册实现类运行时用SpringFactoriesLoader统一加载。比如框架里定义了一个规则处理器public interface RuleHandler { boolean support(String ruleType); }读取所有实现ListRuleHandler handlers SpringFactoriesLoader.loadFactories(RuleHandler.class, this.getClass().getClassLoader());插件jar只需要在自己的spring.factories里写com.example.framework.RuleHandler\ com.example.plugin.PluginRuleHandlerA,\ com.example.plugin.PluginRuleHandlerB运行时代码不用改动就能加载新增插件。这种玩法非常适合规则引擎、消息路由、多租户策略分发等场景。比起自己写配置文件再反射实例化用SpringFactoriesLoader可以少写不少样板代码而且自动兼容多jar包合并。要注意写插件接口时尽量把契约定义清楚实现类必须有无参构造器否则运行时加载会报InstantiationException。这类自定义SPI一般不会被Spring容器管理Bean的依赖注入也指望不上适合做无状态扩展点。5.3 用SpringApplicationRunListener统计启动耗时另一个容易被忽略的扩展点是SpringApplicationRunListener。它定义了starting、environmentPrepared、contextPrepared、contextLoaded、started、ready、failed等事件许多做了启动性能分析的工具就是靠它记录各阶段耗时。注册方式同样是写入spring.factories但实现类有几个约束必须有无参构造器构造器参数必须是(SpringApplication, String[] args)。原因是框架在启动早期就要实例化它没法走Spring容器注入。这个扩展点适合做平台级的启动监控普通业务项目不建议滥用。我个人在实际项目里用Spring.factories注册过自定义SPI、做过Environment兜底配置也踩过自动配置不生效的静默坑。这几年下来最大的体会是它并不神秘本质上就是框架给了每个组件一张入场券登记表能不能真正进入容器还得看条件注解和依赖环境。排查这类问题时我的固定动作永远是先解压jar看META-INF/spring.factories在不在再用--debug看条件评估报告八九成问题能在十分钟内定到根因。希望这篇整理能让你在写Starter和排障时少绕几个弯。