Spring Boot 的自动配置是我用了这么多年之后依然觉得最值得掰开揉碎讲清楚的一个机制。很多人天天写SpringBootApplication各种 starter 往pom.xml里一扔应用就能跑起来但你要是问一句“为什么加个spring-boot-starter-redis就自动有RedisTemplate用了”能答上来的人真不多。这篇文章不打算从头抄一遍官方文档而是想以我实际踩坑和做自定义 starter 的经验为线索把自动配置这整套逻辑彻底讲透顺便给你一份可以直接照着写的自定义自动配置实操指南。1. 自动配置到底解决了什么问题1.1 回到 Spring 配置的时代你才知道现在有多幸福我先带大家回忆一下没有自动配置的时候用 Spring 搞一个 Web 应用是什么场面。如果你早年写过 Spring 3、Spring 4 的 XML 配置一定对那一坨宣告自己“存在即合理”的 bean 定义记忆深刻。那时候引入一个第三方库比如 JdbcTemplate你要在 applicationContext.xml 里手动声明数据源 DataSource声明 JdbcTemplate还要管理 Properties 文件的读取。哪怕你只是换个数据库连接串也得小心翼翼地改 XML 属性同时祈祷自己没有把命名空间写错没有把 class 路径搞错。一个稍大点的项目配置文件动辄几百行还有各种context:component-scan、mvc:annotation-driven这类约定俗成但又不完全透明的配置片段。这种模式的问题很明显配置本身和业务逻辑无关但它的复杂度会随着引入的组件数量直线上升。你每引入一个新组件都要去查文档、抄配置、调参数配置代码占到项目总代码量的比重越来越大而且不同项目之间这些配置高度重复。我记得有个朋友从 SSH 时代转 Spring Boot第一次跑起来一个 Web 项目时跟我说“这不对吧我就建了一个带main方法的类连 web.xml 都没写怎么就起服务了”这个困惑非常典型因为它正好点中了 Spring Boot 自动配置要解决的核心问题把那些“所有项目都得做的通用配置”藏起来交给框架自动完成。1.2 约定优于配置把“重复劳动”交给框架自动配置做的事情本质上就是把 Spring 中大量“样板式”的 bean 装配动作接管过来。它有一句很出名的设计原则叫“约定优于配置”Convention over Configuration。什么意思呢就是说框架先设定一套主流场景下的默认行为比如内嵌 Tomcat、默认端口 8080、默认使用application.properties或application.yml作为配置文件。如果你没有做特殊声明框架就按这些约定把环境搭好如果你有定制需求也可以通过配置项或自定义 bean 来覆盖默认行为。这套哲学带来的直接收益就是你可以用一个只有几 KB 的启动类快速把一个空项目变成带数据库、缓存、消息队列的完整服务而省下的时间可以全花在业务逻辑上。自动配置这个词拆开看就是“自动”加“配置”。配置的载体是 Spring 容器里的BeanDefinition自动则体现在条件判断和装配过程不需要开发者显式触发。你只要在 classpath 里加了某个 starter框架就能感知到对应的类是否存在从而决定要不要装配这一整组组件。这个“感知”的过程等会讲原理时大家会看到靠的全是一组非常精妙的条件注解。2. 自动配置的运行机制与核心原理2.1 从SpringBootApplication说起每个 Spring Boot 应用都离不开SpringBootApplication这个注解。它是个组合注解官方称之为复合注解实际上它把三个注解打包在一起了SpringBootConfiguration、EnableAutoConfiguration和ComponentScan。其中SpringBootConfiguration只是Configuration的变体标明当前类是个配置类。ComponentScan负责扫描当前包及其子包下的Component、Service、Repository、Controller等组件。真正的主角是EnableAutoConfiguration这个注解通过Import(AutoConfigurationImportSelector.class)引入了一个选择器而这个选择器就是自动配置的入口。我见过不少新手在启动类上直接写SpringBootApplication然后问“为什么我的MapperScan要单独加为什么配置类放在外部包就不生效”当你理解了这个组合注解的构成这些问题其实就都有了答案包扫描的边界就在当前包及其子包而自动配置的生效与否则取决于另一个独立的加载链路。2.2 自动配置类的加载链路AutoConfigurationImportSelector 的核心逻辑可以拆成三步来理解。第一步读取所有候选的自动配置类名。这一步依赖 Spring 的SpringFactoriesLoader机制。简单说Spring Boot 的各个 starter 在打包时都会在META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件里列出自己提供的自动配置类这个文件会被加载器读取汇总成一个配置类名的列表。这里有个小历史早期 Spring Boot 用的文件名是META-INF/spring.factories里面用EnableAutoConfiguration作为 key 配置。从 Spring Boot 2.7 开始官方引入新的AutoConfiguration.imports文件机制并在 3.0 移除了旧的spring.factories方式。如果你在旧项目升级时发现自动配置不生效了可以先检查一下依赖的 boot 版本和spring.factories的兼容性。第二步对候选配置类做过滤。这一步会选择器结合ConditionalOnXxx条件注解逐个判断。比如候选里有RedisAutoConfiguration但你的项目里并没有引入RedisTemplate相关的类那么这个配置类就会被直接跳过。反过来如果你加了spring-boot-starter-data-redis依赖classpath 里出现了RedisTemplate等关键类条件注解判断通过这个自动配置类就会被注册成一个普通的Configuration类里面的Bean方法随后正常执行。第三步按照排序规则和用户自定义组件做去重处理。自动配置类虽然多但它们的执行顺序是有讲究的。有的核心配置必须最先执行有的则依赖其他配置先准备好 bean。这个顺序通过AutoConfigureBefore、AutoConfigureAfter、AutoConfigureOrder控制。在完成所有过滤和排序后自动配置类就进入 Spring 容器正式装配流程了和用户自己写的Configuration类在地位上完全平等唯一的区别是它排在用户配置之后执行以保证用户自定义的 bean 能优先覆盖默认配置。2.3 条件注解自动配置的灵魂条件注解是自动配置能“聪明”起来的基础。你可以把它们理解成一个个守卫只有满足特定条件后面的配置逻辑才会加载。我在实际开发中最常用的一组条件注解大概有这些条件注解作用ConditionalOnClassclasspath 中存在指定类时生效ConditionalOnMissingBean容器中不存在某个 bean 时生效ConditionalOnBean容器中存在某个 bean 时生效ConditionalOnProperty指定配置项满足条件时生效ConditionalOnWebApplication当前应用是 Web 应用时生效ConditionalOnExpressionSpEL 表达式结果为 true 时生效ConditionalOnClass用得最频繁。比如ServletWebServerFactoryAutoConfiguration上会标注ConditionalOnClass(ServletRequest.class)因为ServletRequest是 Servlet 容器 API 的一部分如果你的项目根本不是 Web 项目classpath 里自然没有这个类那么 Web 容器相关的自动配置就不会触发。ConditionalOnMissingBean则排在靠后的位置。RedisAutoConfiguration 里通常会定义一个Bean ConditionalOnMissingBean(name redisTemplate)也就是说只有当容器里没有你自己定义的redisTemplate时它才会创建一个默认的 StringRedisTemplate 和 RedisTemplate。一旦你自己定义了一个定制版的RedisTemplate自动配置就会自动让位避免两个同名 bean 打架。理解了条件注解这套体系你就不难明白自动配置的智能之处了。它不是一个把几百个 bean 一股脑塞进容器的暴力机制而是一个充满判断和取舍的装配流程每个候选都在被反复问同一个问题“这个场景需要我吗用户是不是已经自己搞定了”3. 手写一个自定义自动配置完整实操流程3.1 设计思路与场景拆解讲了这么多理论我们直接拿一个实际案例走一遍。假设我们要做一个内部使用的短信发送 SDK目标是让其他业务方引入依赖后只需要在配置文件里写几行短信平台的账号信息就能自动获得一个SmsSender可以直接调send()发短信。场景需求拆解一下这个 starter 至少要包括三样东西一个配置属性类用来绑定sms.api-key、sms.api-secret、sms.sign-name这些配置项一个核心服务类SmsSender封装调用短信平台 HTTP 接口的逻辑一个自动配置类负责把SmsSender注入 Spring 容器并在属性缺失或显式关闭时自动取消整个装配。能够造出这样一套东西说明你对 Spring Boot 自动配置的掌控已经不只停留在“会用”层面。3.2 项目结构与核心代码实现先看工程结构。我建议把 starter 拆成两个 Maven 模块一个是sms-spring-boot-starter本身只是个空壳只负责引入另一个模块并作为依赖入口另一个是sms-spring-boot-autoconfigure放所有核心代码。这个分层和官方做法保持一致starter 聚合依赖autoconfigure 干实事。第一步引入基础依赖。在sms-spring-boot-autoconfigure的pom.xml里至少要加上dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-autoconfigure/artifactId version2.7.18/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-autoconfigure-processor/artifactId optionaltrue/optional /dependency这里有个容易忽略的点spring-boot-autoconfigure-processor是注解处理器它会在编译期生成自动配置的元数据文件IDE 里写配置时能获得属性提示建议加上。第二步编写属性类。配置绑定类的任务是建立一个类型安全的配置映射关系。ConfigurationProperties(prefix sms) public class SmsProperties { private String apiKey; private String apiSecret; private String signName; // getter 和 setter 省略 }注意这里用ConfigurationProperties而不是Value逐行读配置。用属性类的好处是集中管理、强类型、嵌套结构而且可以被EnableConfigurationProperties直接注册后续也能参与配置属性校验。第三步写业务服务类。SmsSender 本身不需要加任何 Spring 注解它只是一个普通 POJO 类型构造器接收 SmsProperties。这样设计的好处是便于单元测试也便于将来在非 Spring 环境里复用。public class SmsSender { private final SmsProperties properties; public SmsSender(SmsProperties properties) { this.properties properties; } public void send(String mobile, String content) { // 这里写调用短信网关的代码 } }第四步创建自动配置类。这是整套机制的落点条件注解在这里全面登场。AutoConfiguration EnableConfigurationProperties(SmsProperties.class) ConditionalOnClass(SmsSender.class) ConditionalOnProperty(prefix sms, name enabled, havingValue true, matchIfMissing true) public class SmsAutoConfiguration { Bean ConditionalOnMissingBean public SmsSender smsSender(SmsProperties properties) { return new SmsSender(properties); } }你可能注意到了AutoConfiguration这个注解它是在 Spring Boot 2.7 引入的等于Configuration加了一个专门标记核心用途就是让自动配置类在常规用户配置类之后加载。条件上ConditionalOnClass(SmsSender.class)保证项目里存在这个类才装配这通常意味着业务方引入了我们的模块ConditionalOnProperty控制开关默认enabledtrue允许其他应用在特殊情况下通过配置直接关闭整个自动配置。第五步注册自动配置类。在src/main/resources/META-INF目录下新建文件spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports写入一行内容com.example.sms.autoconfigure.SmsAutoConfiguration这一步如果不做前面写的自动配置类是一张废纸。Spring Boot 就是靠这个文件找到配置类的少了它业务方加再多的依赖也不会触发装配。第六步编译期元数据生成。在 autoconfigure 模块的pom.xml中开启对spring-boot-configuration-processor的依赖上文第二步已有编译后会在META-INF下生成spring-configuration-metadata.json文件使用方写sms.api-key时会有 IDE 自动提示。3.3 使用效果与 bean 装配验证把上面这个 starter 安装到本地仓库然后在另一个 Spring Boot 项目的pom.xml里引入sms-spring-boot-starter接着在application.yml里写配置sms: api-key: your-key api-secret: your-secret sign-name: 我的应用 enabled: true启动项目直接在其他组件里注入SmsSender就能用。整个过程你不需要写一行Bean注册代码也不需要扫描什么包。如果你想验证装配到底有没有生效可以在启动类里临时加一个ApplicationRunner打印applicationContext.getBeansOfType(SmsSender.class)的结果。我看到SmsSender出现在容器里的时候那种“它真的自己就装好了”的感觉就是 Spring Boot 自动配置的设计初衷。4. 实践经验调试手段与常见问题排查4.1 自动配置生效情况可视化自动配置有个最大的痛点它是隐式的出了问题你无从下手。如果你碰到“为什么我加了某依赖但功能没启用”的怪问题第一件事应该是看一眼自动配置报告。你只需在application.properties里加一行debugtrue再启动应用控制台会输出一份 Auto-configuration Report分成 Positive matches、Negative matches 和 Exclusions 三部分。Positive matches 是你当前生效的自动配置类Negative matches 列出被拒绝的自动配置类及原因。这份报告是一面照妖镜能清楚告诉你哪个条件没满足、哪个配置被跳过了。比如你发现 Redis 相关的功能没启用打开报告一看发现RedisAutoConfiguration出现在 Negative 列表原因是ConditionalOnClass没匹配上说明 classpath 里缺少某类这时你就能确认方向依赖没引对而不是代码写错了。除了debugtrue如果你用的是 Spring Boot Actuator还可以暴露conditions端点在运行期实时查询各个配置类的命中情况这在排查生产环境问题时特别好用不用本地复现直接拉日志看条件评估结果。4.2 我自己踩过的三个坑先说第一个坑自动配置类倍用户类抢先注册导致ConditionalOnMissingBean失效。我在一个项目里搞自定义数据源配置时直接在业务模块的Configuration类里定义了一个DataSource但那份自动配置的默认数据源装配还在两边都往容器里塞 DataSource。启动的时候没有任何报错但后续注入JdbcTemplate时行为就很诡异偶尔连的库不对。后来看报告才意识到ConditionalOnMissingBean的判断时机是在自动配置类加载时但用户配置类优先所以只要用户定义过自动配置就不会再去创建默认数据源了。按说这个机制是可靠的问题出在我把自定义和数据源配置分散到了两个模块加载顺序不可控导致自动配置那边的判断提前发生了。最后我把数据源统一成一个配置类再配合AutoConfigureBefore把顺序理顺才解决。第二个坑是ConfigurationProperties类忘记加 getter/setterSpring Boot 2.x 的属性绑定走 JavaBean 绑定没有 setter 就是绑了个寂寞配置全被忽略代码里拿到的全是 null。属性类报错不明显可能一个 NPE 就甩到你脸上排查起来费时费力。第三个坑是只有自己开发调试的时候把AutoConfiguration.imports文件写错了路径。官方文件名长得非常长我手滑把spring目录写错级别结果自动配置类根本不被加载。排查半天才发现此类问题报错信息不明确建议新建 starter 项目后先把注册文件路径反复确认三遍再进入代码开发。4.3 常见问题速查表我把日常被问得最多的几个问题列成一张表方便你排查时对照现象可能原因处理方式自动配置没生效业务类没进容器AutoConfiguration.imports未配置或路径不对检查META-INF下资源和文件内容条件报告显示 Negative match缺依赖或不满足ConditionalOnXxx根据报告中的条件原因补依赖或调配置自定义 bean 被默认配置覆盖自动配置类的ConditionalOnMissingBean没拦住确认自己的 bean 定义比自动配置更早加载属性值全为 null属性类没有 setter 或者前缀不匹配检查ConfigurationProperties和配置文件 key自动配置的顺序错乱多组配置之间有依赖关系未声明使用AutoConfigureBefore/AutoConfigureAfter/AutoConfigureOrder排列升级后旧方案失效spring.factories不再被识别统一迁移到AutoConfiguration.imports机制4.4 影响范围与合理边界自动配置虽强但也不是越广越好。它最适合解决的是“标准通用组件”的安装问题比如数据源、缓存客户端、消息队列、模板引擎这类大部分场景都差不多的集成。相反如果你正在做一个业务逻辑高度定制化的模块把自动配置当作万能药塞进每个人项目里反而会把黑盒变大出问题了谁都不知道哪里冒出来的 bean。在我维护内部公共组件时我给自己定了几条原则自动配置只负责“组装基础设施”业务逻辑一律不放提供enabled开关允许使用方彻底关闭某个自动配置所有自动配置必须靠条件注解保护好边界哪怕别人误引入依赖也不至于破坏了原有容器。最后再分享一个我私藏的小技巧如果你想知道某个自动配置类到底创建了哪些 Bean可以直接临时关掉它比如在配置文件里标spring.autoconfigure.excludecom.example.sms.autoconfigure.SmsAutoConfiguration然后对比前后容器中 Bean 列表的差异。这个差异完全透明比看任何文档都直观。自动配置这层神秘面纱一旦揭掉你会发现它不过是一个更积极、更智能的Configuration而已看懂它之后你对整个 Spring Boot 运行期的掌控能力又会往上走一个台阶。