Spring Boot Starter
Spring Boot Starter 是集中引入一项功能所需依赖的模块,通常配合自动配置,让应用获得默认组件。比如多个应用都需要支付客户端,就可以把依赖和装配规则放在 Starter 及其自动配置模块中维护。设计时要说清楚:引入后会创建什么、用户怎样替换默认实现,以及缺少可选依赖时能否正常启动。本文以 Boot 3.5 为准。
1. 面试核心
先记住这几条,再读正文- Starter 模块聚合运行依赖,自动配置模块负责配置属性和默认 Bean 的装配,两项职责要分清。卡 · Starter 与自动配置模块
- Boot 3.x 从
AutoConfiguration.imports发现自动配置候选,再按条件决定是否注册。 - 配置处理器生成的元数据供 IDE 提示属性名、类型和默认值,实际绑定与校验由配置基础设施完成。
ApplicationContextRunner用精简上下文验证默认创建、用户替换、功能关闭和缺少依赖等情况。- 可选类型要隔离在带类条件的配置中,让 Spring 先判断类是否存在,再处理相关 Bean 方法。卡 · 可选依赖隔离
2. Starter 与自动配置模块
Starter 负责引入依赖,自动配置负责注册组件。把支付客户端提供给多个应用时,可以按这两项职责拆成两个模块:
acme-payment-spring-boot
└── 自动配置、属性类与扩展接口
acme-payment-spring-boot-starter
└── 自动配置模块与常用运行时依赖
Starter 本身主要声明依赖,创建 Bean 的逻辑放在自动配置模块。这样,依赖聚合与默认装配可以分别维护。简单组件可合为一个模块,但仍应区分两项职责。
在 Maven 中,自动配置模块可以把可选第三方库标为 optional,使它不作为传递依赖自动进入使用者的应用。Starter 再引入默认运行所需的库,让应用通过一个入口完成接入。第三方模块名使用自己的前缀,避免使用官方的 spring-boot-* 命名。
3. 自动配置登记
自动配置类需要登记,Boot 才能找到它。Boot 3.x 使用 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports,文件每行填写一个自动配置类全限定名。
配置类放在专用包中,通过 imports 文件进入容器,避免被业务应用的组件扫描偶然发现。内部组件使用明确的 @Import 导入,装配范围因此更容易控制。
默认 Bean 通过条件注解控制,属性类可用 @EnableConfigurationProperties 启用绑定。示例见 Spring Boot 自动配置。
4. 对外接口
Starter 的对外接口既包括 Java 类型,也包括依赖和配置。使用者需要知道引入后会得到什么、哪些行为可以调整,因此要说明三类约定:
- 依赖约定列出直接依赖、传递依赖与支持版本,让应用知道会引入哪些运行时库。
- 配置约定说明属性前缀、类型、单位、默认值和校验规则,并给出废弃策略。
- Bean 约定列出默认组件与替换接口,让用户知道怎样接入自己的实现。
例如,支付组件统一使用 acme.payment.* 前缀,让属性名与应用自身、其他库的配置区分开。配置元数据是供工具读取的属性说明,记录属性名、类型和默认值等信息。编译时,spring-boot-configuration-processor 将它生成到 META-INF/spring-configuration-metadata.json,IDE 读取后就能提供补全和提示。
元数据只描述属性,不负责执行绑定和校验;实际工作由 @ConfigurationProperties 等基础设施完成。字段改名要留兼容期并说明替代属性,原有参数的单位和含义也要保持稳定。例如,不能在升级时把同一个超时参数从毫秒改成秒,否则旧配置会得到完全不同的超时时间。
5. 条件与覆盖
默认装配要给用户保留关闭和替换的入口。可以组合三个条件:@ConditionalOnClass 检查所需类是否存在,@ConditionalOnProperty 检查功能是否启用,@ConditionalOnMissingBean 检查用户是否已提供实现。三者满足时才注册默认 Bean;用户已经提供实现时,就跳过默认注册,这叫作退让。
退让的执行过程见 Spring Boot 自动配置。
如果应用需要同时使用多个客户端,应设计明确的限定符、客户端注册表或 builder 定制接口。builder 用于逐项设置参数后构造客户端。单个 MissingBean 条件适合替换唯一默认实现;多个客户端如何命名和选择,仍需由扩展接口明确表达。
6. 隐式副作用
启动副作用是组件装配时顺带改变外部状态的行为,例如启动线程或写入远程系统。它会直接影响引入 Starter 的应用,所以默认行为和资源归属要明确:
- 用明确的
@Import组织内部组件,避免宽泛扫描把应用的业务类意外注册。 - 后台线程交给受管理的执行器,提供开关、超时和关闭回调。
- 全局系统属性和默认 Locale 由宿主决定,组件使用自己的局部配置。
- 远程写入、建表,以及产生外部费用的操作,需要显式启用。
- 用户已有的序列化、安全和线程池配置应受到尊重,默认组件按条件退让。
需要外部连接的组件还应报告健康状态,输出清晰日志,并说明连接失败是否阻止应用就绪。这样,宿主才能判断何时接收流量、关闭时由谁释放资源。具体业务流程应由应用服务编排,避免隐藏在所有应用的启动阶段。
7. 条件组合测试
自动配置测试要检查不同条件下实际出现了哪些 Bean。ApplicationContextRunner 是创建并运行精简测试上下文的工具,测试结束后会关闭上下文,适合验证这些结果:
- 条件满足时,只创建预期的默认 Bean。
- 用户提供自定义 Bean 时,默认配置会退让。
- 显式关闭功能时,对应 Bean 不会创建。
- 缺少可选依赖时,上下文仍能启动,且无
ClassNotFoundException。 - 配置值错误时,启动会给出明确失败信息。
- 条件评估报告能说明匹配或未匹配的原因。
下面的测试检查关闭支付功能后的结果:
new ApplicationContextRunner()
.withConfiguration(AutoConfigurations.of(PaymentAutoConfiguration.class))
.withPropertyValues("acme.payment.enabled=false")
.run(context -> assertThat(context).doesNotHaveBean(PaymentClient.class));
下节的自动配置使用 acme.payment.enabled 开关。测试将其设为 false,断言上下文中没有默认客户端,验证关闭功能确实阻止了装配。
用户替换场景可用 withUserConfiguration(...) 加入自定义 Bean,缺类场景则用 FilteredClassLoader 隐藏可选库。最后还要在支持的 Boot、Java 版本组合上验证完整接入。依赖树也要检查,确认 Starter 是否意外升级了日志、网络或序列化组件。
8. 可选依赖隔离
可选库缺失时,自动配置需要安全跳过对应组件。只在返回可选类型的 @Bean 方法上加类条件,仍有加载风险。因为 JVM 解析方法签名时,就可能先加载返回类型,早于方法条件的评估。为此,可以把可选类型放入独立的条件配置类:
@AutoConfiguration
public class PaymentAutoConfiguration {
@Configuration(proxyBeanMethods = false)
@ConditionalOnClass(PaymentClient.class)
@ConditionalOnProperty(prefix = "acme.payment", name = "enabled",
havingValue = "true", matchIfMissing = true)
static class ClientConfiguration {
@Bean
@ConditionalOnMissingBean
PaymentClient paymentClient() {
return new PaymentClient();
}
}
}
示例把 PaymentClient 隔离在嵌套配置类中。Spring 先读取类级注解元数据,确认客户端类型存在后,再处理其中的 Bean 方法。客户端有无参构造器时,这个方法就能创建默认实例;用户已提供客户端时,MissingBean 条件使默认实现退让。
测试时,可通过 new FilteredClassLoader(PaymentClient.class) 隐藏这个类型。如果隔离有效,上下文应能启动,同时没有默认客户端。
9. 常见问题
9.1 只有一个 Java 工具库,也需要做成 Starter 吗?
不一定。如果库只提供 Java API,不需要向容器注册默认组件,普通依赖就够了。多个应用确实要复用同一套依赖与装配规则时,再用 Starter 集中维护。
9.2 引入 Starter 后没有出现预期的 Bean,怎样排查?
先区分配置有没有被发现、条件有没有通过,以及 Bean 是否创建失败,再沿装配过程查找:
- 检查 JAR 中的 imports 文件,确认已登记目标配置类。
- 查看条件评估报告,找到具体未匹配项。
- 核对配置属性是否绑定,以及用户 Bean 是否已让默认实现退让。
- 检查依赖版本是否一致,再沿异常链确认创建失败的原因。
10. 面试题卡片
11. 参考资料
- Spring Boot:Creating Your Own Auto-configuration
- Spring Boot:Configuration Metadata
- Spring Boot:Testing Auto-configuration
- Spring Boot 3.5:Class Conditions and Testing
- Spring Boot 3.5:Generating Configuration Metadata
来源:Coding 101 原文 · 免费阅读,引用请保留出处。内容使用说明