讲个有点反直觉的事儿我见过不少用Spring Boot写了三四年项目的人从来没点开过META-INF目录下的spring.factories文件也不知道自己的项目里那些自动配置到底是怎么被发现的。但 Spring Boot 能成为今天 Java 后端的主流启动框架很大一部分底层能力就是靠这个不起眼的键值配置文件撑起来的。它不花哨不复杂但它牵动着自动配置机制的加载入口、三方 starter 的装配路径、甚至你排查环境问题和理解框架源码的底层线索。这篇文章就围绕Spring.factories展开说清楚它到底是什么、加载链路怎么走、怎么用最稳妥的方式自定义 starter、以及迁移到 Spring Boot 3.x 的时候必须注意什么。适合所有正在写 Spring Boot 项目的开发特别是打算自己封装公共模块或者想真正理解“自动配置为什么自动”的读者。1. Spring.factories 的真实身份一个被低估的 SPI 注册表1.1 它和普通 properties 配置文件的本质差异很多人在application.yml里写spring.datasource.url、server.port就理所当然地认为spring.factories也是一种“配置”。其实它俩完全不是一个层面的东西。application.yml是给应用实例提供运行时参数的它描述的是“我的程序这次启动要连哪个数据库、监听哪个端口”。而META-INF/spring.factories描述的是“我提供的 jar 包里有哪些类希望被 Spring Boot 框架回调”它是框架扩展点的一种注册表本质上是一种 SPIService Provider Interface机制——不需要用户显式Import或ComponentScan指定框架在启动阶段就自动读取并加载这些实现类。这个设计最核心的价值在于解耦。我自己封装一个公共组件比如分布式锁、幂等校验、日志埋点我不需要要求使用者手动加EnableXxx注解只需要在依赖里引入我的 jar 包然后我在 jar 包内声明好对应的自动配置类Spring Boot 就会帮我兜底完成初始化。这就是为什么加一个spring-boot-starter-data-redis之后什么都不用写RedisTemplate就能直接注入使用。1.2 从启动入口看它的位置Spring Boot 启动时首先实例化SpringApplication然后调用getSpringFactoriesInstances方法这一步就会通过SpringFactoriesLoader.loadFactoryNames扫描 classpath 下所有 jar 包中的META-INF/spring.factories。用一段伪代码看这个调用链大致是这样SpringApplication.run(Application.class, args) - new SpringApplication(primarySources) - setListeners(new SpringFactoriesInstances(ApplicationListener.class)) - refreshContext(context) - invokeBeanFactoryPostProcessors(...) - 自动配置类的加载也在这个链路里监听器加载、环境预处理、自动配置类的筛选全部依赖于spring.factories的扫描结果。换句话说没有这个文件Spring Boot 的“自动”人设就立不住。2. 文件结构与加载机制多 jar 合并的概念必须把握好2.1 常见 key 和它们的用途spring.factories不是只能填一个 key它支持一组固定的框架扩展点。常用的有下面这些Key用途org.springframework.boot.autoconfigure.EnableAutoConfiguration自动配置类入口最核心的 keyorg.springframework.context.ApplicationContextInitializer在容器刷新前做的自定义初始化org.springframework.context.ApplicationListener注册应用事件监听器org.springframework.boot.env.EnvironmentPostProcessor自定义环境变量处理常用于环境准备阶段加载额外配置org.springframework.boot.SpringApplicationRunListenerSpringApplication 启动过程中各阶段的监听回调org.springframework.boot.diagnostics.FailureAnalyzer启动失败时的错误提示分析器org.springframework.boot.autoconfigure.template.TemplateAvailabilityProvider模板引擎可用性判断日常开发中产出率最高的是EnableAutoConfiguration我们自定义 starter 的时候主要也用到它。2.2 一个文件多行配置一个 key 下的类是怎么合并的spring.factories的文件内容是标准的 Properties 格式value 是逗号分隔的类全限定名。注意这里不会出现“后一个文件覆盖前一个文件”的行为而是多个 jar 包的结果合并。实际效果是所有依赖 jar 里的spring.factories都会被打包进各自的META-INF目录Spring Boot 在启动时通过ClassLoader.getResources拿到的是所有 jar 包中同名文件的集合然后逐行读取、按 key 合并成一个LinkedMultiValueMap最后再逐个实例化。举个我踩过的坑。假设项目中同时依赖 a-starter 和 b-starter两个 jar 包里都有org.springframework.boot.autoconfigure.EnableAutoConfiguration这个 key。在合并后两组自动配置类会共存不会互相覆盖。但如果两个 jar 包各自定义了一个同名类全限定名单一样ClassLoader 实际加载的是先出现在 classpath 里的那个另一个会被静默忽略。这种冲突排查起来极其痛苦因为编译期和启动期都没有任何报错。2.3 SpringFactoriesLoader 的读取顺序细节ListString names SpringFactoriesLoader.loadFactoryNames(type, classLoader);这段代码内部的关键逻辑是遍历META-INF/spring.factories的所有 URL 资源读取 Properties然后拼成一个 key 对应的 List。这一步其实只有一个合并逻辑排序是在自动配置类处理阶段按AutoConfigureBefore、AutoConfigureAfter、AutoConfigureOrder的注解解析来完成的。理解了这一点就不会出现“为什么我在依赖里排在前面配置类就被先加载”这种误解了。自动配置的执行顺序按注解声明来而不是按 classpath 的先后顺序来。当然不同自动配置类之间的依赖关系尽量用注解显式声明这比依赖 classpath 顺序靠谱得多。3. 自定义 Starter 的完整实现从声明到生效的全程拆解3.1 为什么推荐独立的 autoconfigure 模块真正开始写自己的 starter 之前先说一个建议这也是我改造过多个项目后最想强调的一点把自动配置类放到独立的模块里例如xxx-spring-boot-autoconfigure然后提供一个单独的xxx-spring-boot-starter模块后者仅仅依赖前者。这样拆分的好处是依赖方可以选择只引用自动配置模块配合Import或者EnableXxx注解手动控制配置类的加载而大部分业务项目则直接依赖 starter 模块走自动装配。如果自动配置代码和业务代码放在同一个 jar 里别人依赖你时可能被迫加载一堆他不需要的配置不优雅。3.2 一个最小的自动配置示例假设我要做一个“灰度发布标记组件”希望引入依赖后自动配置好相关 Bean。第一步创建自动配置类package com.example.gray.autoconfigure; AutoConfiguration ConditionalOnClass(GrayTagService.class) EnableConfigurationProperties(GrayProperties.class) public class GrayAutoConfiguration { Bean ConditionalOnMissingBean public GrayTagService grayTagService(GrayProperties properties) { return new GrayTagService(properties.getDefaultTag()); } }注意我用的是AutoConfiguration而不是Configuration。这是 Spring Boot 2.7 开始引入的注解它正是为了替代在spring.factories里声明EnableAutoConfiguration的老玩法。第二步创建属性绑定类ConfigurationProperties(gray) public class GrayProperties { private String defaultTag base; public String getDefaultTag() { return defaultTag; } public void setDefaultTag(String defaultTag) { this.defaultTag defaultTag; } }第三步在resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件里写一行com.example.gray.autoconfigure.GrayAutoConfiguration注意如果项目还在用 Spring Boot 2.6 及以下版本就需要用老写法在spring.factories里加这个 keyorg.springframework.boot.autoconfigure.EnableAutoConfiguration\ com.example.gray.autoconfigure.GrayAutoConfiguration3.3 条件装配和顺序控制的几个关键点自动配置类不是无脑实例化所有 Bean它必须能感知“当前环境里有没有对应的类”和“用户有没有自己定义过 Bean”否则你做出来的 starter 会让每个使用者的上下文里多出一堆无意义的 Bean甚至跟业务代码冲突。其中最常用的三个条件注解ConditionalOnClass当 classpath 中存在某个类时才生效。绝大多数 starter 都依赖这个因为它能避免在没有引入对应依赖时报错。ConditionalOnMissingBean当容器中没有某个 Bean 时才创建默认实现。这是给用户留后门的方式用户只要自己定义了一个同类型 Bean自动配置的默认 Bean 就会让位。ConditionalOnProperty按配置项开关控制。有的组件默认开启用户可以通过配置关闭。装配顺序方面AutoConfiguration注解里直接提供了after和before两个属性例如AutoConfiguration(after DataSourceAutoConfiguration.class)这样做能确保你的自动配置类在数据源初始化之后再执行。如果用较老的注解则要额外加AutoConfigureAfter不过现在直接写在AutoConfiguration里会更清爽一些。4. 实战排查案例当自动配置不生效我通常会按这个链路找问题4.1 现象一自定义 starter 引入后没有任何反应最典型的情形是本地写了一个公共模块在另一个项目里引用了依赖但自动配置的 Bean 一直不存在注入时直接报NoSuchBeanDefinitionException。排查顺序我建议这么来。首先用jar tf或 IDE 自带的反编译工具检查依赖包里的META-INF/spring.factories或META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件是否真的打进去了。这一步看着蠢但遇到问题的概率最高因为很多人用的是 Maven 打包如果resources目录路径不对配置文件根本没被复制进 jar 包。我刚入行时遇到过的情况就是 IDEA 中 Mark Directory as Resources Root 标错了导致src/main/java下面的META-INF目录没有被打包。这里的核心认知是spring.factories位于 classpath 根目录下的 META-INF 里只有被真正打进 jar 包的META-INF才会在运行时被扫描到。确认文件在 jar 里之后第二步就是看自动配置条件是否满足。Spring Boot 启动时加一个启动参数debugtrue启动日志里会输出一份CONDITIONS EVALUATION REPORT里面会清楚列出每一个自动配置类是被哪个条件匹配的、哪个条件没匹配上。这份报告是排查自动配置问题最直接的证据比我之前对着代码猜条件快得多。4.2 现象二同一个配置类在 Spring Boot 2.6 能生效3.x 里失效这就是我前面提到的最关键的新旧机制切换问题。Spring Boot 3.0 的发布说明里已经明确不再支持从spring.factories的EnableAutoConfiguration键加载自动配置类统一改为META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports。如果你在 Mac 或 Linux 上写代码目录名大小写也很容易踩坑AutoConfiguration.imports前面的目录是META-INF/spring不是META-INF/Spring。目录名写错的话打包不会报错启动也不会报错但配置就是不加载这种问题最容易消磨耐心。4.3 现象三自动配置类的顺序不对导致 Bean 覆盖假设你封装了一个MetricsAutoConfiguration里面注册了一个MetricsCollector但业务项目里也有一个同类型 Bean。没有加ConditionalOnMissingBean的话你的自动配置 Bean 会跟业务 Bean 同时存在或者因为定义顺序不同其中一个覆盖另一个。这种问题的排查结果往往非常不稳定今天生效明天换个人改个配置又不生效。正确做法是统一用ConditionalOnMissingBean避免覆盖并且用AutoConfiguration(before / after)或AutoConfigureOrder显式声明顺序。4.4 现象四多模块项目下依赖 jar 加载到了旧的 spring.factories这个问题在大型项目里很常见。公共模块发布到公司私有仓库之后旧版本还在仓库里被其他服务引用。排查时先看依赖树mvn dependency:tree重点看两件事这个 jar 是否有多个版本被同时引入版本仲裁后是否指向了你预期之外的版本以及spring.factories是否存在但内容不是最新。如果存在版本冲突用mvn dependency:tree -Dverbose -Dincludescom.example:xxx-spring-boot-autoconfigure排查。多数情况下直接在 pom 里加显式依赖版本就能解决。5. 实践心得spring.factories 与周边机制的选择边界5.1 和 Java SPI 的对比谁更适合哪个场景Java 的META-INF/services机制和 Spring 的 SPI 很像但 Spring 的版本做得更顺手。它在同一个文件里支持多个 key不同 jar 包的同名配置还能自动合并不像 Java SPI 需要自己写 ServiceLoader 去循环读取实例。不过如果某个项目完全没有 Spring 依赖那就没有必要强行引入 Spring 的一套。Java 原生 SPI 更轻量类加载也更直观。Spring Boot 项目里基本不需要用原生的 ServiceLoader直接用 Spring 的SpringFactoriesLoader即可。5.2 Spring Boot 3.x 和 2.7 之间迁移注意清单如果你维护的项目还停留在 Spring Boot 2.7 之前又打算升级到 Spring Boot 3最好先做一次全局扫描搜索所有META-INF/spring.factories文件把EnableAutoConfiguration对应的配置迁移到META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports搜索代码里是否有直接调用SpringFactoriesLoader.loadFactoryNames的地方底层行为不变不过要注意返回结构确认spring.factories里是否还有其它 key 的配置那些仍然会被加载不用搬升级到 Spring Boot 3 后Java 版本基线变成 17如果组件里写了基于旧版 JDK 的反射或字节码操作需要额外适配我个人在实际迁移中的做法是先在测试环境留一个“过渡版本”两个声明文件同时保留确认新机制加载成功且没有重复 Bean 冲突之后再删掉spring.factories里的旧声明。这样能把迁移风险控制在最小。5.3 关于组件设计与安全配置的小提醒热搜词里有大量关于 Spring Boot Actuator 的内容围绕这个点多说一句。Actuator 本身提供了很多监控端点使用起来非常方便但它依赖自动配置机制来暴露这些端点。如果你不是非常清楚暴露出来的health、metrics、env等端点意味着什么至少要去application.yml里确认management.endpoints.web.exposure.include这一项别随便填*。我见过不少项目直接配置成include: *然后整个运行环境的敏感配置项通过/actuator/env暴露出去这是非常危险的操作。而这类端点能否生效底层的判断逻辑也跟自动配置类有关management: endpoints: web: exposure: include: health,info,metrics这句话的核心是开放哪些端点而不是随便暴露所有端点。这种认知对每一位使用 Spring Boot 的开发者来说都很重要。5.4 善用条件报告与组件标签最后分享一个我在写公共组件时养成的习惯所有自动配置类都尽量加上AutoConfiguration(after ...)显式声明顺序并且配置类命名统一以AutoConfiguration结尾。这样在排查问题时一眼就能从CONDITIONS EVALUATION REPORT里定位到自己的组件处于哪个位置。命名规范和可读性在组件库这种面向多人使用的场景里价值远比你想象的更大。6. 封装组件时的最终检查清单这里整理一下我在发布一个 starter 到公司内部仓库之前会过一遍的清单每一行都是从实际故障里沉淀出来的。检查META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件是否存在内容是否指向真实存在的类如果组件要兼容老版本检查spring.factories里的EnableAutoConfiguration键是否有拼写错误检查所有自动配置类是否都加了合适的条件注解尤其是ConditionalOnMissingBean检查自动配置类里Bean方法的参数是否能被正常注入避免因为参数类型不在容器里导致启动报错跑一次mvn clean package确认最终 jar 包中包含META-INF资源文件在干净的 Spring Boot 项目中引入 starter验证自动配置能被正确加载然后查看启动日志中的条件评估报告检查自动配置类和属性配置类是否被扫描到了不合适的范围避免把套话、无用的代码带进依赖方这一步一步走完基本能杜绝百分之九十五以上的自动配置失效问题。实际写代码时还有一个让我印象深刻的细节自动配置类里的Bean方法尽量不要在方法内部做太重的初始化尤其是那些ConditionalOnMissingBean兜底的默认 Bean。因为自动配置类的加载对启动时间是有影响的如果每次应用启动都要创建很多临时资源整个启动速度会被拖慢。把重量级初始化移到首次使用时再处理或者设计成懒加载对线上应用更友好。