手写一个自定义 Starter：从 0 到被 Boot 自动装载

这一篇讲的不是「怎么用 Spring Boot」，而是怎么自己做一个让别人「一引就生效」的 Spring Boot 插件。你写好一套能力（比如发短信），把它打包成一个 jar；别人只需要在自己的项目里写一段 <dependency> 和几行 yml，就能直接把这个能力当现成组件用——不用他写任何注册代码。这件事在 Spring Boot 里叫 Starter（启动器）。

先把这六个词一次性解释清楚，后文不再重复：

学完这一篇，你应该能回答三个问题：

• 我的 Java 代码到底该放 starter 模块还是 autoconfigure 模块？放错了会看到哪句报错？
• 容器是怎么「知道」我这个第三方配置类存在的？靠哪个文件、路径必须怎么写？
• 使用方想关掉我的 Starter，或者想用他自己的实现替换我的默认实现，我该留什么口子？

引入 spring-boot-starter-web 之后，你一行配置没写，却凭空得到了嵌入式 Tomcat、Spring MVC、Jackson 序列化……很多人的第一反应是「这 starter 真神奇」。但只要打开它的 pom，你会发现一个反直觉的事实：starter 这个 jar 里，一行 Java 代码都没有。

Spring Boot 官方把「starter」拆成了两个职责完全不同的东西：

spring-boot-starter-web 的 pom（精简后）大致是这样：

下面以一个「短信发送」Starter 为例从零做出来。目标很具体：使用方引入依赖、写上几行 yml，就能直接 @Autowired SmsClient。

按官方建议拆成两个模块：

autoconfigure 模块的 pom，关键是对只用于编译期的依赖使用 optional：

starter 模块的 pom，只负责把 autoconfigure 打包带走：

两个 pom 该勾哪几项，别去抄别人的——自己生成一遍，顺便看清每一项的 scope 和 optional 是从哪句话来的：

模块拆完了，四个文件各自管什么？这层「谁管谁」的关系比 pom 更容易记混，所以做成可以一格格点的堆叠图——从下往上点，每抽掉一层，使用方的体验就掉一格：

属性类负责把 yml 里的 sms.* 绑定成一个 Java 对象。它是整个 Starter 的「参数面板」：

属性类只是「接水的杯子」，水是怎么流进来的？这段动画把一条 yml 走到 SmsClient 手里的六拍全演了一遍，注意第 ③ 拍：access-key 和 accessKey 是在这一刻对上的。

SmsClient 就是这个 Starter 真正对外提供的能力。关键认知：它是一个普通 POJO，不做任何注册。

这是整个 Starter 的灵魂：它决定「什么时候把 SmsClient 注册进容器」。

逐注解解读，这才是读/写自动配置的正确姿势：

• @AutoConfiguration：新式自动配置标记，等价于 @Configuration(proxyBeanMethods = false)，但额外获得排序能力（before / after）。它必须由 imports 清单注册，不能用 @ComponentScan 扫到
• @ConditionalOnClass(SmsClient.class)：classpath 上必须存在该类。这正是「依赖没引入时整个自动配置直接跳过」的开关
• @ConditionalOnProperty(prefix = "sms", name = "enabled", havingValue = "true", matchIfMissing = true)：给使用方一个总开关；matchIfMissing = true 表示「yml 里不写也默认开启」
• @EnableConfigurationProperties(SmsProperties.class)：把 SmsProperties 注册成 Bean 并完成绑定，这样下面的 @Bean 方法可以直接要一个参数
• @ConditionalOnMissingBean（写在 @Bean 方法上）：用户优先的体现——使用方自己定义了 SmsClient，这里就主动让路；没定义才兜底

上面五条各管一件事，而这五件事正是面试与工单里被追问最多的五处。背不住——来玩一局：先点你写下的那行注解，再点它唯一负责的那件事。

自动配置类写好了，但容器怎么知道它的存在？答案是一份清单文件。路径必须一字不差：

文件内容极其简单，一行一个类名，不需要任何 key：

有人会问：直接在自动配置类上写 @ComponentScan 把自己的包扫进来，不是更省事？省事是省事，但它把「条件什么时候求值」这件事从容器手里抢回了扫描顺序手里。两条入口的差别就在这张对照图里——同一个类，走左边那条门，@ConditionalOnMissingBean 就可能提前答「没有」：

Starter 做完，使用方需要做的只有三件事。

第一步，加依赖：

第二步，写配置：

第三步，直接用：

启动后控制台输出即证明接线成功：

Starter 「没生效」时，别猜，直接开条件报告：

报告里找到自己的配置类，逐条核对每个条件：

官方对自定义 starter 有明确的命名与发布建议，照着做能少踩很多坑：

下面这个演示把上面的三个条件做成了可切换开关。试着把「用户已自定义」打开，观察 SmsClient 的注册是如何被跳过的：

前面四个文件都写完了，现在把它们按启动顺序连成一条线。这条线是本篇最难自行推导的部分，也是面试里「说说自定义 starter 的原理」的标准答案骨架：

上面那张表是「读」的，顺序还是得点。把这五步摊成一次单步执行：左边六行代码，右边同步刷新此刻的变量和调用栈。连点下一步，重点停在第 ② 拍——那一拍决定了后面四拍到底有没有机会发生：

光看图记不住装配链路，因为它发生在启动的最初几秒、且全程「看不见对象」。下面五个实验在你的浏览器里真实执行 Spring Boot 的那几层，每个都能自己切参数。建议顺序：先 ① 建立整体感，再 ② 看清注册与排序，然后 ③ 逐个搞懂条件注解，④ 弄明白使用方的配置到底怎么进到 SmsProperties，最后 ⑤ 回头确认 SmsProperties 和 SmsClient 究竟是从哪条门进容器的。

第一个实验拆掉整个 Starter 的四根承重柱。元数据（metadata）指的是「描述自己配置的数据」，这里指那份 imports 清单；依次点四个按钮，你会看到「清单存在 → 属性绑上 → Bean 造出来 → 我把开关关掉」的完整过程，最后一个按钮正是第十二节决策卡里「让使用方能优雅降级」的落点：

第二个实验回答第 2 步那个最抽象的问题：候选清单是从哪些 jar 里捞出来的，捞出来之后为什么要排序。「排序与分组」那一步能看到官方自动配置之间的 before / after——这就是第五节强调 @AutoConfiguration 比裸 @Configuration 多出来的能力，你的第三方配置默认排在所有官方配置之后：

第三个实验把第五节那三个条件注解逐个拆开求值。条件注解（conditional annotation）就是「满足条件才装配」的判断开关。切到 @ConditionalOnMissingBean 那一格，你会亲眼看到用户已定义同名 Bean 时默认实现如何被跳过——这正是第十四节沙盘要你手动验证的同一件事：

第四个实验解释使用方最常问的一句话：「我在 yml 里写了 access-key，Java 字段叫 accessKey，凭什么对得上？」。松散绑定（relaxed binding）就是 @ConfigurationProperties 允许 kebab-case、camelCase、大写环境变量三种写法命中同一个字段的能力；顺手对比「谁覆盖谁」，能看懂 profile、环境变量、命令行三层的优先级关系：

第五个实验回答的是一句很少被讲清的话：SmsProperties 和 SmsClient 都是 Bean，但它们进容器走的不是同一条门。依次点 scan、bean、import、auto，四条门（组件扫描、@Bean 方法、@Import 直送、清单登记的自动配置）会把各自的时机打给你看——你的属性类靠 @EnableConfigurationProperties 走「直送」，SmsClient 走 @Bean，自动配置类本身走清单。最后点 miss，看清「包没被扫到」和「清单没登记」为什么会报出同一句话：

实验按到这里，可以换成命令行自己敲。下面这台控制台连着浏览器里的同一个内核，回显全部由内核算出来：

这个沙盘模拟使用方项目的最终状态。左边两个旋钮：总开关怎么写、使用方有没有自己定义同类型 Bean。右边立刻给出容器里到底有哪个 SmsClient，以及注入处会不会炸。

先把结论摆在这里：一个设计合格的 Starter 必须同时提供「关得掉」（sms.enabled）和「换得掉」（@ConditionalOnMissingBean）两个口子。前者的目的是让使用方在自己的 application.yml 里就能表达意图，后者的目的是让用户自定义永远压过你的默认实现——这是第五节逐注解解读的落点。

下表第一列可以直接整段粘进搜索框，别意译也别缩写；最后一列指出去哪一篇深挖。

上面最后两行的区别，只有在真堆栈上点一次才分得清。这段是 starter 作者收到最多的那张工单：依赖引了、yml 写了、Bean 却说找不到。先别看解析——点出你认为的凶手行：

目标：15 分钟做一个最小可用 starter，把「引依赖 → 生效 → 关掉 → 不生效」四态走一遍。

使用方 application.yml 与预期输出：

验收清单：① 把 echo.enabled 改成 false，注入处应报 NoSuchBeanDefinitionException；② jar tf 看 autoconfigure 包里有 .class 和那份 imports，starter 包里只有 pom；③ 说出「为什么删掉 setter 会导致 tag 变回默认值」。

每个变体只动一处，观察点各不相同：

1. 给 EchoProperties 加一个 @Min(100) private int delay = 500;，但不加 @Validated。你会观察到：把 echo.delay 写成 50 照样启动成功——这就是第三节的坑，校验静默失效；补上类级别的 @Validated 后再试，启动即报 must be greater than or equal to 100。
2. 把 imports 文件从 META-INF/spring/ 移到 META-INF/（只挪位置，内容不动）。你会观察到：启动无任何报错，但 EchoService 再也不存在，--debug 报告里连 EchoAutoConfiguration 这个名字都搜不到——这正是第十六节倒数第二行的成因。
3. 在使用方项目里自己写一个 @Bean EchoService，然后把它所在的配置类分别放在「普通 @Configuration」和「被 @AutoConfiguration 标注」两种位置。你会观察到：前者 @ConditionalOnMissingBean 正常让路，后者容易撞进第十五节沙盘「true + 有一个」那一格，出现两个候选 Bean。
4. 把 @ConditionalOnProperty 从类级别挪到 @Bean 方法级别，再把 echo.enabled 设为 false。你会观察到：EchoProperties 依然存在（因为 @EnableConfigurationProperties 还在类上），只是 EchoService 不再生成——开关的作用域变小了。

做一个公司内部 starter：oss-spring-boot-starter，把「阿里云 OSS 上传」包装成开箱即用。

• 结构必须是两个模块 + 四个文件（属性类、核心服务类、自动配置类、imports 清单），命名遵守第九节表格
• 属性至少含 oss.enabled / oss.endpoint / oss.bucket / oss.access-key / oss.secret-key / oss.timeout，其中 access-key、secret-key 用 @NotBlank，timeout 用 @Min(500)，并带上 @Validated
• 提供 OssClient 接口 + 一个默认实现，默认实现的 @Bean 方法必须标 @ConditionalOnMissingBean，让使用方能换成自己的 mock 实现
• 附带 additional-spring-configuration-metadata.json，给 oss.enabled 写上 description 与 defaultValue，让 IDE 有提示
• 写一个 OssAutoConfigurationTest，用 ApplicationContextRunner 覆盖四种组合：默认开、enabled=false、用户自定义实现、缺 endpoint 时启动失败

验收清单：① 使用方只写 <dependency> + 5 行 yml 即可注入 OssClient；② --debug 报告里能同时看到一条 Positive match 与一条因 enabled=false 产生的 Negative match；③ 故意把 yml 的 access-key 留空，启动立刻失败并点名该字段；④ 使用方定义自己的 OssClient 时，容器里只有他那个（用断言 doesNotHaveBean 或 hasSingleBean 证明）；⑤ 把你的 starter 装进一个全新项目，全程不需要写一行 @Bean。