要在spring boot 3.2中开发可扩展的自定义starter,必须使用meta-inf/spring/org.springframework.boot.autoconfigure.autoconfiguration.imports声明自动配置类,并精准运用@conditionalonclass(需字符串类名)、@conditionalonproperty(matchifmissing=false控制开关)、@conditionalonmissingbean(指定类型参数)和@conditionalonwebapplication(加在类上)等新版条件注解。

要在Spring Boot 3.2中开发具备扩展能力的自定义Starter,必须精准使用新版条件注解体系——Spring Boot 3.2废弃了spring.factories机制,全面转向META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件声明自动配置类,且部分Condition注解行为发生语义变更。
创建AutoConfiguration.imports声明入口
在src/main/resources/META-INF/spring/目录下新建org.springframework.boot.autoconfigure.AutoConfiguration.imports文件(注意路径和文件名完全一致,大小写敏感)。
逐行写入自动配置类全限定名,每行一个,不可有空格或注释:
【com.example.sms.autoconfigure.SmsAutoConfiguration】
这一步不可跳过或写错路径,否则Spring Boot 3.2启动时完全不会扫描该配置类,后续所有条件逻辑均失效。
用@ConditionalOnClass检测依赖存在性
方法一:检测核心客户端类是否存在
在自动配置类上添加@ConditionalOnClass,指定你封装功能所依赖的第三方类:
@ConditionalOnClass(name = "com.aliyuncs.DefaultAcsClient")
注意:Spring Boot 3.2要求显式使用name属性传入字符串类名,不能直接写DefaultAcsClient.class——否则编译通过但运行时因类未加载而判定失败。
方法二:同时检测多个类
用数组形式传入多个类名字符串:
@ConditionalOnClass(name = {"com.tencentcloud.common.Credential", "com.tencentcloud.sms.v20190711.SmsClient"})
只要数组中任意一个类在classpath中存在,条件即满足。适合多厂商短信SDK兼容场景。
用@ConditionalOnProperty控制功能开关
第一步:定义配置属性前缀
在自动配置类上添加@EnableConfigurationProperties(SmsProperties.class),确保属性绑定生效。
第二步:声明启用开关
在@Bean方法上加注解:
@ConditionalOnProperty(prefix = "custom.sms", name = "enabled", havingValue = "true", matchIfMissing = false)
【matchIfMissing = false是关键】 表示如果用户application.yml里根本没配custom.sms.enabled,则默认不启用该Bean——避免误触发生产环境短信发送。
第三步:支持多级开关嵌套
例如只在测试环境启用模拟模式:
@ConditionalOnProperty(prefix = "custom.sms.mock", name = "enabled", havingValue = "true")
此时需同时满足custom.sms.enabled=true与custom.sms.mock.enabled=true才加载MockSmsService。
用@ConditionalOnMissingBean实现安全覆盖
① 声明Bean时必须指定类型参数
错误写法:@ConditionalOnMissingBean
正确写法:@ConditionalOnMissingBean(SmsService.class)
② 若用户已在主应用中定义同类型Bean,你的Starter不会覆盖它,而是静默跳过注册。
③ 支持按名称排除:
@ConditionalOnMissingBean(value = SmsService.class, ignored = DefaultSmsService.class)
表示即使容器中已存在DefaultSmsService实例,只要没有其他SmsService实现,仍会注入当前Bean。
④ 注意:Spring Boot 3.2中@ConditionalOnMissingBean不再支持search = SearchStrategy.ALL参数,如需跨层级查找,请改用@Primary配合手动注入。
用@ConditionalOnWebApplication限定运行环境
仅当项目是Web应用时才加载短信配置:
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
若项目为Reactive Web(如WebFlux),需改为Type.REACTIVE;若两者都支持,去掉type参数即可。
这个注解必须加在配置类上,不能加在单个@Bean方法上——加在方法上会导致Spring Boot 3.2忽略该条件。











