用了这么多年 Spring Boot多数人的日常是spring-boot-starter-web一把梭spring-boot-starter-data-redis再一把梭项目起来了包也引了一堆。可真要自己动手写一个 starter很多人第一反应是“这玩意儿不是框架作者才干的事吗”。我以前也这么想直到有一次公司内部要统一对接一套企业微信的消息推送 SDK十几个服务都要接每个项目里复制粘贴一遍初始化代码、封装工具类、配置读取逻辑改一个参数得全量通知所有服务方重新发布。那会儿我意识到自定义 Starter 不是炫技是偷懒的刚需。这篇文章就把我实际写自定义 Starter 的完整思路、代码细节、踩坑记录都摊开讲。适合两类人看一类是想把自己公司的公共组件、SDK 整理成标准依赖的架构师或后端开发另一类是准备面试被问到“Spring Boot 自动配置原理”相关问题想拿真实经验说话的求职者。1. 动手前的认知Starter 到底是干什么的1.1 Starter 机制的本质约定大于配置Spring Boot 的 Starter 看起来就是一堆依赖的集合一个pom.xml引进去功能就有了。但这只是表面。它真正的价值在于“自动配置”这四个字。我习惯把 Starter 理解成“一个自带安装程序的三方库”。普通 jar 包引入后你得自己 new 对象、自己读配置、自己管理生命周期。而 Starter 引入后Spring Boot 启动时会自动检测 classpath 下的类自动创建对应的 Bean、自动绑定application.yml里的配置项。你的业务代码里什么都不用写直接Autowired就能用。这个机制的核心是EnableAutoConfiguration注解它会让 Spring Boot 去读取所有 jar 包META-INF目录下的自动配置声明文件然后把符合条件的Configuration配置类加载进来。写自定义 Starter本质上就是写一个“能被 Spring Boot 自动识别并加载的配置模块”。1.2 判断要不要拆成 Starter三个标准不是说所有公共代码都要做成 Starter。拆之前先问自己三个问题都满足了再做第一是否被多个独立服务复用。注意是“独立服务”不是同一个工程里多个模块。模块之间用内部依赖就行没必要上 Starter。三个以上不同服务都要用同一个组件才值得考虑。第二初始化逻辑是否复杂。比如连接池、客户端构建、密钥加解密、多个配置项映射这些初始化代码少说几十行多则上百行。如果只是提供一个静态工具方法那打成普通 jar 包就够了Starter 反而过度设计。第三是否需要跟随 Spring 生命周期。比如要在应用启动后执行回调、要监听容器事件、要感知配置刷新这种强耦合 Spring 容器的场景必须用 Starter 的自动配置方式。我踩过的坑是早期把公司一个加密工具类也做成了 Starter结果自动配置类加了各种条件注解最后发现根本没有 Bean 需要注入纯属给自己加戏。后来那个 Starter 就被降级成普通工具包了。1.3 命名规范官方约定和自定义前缀命名这东西看着不起眼但我见过太多人在这上面吃亏。官方 Starter 的命名格式是spring-boot-starter-{模块名}比如spring-boot-starter-web。自定义 Starter 官方推荐用{模块名}-spring-boot-starter比如myapp-redis-spring-boot-starter。这么设计是有讲究的你自己的模块名放前面别人一看就知道这个 Starter 是干什么的后半段统一用spring-boot-starter结尾Maven 中央仓库和 IDE 插件才能识别出这是 Spring Boot 生态的组件。但是要注意如果你的项目引了官方 Starter 又自定义了同名前缀的类很容易出现 Bean 冲突。我建议自定义类的前缀用公司缩写或模块缩写比如com.company.xxx.autoconfigure避免和官方命名空间撞车。另外一个细节Starter 本身通常是个空 jar只负责引入依赖真正干活的是 auto-configuration 模块。所以实际项目里经常拆成两个模块xxx-spring-boot-starter依赖聚合和xxx-spring-boot-autoconfigure自动配置逻辑。小项目可以合并成一个但模块多了以后拆开是正解不然用户只想用你的一小部分功能还得引入全部依赖。2. 自定义 Starter 的核心实现从依赖到自动配置类2.1 工程结构怎么摆我这边以 Maven 项目为例标准的 Starter 工程结构长这样my-starter-demo/ ├── pom.xml └── src/ └── main/ ├── java/ │ └── com/example/demo/ │ ├── DemoProperties.java │ ├── DemoService.java │ └── DemoAutoConfiguration.java └── resources/ └── META-INF/ └── spring.factories如果你用的是 Spring Boot 2.7 及以上版本resources/META-INF/下还可以放一个org.springframework.boot.autoconfigure.AutoConfiguration.imports文件来替代spring.factories这个后面细说。但老项目或者要兼容老版本spring.factories仍然要保留。2.2 引入最小的依赖自定义 Starter 不需要引spring-boot-starter-web这种重量级依赖因为它本身不处理 Web 请求。核心依赖其实就两个dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-autoconfigure/artifactId version2.7.18/version scopeprovided/scope /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-configuration-processor/artifactId version2.7.18/version optionaltrue/optional /dependency注意spring-boot-autoconfigure的 scope 我用了provided因为用户的工程里必然会引入 Spring Boot这个 jar 只是编译期需要。spring-boot-configuration-processor是配置元数据处理器它会扫描ConfigurationProperties注解的类在编译时生成spring-configuration-metadata.json这样用户在 IDE 里写配置时会有自动提示。这个依赖一定要设为optional避免传递到用户的工程里。2.3 配置属性类让用户用得爽的第一道关卡写配置属性类是最见功力的地方。好的属性设计能让你少写很多文档差的设计能让用户骂娘。一个规范的配置属性类长这样ConfigurationProperties(prefix demo) public class DemoProperties { /** * 是否开启 demo 功能默认开启 */ private boolean enabled true; /** * 服务地址必填项 */ private String url; /** * 超时时间单位毫秒默认 3000 */ private long timeout 3000L; /** * 重试次数默认 3 */ private int retryCount 3; // getter 和 setter 省略 }关键点有三个第一个prefix 一定要短且唯一。demo前缀用户写配置就是demo.urlxxx。我之前见过有人用com.example.myproject.config这种前缀写配置的时候能把人逼疯。第二个所有属性都必须有默认值。这一点极其重要。默认值能让 Starter 在用户不配置任何东西的情况下也运行得起来至少能启动不报错。即使某个属性是必填项也别直接null了之可以在自动配置类里做校验抛出一个明确的异常提示“demo.url is required”。第三个用 Javadoc 注释写清楚每个字段的含义和单位。这个注释不是给代码看的是给客户看的功能说明。配合spring-boot-configuration-processor用户的 IDE 里就能看到这些注释渲染出来的文档说明。2.4 服务类业务逻辑和 Spring 解耦属性配置类负责接收配置服务类负责真正干活。服务类的设计有个分寸要拿捏既要不依赖 Spring 的 API又要能优雅地融入 Spring 容器。比如你要封装一个发送消息的服务可以这样设计public class DemoService { private final DemoProperties properties; public DemoService(DemoProperties properties) { this.properties properties; } public String ping(String input) { // 这里实际发起调用用 properties 里的 url、timeout 等配置 return pong: input , timeout properties.getTimeout(); } }注意这个类没有任何 Spring 注解它就是一个纯 POJO。好处是单元测试特别方便new DemoService(props)就能测。真正把它交给 Spring 的是后面的自动配置类。这样职责清晰DemoProperties管配置、DemoService管业务、DemoAutoConfiguration管装配。2.5 自动配置类整个 Starter 的心脏自动配置类是决定 Starter 能不能在 Spring Boot 里正常工作的地方。最基础的写法如下Configuration ConditionalOnClass(DemoService.class) EnableConfigurationProperties(DemoProperties.class) public class DemoAutoConfiguration { Bean ConditionalOnMissingBean public DemoService demoService(DemoProperties properties) { return new DemoService(properties); } }这个类上有三个注解每一个都有讲究。Configuration让 Spring 把它当作配置类处理这是最基本的。重点在下面两个。ConditionalOnClass(DemoService.class)是一个条件注解它的意思是classpath 里存在 DemoService 这个类时才加载这个配置类。这是 Spring Boot 自动配置的精髓——把判断交给 classpath而不是交给配置文件。用户引了你的 Starter类就在没引类就不在配置类自然不会被加载。这种机制保证 Starter 是“即插即用”的不需要用户在application.yml里写开关。EnableConfigurationProperties(DemoProperties.class)把配置属性类注册为 Spring 管理的 Bean并且自动完成application.yml里demo.*配置项到DemoProperties对象字段的绑定。这里有个细节有人会问为什么不用Component直接标注在DemoProperties上让它被扫描到。答案是不推荐因为你的 Starter 是引到用户工程里的组件扫描扫不到第三方 jar 包里的类即使扫描到了也无法保证配置绑定的时机。ConditionalOnMissingBean加在demoServiceBean 方法上意思是如果用户已经自己定义了一个DemoService类型的 Bean那就不再创建。这么做是给用户留了后门让他们可以完全覆盖你提供的默认实现。2.6 老版本和新版本的注册方式差异这里专门说一下自动配置类的注册方式因为版本差异太大我见过不少人在升级 Spring Boot 后 Starter 突然失效排查半天才发现是注册方式变了。Spring Boot 2.7 之前自动配置类的注册是在resources/META-INF/spring.factories文件里完成的org.springframework.boot.autoconfigure.EnableAutoConfiguration\ com.example.demo.DemoAutoConfigurationSpring Boot 2.7 之后官方推荐改用META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件内容更简洁com.example.demo.DemoAutoConfiguration到了 Spring Boot 3.xspring.factories方式被移除了必须用 imports 文件。所以如果你要做一个要长期维护的 Starter我建议在兼容的版本里两个文件都放。2.7 以下的用spring.factories2.7 及以上用 imports 文件两边都声明同一个自动配置类。还有一个版本相关的坑Spring Boot 2.7 引入了AutoConfiguration注解它其实是个组合注解等于Configuration(proxyBeanMethods false)加上自动配置的语义。如果用了这个注解自动配置类还可以实现AutoConfiguration.imports的排序接口控制多个自动配置类的加载顺序。这里不展开大家知道有这个东西就行。3. 一行一行写代码一个可运行的日志记录 Starter 手工实践3.1 需求场景定义前面全是理论现在来点实实在在的。我以一个“操作日志自动记录 Starter”为例完整走一遍开发流程。需求是这样的公司内部多个服务都希望把用户的关键操作登录、下单、修改密码等自动记录到日志表或者发送到消息队列。以前每个服务各自的实现方式都不一样有的用 AOP 切面有的在业务代码里手动打点。现在统一做一个 starter业务方引入依赖后只要在方法上加一个注解就能自动记录操作日志。这个场景很典型有注解、有 AOP 切面、有配置项、有自动装配几乎覆盖了 Starter 开发的全部要点。3.2 第一步定义注解和属性类先定义注解这是给用户使用的入口package com.example.operationlog.annotation; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) public interface OperationLog { /** * 操作类型比如 login、order、update */ String type(); /** * 操作描述比如“用户登录”“创建订单” */ String desc() default ; }再定义配置属性类package com.example.operationlog.config; import org.springframework.boot.context.properties.ConfigurationProperties; ConfigurationProperties(prefix operation.log) public class OperationLogProperties { /** * 是否启用操作日志功能默认启用 */ private boolean enabled true; /** * 日志存储方式console 输出、db 存储、mq 发送默认 console */ private String storeType console; public boolean isEnabled() { return enabled; } public void setEnabled(boolean enabled) { this.enabled enabled; } public String getStoreType() { return storeType; } public void setStoreType(String storeType) { this.storeType storeType; } }属性类里的enabled是给用户留的“全局开关”storeType是给用户留的“存储策略选择”。这种设计能让一个组件适应不同环境比如测试环境用 console 输出生产环境用 db 存储。3.3 第二步编写日志记录服务接下来是核心服务类。这里我设计成两种角色一个OperationLogService接口负责定义日志发送的契约一个默认实现负责把日志打到控制台。package com.example.operationlog.service; public interface OperationLogService { void record(String operator, String type, String desc, String result); }package com.example.operationlog.service.impl; import com.example.operationlog.service.OperationLogService; import org.slf4j.Logger; import org.slf4j.LoggerFactory; public class DefaultOperationLogService implements OperationLogService { private static final Logger log LoggerFactory.getLogger(DefaultOperationLogService.class); Override public void record(String operator, String type, String desc, String result) { log.info(操作日志 | 操作人: {} | 类型: {} | 描述: {} | 结果: {}, operator, type, desc, result); } }为什么要把服务定义成接口因为不同的storeType对应不同的实现用户可能想用自己的日志存储系统。用接口 条件装配的组合用户自定义一个OperationLogServiceBean 就可以完全覆盖默认实现。3.4 第三步AOP 切面实现自动记录有了注解和服务还需要一个切面把两者串联起来。AOP 切面本身也是一个普通的类但它必须由 Spring 管理并且需要引入spring-boot-starter-aop依赖package com.example.operationlog.aspect; import com.example.operationlog.annotation.OperationLog; import com.example.operationlog.service.OperationLogService; import org.aspectj.lang.ProceedingJoinPoint; import org.aspectj.lang.annotation.Around; import org.aspectj.lang.annotation.Aspect; import org.aspectj.lang.reflect.MethodSignature; import org.springframework.beans.factory.annotation.Autowired; Aspect public class OperationLogAspect { Autowired private OperationLogService operationLogService; Around(annotation(operationLog)) public Object around(ProceedingJoinPoint joinPoint, OperationLog operationLog) throws Throwable { long startTime System.currentTimeMillis(); String result success; try { return joinPoint.proceed(); } catch (Throwable throwable) { result error: throwable.getMessage(); throw throwable; } finally { long cost System.currentTimeMillis() - startTime; String operator resolveOperator(); String desc operationLog.desc(); if (desc.isEmpty()) { desc operationLog.type(); } operationLogService.record(operator, operationLog.type(), desc, result , cost cost ms); } } private String resolveOperator() { // 实际场景里可以从 SecurityContext、ThreadLocal、Header 里获取当前登录用户 return unknown; } }这个切面有几个值得说的细节。Around(annotation(operationLog))这种写法是直接把注解对象作为参数传入通知方法这样在方法体内可以直接拿到注解上的type()和desc()属性。比用反射再去getAnnotation要干净许多。finally块里做日志记录保证了无论方法成功还是抛异常都会记录。同时把异常继续抛出去不吞掉业务异常这一点很重要。有些初学者容易在切面里把异常 catch 了就不管了导致业务方完全感知不到失败。resolveOperator()返回的是操作人实际场景里基本都是从安全上下文里取。我这里没有引入具体的 Spring Security 依赖只是给你留了个扩展点的大致框架。3.5 第四步编写自动配置类并串联所有组件现在把前面的组件全部装配到一起package com.example.operationlog.config; import com.example.operationlog.aspect.OperationLogAspect; import com.example.operationlog.service.OperationLogService; import com.example.operationlog.service.impl.DefaultOperationLogService; import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration EnableConfigurationProperties(OperationLogProperties.class) ConditionalOnProperty(prefix operation.log, name enabled, havingValue true, matchIfMissing true) public class OperationLogAutoConfiguration { Bean ConditionalOnMissingBean public OperationLogService operationLogService() { return new DefaultOperationLogService(); } Bean ConditionalOnMissingBean public OperationLogAspect operationLogAspect(OperationLogService operationLogService) { return new OperationLogAspect(); } }注意两个条件注解的配合。ConditionalOnProperty加在配置类上判断operation.log.enabled配置项。matchIfMissing true意味着当用户没配置这个属性时默认匹配成功整个 Starter 默认生效。如果用户想关闭只要在配置文件里写operation.log.enabledfalse就行。ConditionalOnMissingBean分别加在服务和切面的 Bean 上。用户如果只自定义了OperationLogService那切面还是会自动装配而且注入的是用户的实现。用户如果连切面也想自己控制也可以自己定义。3.6 第五步注册自动配置类最后一步是把自动配置类告诉 Spring Boot。我同时准备了两种方式方便你在不同版本下切换。在src/main/resources/META-INF/spring.factories里写org.springframework.boot.autoconfigure.EnableAutoConfiguration\ com.example.operationlog.config.OperationLogAutoConfiguration在src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports里写com.example.operationlog.config.OperationLogAutoConfiguration这里有个特别容易踩的坑文件路径必须完全正确比如AutoConfiguration.imports文件名是固定的org.springframework.boot.autoconfigure.AutoConfiguration.imports少一个字符都加载不到。而且这个文件必须在META-INF/spring/目录下不是META-INF/下。我第一次写的时候就把文件放错位置结果 Spring Boot 静默忽略项目不报错但 Starter 就是不生效排查了很久。3.7 构建和本地验证写完之后用 Maven 打包mvn clean install然后新建一个测试工程引入这个 Starterdependency groupIdcom.example/groupId artifactIdoperation-log-spring-boot-starter/artifactId version1.0.0/version /dependency测试工程里写一个简单接口RestController public class TestController { OperationLog(type login, desc 用户登录) GetMapping(/login) public String login(RequestParam String username) { return welcome username; } }启动测试工程访问/login?usernamezhangsan控制台输出INFO 12345 --- [nio-8080-exec-1] c.e.o.service.impl.DefaultOperationLogService : 操作日志 | 操作人: unknown | 类型: login | 描述: 用户登录 | 结果: success, cost2ms到这里一个真正可用的 Starter 就算完工了。业务方引入依赖在方法上加一个注解日志记录就自动生效了。4. 项目里实战常用的进阶技巧条件装配与自动配置排序4.1 条件注解全家桶让 Starter 更聪明前面代码里已经用了ConditionalOnClass、ConditionalOnMissingBean、ConditionalOnProperty但 Spring Boot 的条件注解远不止这几个。我把项目中真正用得上的整理一下。ConditionalOnBean和ConditionalOnMissingBean是互补的。一个判断容器中已有某个 Bean 时生效一个判断没有时生效。这里有一个极大的坑这两个注解的判断时机。如果放在配置类上它是在配置类解析阶段判断的此时很多 Bean 还没注册如果放在Bean方法上它是在方法执行阶段判断的时机要晚一些。所以大多数情况下ConditionalOnMissingBean应该放在Bean方法上而不是配置类上。ConditionalOnExpression可以写 SpEL 表达式。我见过一个场景某个功能开关要同时看两个配置项比如demo.enabledtrue且demo.modefull才生效这时用ConditionalOnExpression(${demo.enabled:true} ${demo.mode:full} full)就能搞定。但要注意 SpEL 表达式里字符串比较的写法少了引号就会报错。ConditionalOnWebApplication和ConditionalOnNotWebApplication是判断应用类型的。比如某个 Starter 只服务于 Web 项目可以加这个注解非 Web 项目里直接跳过省得浪费加载时间。这几个注解组合起来可以让同一个 Starter 在不同场景下表现不同行为。比如我做过一个消息推送 StarterWeb 环境下它自动注册 HTTP 接口用于推送回调非 Web 环境下不注册接口只提供服务实现。一个 jar 包解决了两种项目的需求。4.2 自动配置类的加载顺序控制多个 Starter 之间可能存在依赖关系。比如你写了一个common-spring-boot-starter里面定义了公司统一的RestTemplate配置又写了一个order-spring-boot-starter内部依赖RestTemplate。这时就必须保证common的自动配置先执行否则order的自动配置在装配RestTemplate时可能还没创建。Spring Boot 提供了三个控制顺序的注解AutoConfigureBefore表明当前自动配置在指定的自动配置之前执行。AutoConfigureAfter表明当前自动配置在指定的自动配置之后执行。AutoConfigureOrder用 Order 值排序值越小越先执行。举个例子Configuration AutoConfigureAfter(CommonAutoConfiguration.class) public class OrderAutoConfiguration { // ... }这段代码的含义是OrderAutoConfiguration必须在CommonAutoConfiguration之后加载。这样OrderAutoConfiguration里注入RestTemplate时容器里已经存在了。值得提醒的是顺序注解只在自动配置类之间生效对用户自己Configuration定义的配置类不生效。因为自动配置类的加载时机是在用户的配置类之后顺序只影响自动配置类之间的相对顺序。4.3 与 Spring Boot 3.x、微服务框架的兼容问题Spring Boot 3.x 的变化不仅仅是注册方式还有一个重要升级基于 Java 17 Jakarta EE 9。如果说你的 starter 内部用到了一些旧的javax.*包比如javax.annotation.PostConstruct在 Boot 3.x 里会直接编译失败必须换成jakarta.annotation.PostConstruct。另外如果你所在的团队用的是 Spring Cloud自定义 Starter 可能会和配置中心、注册中心产生联动。我的建议是先不要让你的 Starter 直接依赖 Spring Cloud 的 API除非万不得已。因为 Spring Cloud 版本升级频繁牵一发动全身。更好的方式是定义一个抽象的ConfigurationProvider接口让用户的配置从本地application.yml读取还是从配置中心读取由用户自己去适配。我踩过的一个真实的坑是早期做了一个读写分页的 Starter直接在代码里用了 Nacos 的NacosValue注解实现配置动态刷新。后来公司统一升级 Spring Cloud 版本Nacos 客户端 API 变化我的 Starter 也得跟着改所有接入方都得升级依赖。如果当时设计成暴漏一个接口让用户自己实现配置刷新就没这档子事了。5. 常见问题排查自定义 Starter 不生效的现场实录5.1 自动配置类根本没被加载这是最多人遇到的问题。现象是引用之后启动自定义的 Bean 完全不存在Autowired直接报错。排查思路分三步走第一步确认自动配置类有没有被注册。Spring Boot 启动时加--debug参数控制台会输出Auto-configuration report里面会列出所有匹配成功、匹配失败、排除的自动配置类。如果你的 Starter 的自动配置类连名字都没出现说明压根没注册如果出现在“匹配失败”里说明条件注解的判断没通过。第二步检查注册文件路径和内容。spring.factories的 key 必须是org.springframework.boot.autoconfigure.EnableAutoConfiguration不是org.springframework.context.annotation.ConfigurationAutoConfiguration.imports文件必须放在META-INF/spring/下不是META-INF/下。这两个是静态资源路径问题写错就是静默失败没有任何报错。第三步看看有没有被排除。如果你在启动类上用了SpringBootApplication(exclude XXXAutoConfiguration.class)或者配置文件里配了spring.autoconfigure.exclude...那也会导致不生效。这属于显式排除一般不会忘了但排查的时候也顺带看一眼。5.2 配置属性绑定不生效用户配置了demo.urlxxx但DemoProperties里拿到的还是 null。最常见的原因是ConfigurationProperties的类没有被EnableConfigurationProperties注册也没有被Component标注。如果只是单纯加了一个ConfigurationProperties注解Spring 容器并不知道要创建这个 Bean配置绑定自然无从谈起。另一个原因是 IDE 缓存。spring-boot-configuration-processor生成的配置元数据有时候不会立即刷新导致配置提示和绑定看起来没生效。这时候可以先mvn clean把target目录清掉再重新编译。还有一个易忽略的点getter 和 setter 必须要有。Spring Boot 的配置绑定底层用的是 JavaBean 属性访问器不是字段反射。只写了字段没写 getter/setter绑定会失败。Lombok 的Data可以处理这个但前提是编译期正常生成了方法。5.3 Bean 重复定义或覆盖问题如果你的 Starter 定义了DemoServiceBean用户也定义了一个DemoServiceBean默认情况下 Spring Boot 会以用户的为准吗不一定。Spring Boot 自动配置类里有ConditionalOnMissingBean注解时才会主动避开用户已有的 Bean。如果没有这个注解两个 Bean 同名或者同类型冲突启动阶段会直接报BeanDefinitionOverrideException或者NoUniqueBeanDefinitionException。所以规范的写法是自动配置类里所有对外暴露的 Bean都要加上ConditionalOnMissingBean。这不是可选项是必选项。这样可以保证用户有权利覆盖 Starter 的默认行为。如果确实希望 Starter 的 Bean 覆盖用户的 Bean可以在配置文件里设置spring.main.allow-bean-definition-overridingtrue但我强烈不建议这么做。全局覆盖开关很危险一个服务里几十个依赖你不知道哪个依赖的 Bean 会被悄悄覆盖。5.4 常见问题速查表我把实际工作中积累的问题现象和排查方向整理成了表格方便你遇到问题时快速定位。问题现象可能原因排查/解决方案Starter 引入后没有任何效果自动配置类未注册检查spring.factorieskey 名、检查 imports 文件路径、用--debug看自动配置报告配置项写了一大堆但值全是 null属性类未注册/未绑定确认EnableConfigurationProperties或ConfigurationProperties正确标注检查是否有 getter/setter项目启动报 Bean 重复缺少ConditionalOnMissingBean自动配置类中的Bean方法统一补上该条件注解用户自定义的 Bean 被覆盖全局允许覆盖检查spring.main.allow-bean-definition-overriding是否被打开升级 Spring Boot 3.x 后失效注册方式变化或 javax API 未替换改用 AutoConfiguration.imports检查 javax 到 jakarta 的迁移配置属性在 IDE 里没有提示缺少配置处理器依赖引入spring-boot-configuration-processor重新编译刷新元数据切面不生效缺少 AOP 依赖或切面类未被注册确认引入了spring-boot-starter-aop切面类是否在自动配置类中被声明为 Bean多个 Starter 之间有依赖关系的 Bean 缺失自动配置加载顺序不对使用AutoConfigureAfter/AutoConfigureBefore/AutoConfigureOrder5.5 调试技巧如何快速定位 Starter 的问题我调试自定义 Starter 时最有用的三招分享给你。第一招是启动时加--debug看自动配置报告。这个前面提过再强调一次因为真的大部分定位都靠它。报告里会显示每个自动配置类匹配的条件注解和匹配结果一眼就能看出你的 Starter 是哪一步没通过。第二招是打断点。自动配置类也是普通的Configuration类可以在类上打条件注解的断点或者在Bean方法打断点。Spring 容器刷新时会直接走到这里你就能实时看到ConditionEvaluator的判断过程。第三招是写一个针对自动配置类的测试。用ApplicationContextRunner这个工具类它专门用于测试自动配置Test void testAutoConfiguration() { new ApplicationContextRunner() .withConfiguration(AutoConfigurations.of(OperationLogAutoConfiguration.class)) .withPropertyValues(operation.log.enabledtrue) .run(context - { assertThat(context).hasSingleBean(OperationLogService.class); assertThat(context).hasSingleBean(OperationLogAspect.class); }); }这个测试不需要启动完整的 Spring Boot 应用跑的极快非常适合在本地验证修改后的自动配置行为。我在开发 Starter 时都会搭一套这种测试每次改完代码跑一遍比手动起一个 demo 工程验证快太多了。6. 从能用到优雅我在实际项目中的最后一公里经验前面讲完了技术实现最后聊一点偏工程实践的东西。我经过几个真实项目的打磨现在写自定义 Starter 之前一定会先做一件事画一个“什么该放 Starter什么不该放”的边界图。Starter 的职责是“把重复的初始化过程自动化”而不是“把所有公共代码都塞进去”。工具类、常量类、纯粹的 DTO 对象这些不该进 Starter连接池管理、客户端构建、切面逻辑、生命周期管理这些才是 Starter 的主场。另一个感悟是文档和示例工程不能省。代码写得再飘逸接入方看不懂一样白搭。我给每个 Starter 都配一个独立的demo模块里面是最小的可运行示例。接入方照着 demo 抄五分钟就能跑通。配置项说明我直接用spring-boot-configuration-processor的元数据注释写在字段上用户 IDE 里鼠标悬停就能看到。最后再分享一个小技巧给 Starter 预留一个enabled开关。即使默认是开启的也一定要留一个全局总开关。因为生产环境出问题的时候甲方要求“立刻下线某个功能”如果没有这个开关你只能重新打包发版有了开关运维改一行配置重启就能搞定。这种细节关键时刻能救你一命。写自定义 Starter 这件事技术上并不难难的是理解它背后“约定大于配置”的设计哲学。当你真正理解了 Spring Boot 是怎么发现你写的自动配置类的你对整个框架的理解都会上一个台阶。希望这份经验能帮你少走点弯路。 
长河君 · 2026/9/9 11:41:30 · 阅读 1.2k 从零手写Spring Boot自定义Starter：自动配置原理与实战
用了这么多年 Spring Boot多数人的日常是spring-boot-starter-web一把梭spring-boot-starter-data-redis再一把梭项目起来了包也引了一堆。可真要自己动手写一个 starter很多人第一反应是“这玩意儿不是框架作者才干的事吗”。我以前也这么想直到有一次公司内部要统一对接一套企业微信的消息推送 SDK十几个服务都要接每个项目里复制粘贴一遍初始化代码、封装工具类、配置读取逻辑改一个参数得全量通知所有服务方重新发布。那会儿我意识到自定义 Starter 不是炫技是偷懒的刚需。这篇文章就把我实际写自定义 Starter 的完整思路、代码细节、踩坑记录都摊开讲。适合两类人看一类是想把自己公司的公共组件、SDK 整理成标准依赖的架构师或后端开发另一类是准备面试被问到“Spring Boot 自动配置原理”相关问题想拿真实经验说话的求职者。1. 动手前的认知Starter 到底是干什么的1.1 Starter 机制的本质约定大于配置Spring Boot 的 Starter 看起来就是一堆依赖的集合一个pom.xml引进去功能就有了。但这只是表面。它真正的价值在于“自动配置”这四个字。我习惯把 Starter 理解成“一个自带安装程序的三方库”。普通 jar 包引入后你得自己 new 对象、自己读配置、自己管理生命周期。而 Starter 引入后Spring Boot 启动时会自动检测 classpath 下的类自动创建对应的 Bean、自动绑定application.yml里的配置项。你的业务代码里什么都不用写直接Autowired就能用。这个机制的核心是EnableAutoConfiguration注解它会让 Spring Boot 去读取所有 jar 包META-INF目录下的自动配置声明文件然后把符合条件的Configuration配置类加载进来。写自定义 Starter本质上就是写一个“能被 Spring Boot 自动识别并加载的配置模块”。1.2 判断要不要拆成 Starter三个标准不是说所有公共代码都要做成 Starter。拆之前先问自己三个问题都满足了再做第一是否被多个独立服务复用。注意是“独立服务”不是同一个工程里多个模块。模块之间用内部依赖就行没必要上 Starter。三个以上不同服务都要用同一个组件才值得考虑。第二初始化逻辑是否复杂。比如连接池、客户端构建、密钥加解密、多个配置项映射这些初始化代码少说几十行多则上百行。如果只是提供一个静态工具方法那打成普通 jar 包就够了Starter 反而过度设计。第三是否需要跟随 Spring 生命周期。比如要在应用启动后执行回调、要监听容器事件、要感知配置刷新这种强耦合 Spring 容器的场景必须用 Starter 的自动配置方式。我踩过的坑是早期把公司一个加密工具类也做成了 Starter结果自动配置类加了各种条件注解最后发现根本没有 Bean 需要注入纯属给自己加戏。后来那个 Starter 就被降级成普通工具包了。1.3 命名规范官方约定和自定义前缀命名这东西看着不起眼但我见过太多人在这上面吃亏。官方 Starter 的命名格式是spring-boot-starter-{模块名}比如spring-boot-starter-web。自定义 Starter 官方推荐用{模块名}-spring-boot-starter比如myapp-redis-spring-boot-starter。这么设计是有讲究的你自己的模块名放前面别人一看就知道这个 Starter 是干什么的后半段统一用spring-boot-starter结尾Maven 中央仓库和 IDE 插件才能识别出这是 Spring Boot 生态的组件。但是要注意如果你的项目引了官方 Starter 又自定义了同名前缀的类很容易出现 Bean 冲突。我建议自定义类的前缀用公司缩写或模块缩写比如com.company.xxx.autoconfigure避免和官方命名空间撞车。另外一个细节Starter 本身通常是个空 jar只负责引入依赖真正干活的是 auto-configuration 模块。所以实际项目里经常拆成两个模块xxx-spring-boot-starter依赖聚合和xxx-spring-boot-autoconfigure自动配置逻辑。小项目可以合并成一个但模块多了以后拆开是正解不然用户只想用你的一小部分功能还得引入全部依赖。2. 自定义 Starter 的核心实现从依赖到自动配置类2.1 工程结构怎么摆我这边以 Maven 项目为例标准的 Starter 工程结构长这样my-starter-demo/ ├── pom.xml └── src/ └── main/ ├── java/ │ └── com/example/demo/ │ ├── DemoProperties.java │ ├── DemoService.java │ └── DemoAutoConfiguration.java └── resources/ └── META-INF/ └── spring.factories如果你用的是 Spring Boot 2.7 及以上版本resources/META-INF/下还可以放一个org.springframework.boot.autoconfigure.AutoConfiguration.imports文件来替代spring.factories这个后面细说。但老项目或者要兼容老版本spring.factories仍然要保留。2.2 引入最小的依赖自定义 Starter 不需要引spring-boot-starter-web这种重量级依赖因为它本身不处理 Web 请求。核心依赖其实就两个dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-autoconfigure/artifactId version2.7.18/version scopeprovided/scope /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-configuration-processor/artifactId version2.7.18/version optionaltrue/optional /dependency注意spring-boot-autoconfigure的 scope 我用了provided因为用户的工程里必然会引入 Spring Boot这个 jar 只是编译期需要。spring-boot-configuration-processor是配置元数据处理器它会扫描ConfigurationProperties注解的类在编译时生成spring-configuration-metadata.json这样用户在 IDE 里写配置时会有自动提示。这个依赖一定要设为optional避免传递到用户的工程里。2.3 配置属性类让用户用得爽的第一道关卡写配置属性类是最见功力的地方。好的属性设计能让你少写很多文档差的设计能让用户骂娘。一个规范的配置属性类长这样ConfigurationProperties(prefix demo) public class DemoProperties { /** * 是否开启 demo 功能默认开启 */ private boolean enabled true; /** * 服务地址必填项 */ private String url; /** * 超时时间单位毫秒默认 3000 */ private long timeout 3000L; /** * 重试次数默认 3 */ private int retryCount 3; // getter 和 setter 省略 }关键点有三个第一个prefix 一定要短且唯一。demo前缀用户写配置就是demo.urlxxx。我之前见过有人用com.example.myproject.config这种前缀写配置的时候能把人逼疯。第二个所有属性都必须有默认值。这一点极其重要。默认值能让 Starter 在用户不配置任何东西的情况下也运行得起来至少能启动不报错。即使某个属性是必填项也别直接null了之可以在自动配置类里做校验抛出一个明确的异常提示“demo.url is required”。第三个用 Javadoc 注释写清楚每个字段的含义和单位。这个注释不是给代码看的是给客户看的功能说明。配合spring-boot-configuration-processor用户的 IDE 里就能看到这些注释渲染出来的文档说明。2.4 服务类业务逻辑和 Spring 解耦属性配置类负责接收配置服务类负责真正干活。服务类的设计有个分寸要拿捏既要不依赖 Spring 的 API又要能优雅地融入 Spring 容器。比如你要封装一个发送消息的服务可以这样设计public class DemoService { private final DemoProperties properties; public DemoService(DemoProperties properties) { this.properties properties; } public String ping(String input) { // 这里实际发起调用用 properties 里的 url、timeout 等配置 return pong: input , timeout properties.getTimeout(); } }注意这个类没有任何 Spring 注解它就是一个纯 POJO。好处是单元测试特别方便new DemoService(props)就能测。真正把它交给 Spring 的是后面的自动配置类。这样职责清晰DemoProperties管配置、DemoService管业务、DemoAutoConfiguration管装配。2.5 自动配置类整个 Starter 的心脏自动配置类是决定 Starter 能不能在 Spring Boot 里正常工作的地方。最基础的写法如下Configuration ConditionalOnClass(DemoService.class) EnableConfigurationProperties(DemoProperties.class) public class DemoAutoConfiguration { Bean ConditionalOnMissingBean public DemoService demoService(DemoProperties properties) { return new DemoService(properties); } }这个类上有三个注解每一个都有讲究。Configuration让 Spring 把它当作配置类处理这是最基本的。重点在下面两个。ConditionalOnClass(DemoService.class)是一个条件注解它的意思是classpath 里存在 DemoService 这个类时才加载这个配置类。这是 Spring Boot 自动配置的精髓——把判断交给 classpath而不是交给配置文件。用户引了你的 Starter类就在没引类就不在配置类自然不会被加载。这种机制保证 Starter 是“即插即用”的不需要用户在application.yml里写开关。EnableConfigurationProperties(DemoProperties.class)把配置属性类注册为 Spring 管理的 Bean并且自动完成application.yml里demo.*配置项到DemoProperties对象字段的绑定。这里有个细节有人会问为什么不用Component直接标注在DemoProperties上让它被扫描到。答案是不推荐因为你的 Starter 是引到用户工程里的组件扫描扫不到第三方 jar 包里的类即使扫描到了也无法保证配置绑定的时机。ConditionalOnMissingBean加在demoServiceBean 方法上意思是如果用户已经自己定义了一个DemoService类型的 Bean那就不再创建。这么做是给用户留了后门让他们可以完全覆盖你提供的默认实现。2.6 老版本和新版本的注册方式差异这里专门说一下自动配置类的注册方式因为版本差异太大我见过不少人在升级 Spring Boot 后 Starter 突然失效排查半天才发现是注册方式变了。Spring Boot 2.7 之前自动配置类的注册是在resources/META-INF/spring.factories文件里完成的org.springframework.boot.autoconfigure.EnableAutoConfiguration\ com.example.demo.DemoAutoConfigurationSpring Boot 2.7 之后官方推荐改用META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件内容更简洁com.example.demo.DemoAutoConfiguration到了 Spring Boot 3.xspring.factories方式被移除了必须用 imports 文件。所以如果你要做一个要长期维护的 Starter我建议在兼容的版本里两个文件都放。2.7 以下的用spring.factories2.7 及以上用 imports 文件两边都声明同一个自动配置类。还有一个版本相关的坑Spring Boot 2.7 引入了AutoConfiguration注解它其实是个组合注解等于Configuration(proxyBeanMethods false)加上自动配置的语义。如果用了这个注解自动配置类还可以实现AutoConfiguration.imports的排序接口控制多个自动配置类的加载顺序。这里不展开大家知道有这个东西就行。3. 一行一行写代码一个可运行的日志记录 Starter 手工实践3.1 需求场景定义前面全是理论现在来点实实在在的。我以一个“操作日志自动记录 Starter”为例完整走一遍开发流程。需求是这样的公司内部多个服务都希望把用户的关键操作登录、下单、修改密码等自动记录到日志表或者发送到消息队列。以前每个服务各自的实现方式都不一样有的用 AOP 切面有的在业务代码里手动打点。现在统一做一个 starter业务方引入依赖后只要在方法上加一个注解就能自动记录操作日志。这个场景很典型有注解、有 AOP 切面、有配置项、有自动装配几乎覆盖了 Starter 开发的全部要点。3.2 第一步定义注解和属性类先定义注解这是给用户使用的入口package com.example.operationlog.annotation; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) public interface OperationLog { /** * 操作类型比如 login、order、update */ String type(); /** * 操作描述比如“用户登录”“创建订单” */ String desc() default ; }再定义配置属性类package com.example.operationlog.config; import org.springframework.boot.context.properties.ConfigurationProperties; ConfigurationProperties(prefix operation.log) public class OperationLogProperties { /** * 是否启用操作日志功能默认启用 */ private boolean enabled true; /** * 日志存储方式console 输出、db 存储、mq 发送默认 console */ private String storeType console; public boolean isEnabled() { return enabled; } public void setEnabled(boolean enabled) { this.enabled enabled; } public String getStoreType() { return storeType; } public void setStoreType(String storeType) { this.storeType storeType; } }属性类里的enabled是给用户留的“全局开关”storeType是给用户留的“存储策略选择”。这种设计能让一个组件适应不同环境比如测试环境用 console 输出生产环境用 db 存储。3.3 第二步编写日志记录服务接下来是核心服务类。这里我设计成两种角色一个OperationLogService接口负责定义日志发送的契约一个默认实现负责把日志打到控制台。package com.example.operationlog.service; public interface OperationLogService { void record(String operator, String type, String desc, String result); }package com.example.operationlog.service.impl; import com.example.operationlog.service.OperationLogService; import org.slf4j.Logger; import org.slf4j.LoggerFactory; public class DefaultOperationLogService implements OperationLogService { private static final Logger log LoggerFactory.getLogger(DefaultOperationLogService.class); Override public void record(String operator, String type, String desc, String result) { log.info(操作日志 | 操作人: {} | 类型: {} | 描述: {} | 结果: {}, operator, type, desc, result); } }为什么要把服务定义成接口因为不同的storeType对应不同的实现用户可能想用自己的日志存储系统。用接口 条件装配的组合用户自定义一个OperationLogServiceBean 就可以完全覆盖默认实现。3.4 第三步AOP 切面实现自动记录有了注解和服务还需要一个切面把两者串联起来。AOP 切面本身也是一个普通的类但它必须由 Spring 管理并且需要引入spring-boot-starter-aop依赖package com.example.operationlog.aspect; import com.example.operationlog.annotation.OperationLog; import com.example.operationlog.service.OperationLogService; import org.aspectj.lang.ProceedingJoinPoint; import org.aspectj.lang.annotation.Around; import org.aspectj.lang.annotation.Aspect; import org.aspectj.lang.reflect.MethodSignature; import org.springframework.beans.factory.annotation.Autowired; Aspect public class OperationLogAspect { Autowired private OperationLogService operationLogService; Around(annotation(operationLog)) public Object around(ProceedingJoinPoint joinPoint, OperationLog operationLog) throws Throwable { long startTime System.currentTimeMillis(); String result success; try { return joinPoint.proceed(); } catch (Throwable throwable) { result error: throwable.getMessage(); throw throwable; } finally { long cost System.currentTimeMillis() - startTime; String operator resolveOperator(); String desc operationLog.desc(); if (desc.isEmpty()) { desc operationLog.type(); } operationLogService.record(operator, operationLog.type(), desc, result , cost cost ms); } } private String resolveOperator() { // 实际场景里可以从 SecurityContext、ThreadLocal、Header 里获取当前登录用户 return unknown; } }这个切面有几个值得说的细节。Around(annotation(operationLog))这种写法是直接把注解对象作为参数传入通知方法这样在方法体内可以直接拿到注解上的type()和desc()属性。比用反射再去getAnnotation要干净许多。finally块里做日志记录保证了无论方法成功还是抛异常都会记录。同时把异常继续抛出去不吞掉业务异常这一点很重要。有些初学者容易在切面里把异常 catch 了就不管了导致业务方完全感知不到失败。resolveOperator()返回的是操作人实际场景里基本都是从安全上下文里取。我这里没有引入具体的 Spring Security 依赖只是给你留了个扩展点的大致框架。3.5 第四步编写自动配置类并串联所有组件现在把前面的组件全部装配到一起package com.example.operationlog.config; import com.example.operationlog.aspect.OperationLogAspect; import com.example.operationlog.service.OperationLogService; import com.example.operationlog.service.impl.DefaultOperationLogService; import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration EnableConfigurationProperties(OperationLogProperties.class) ConditionalOnProperty(prefix operation.log, name enabled, havingValue true, matchIfMissing true) public class OperationLogAutoConfiguration { Bean ConditionalOnMissingBean public OperationLogService operationLogService() { return new DefaultOperationLogService(); } Bean ConditionalOnMissingBean public OperationLogAspect operationLogAspect(OperationLogService operationLogService) { return new OperationLogAspect(); } }注意两个条件注解的配合。ConditionalOnProperty加在配置类上判断operation.log.enabled配置项。matchIfMissing true意味着当用户没配置这个属性时默认匹配成功整个 Starter 默认生效。如果用户想关闭只要在配置文件里写operation.log.enabledfalse就行。ConditionalOnMissingBean分别加在服务和切面的 Bean 上。用户如果只自定义了OperationLogService那切面还是会自动装配而且注入的是用户的实现。用户如果连切面也想自己控制也可以自己定义。3.6 第五步注册自动配置类最后一步是把自动配置类告诉 Spring Boot。我同时准备了两种方式方便你在不同版本下切换。在src/main/resources/META-INF/spring.factories里写org.springframework.boot.autoconfigure.EnableAutoConfiguration\ com.example.operationlog.config.OperationLogAutoConfiguration在src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports里写com.example.operationlog.config.OperationLogAutoConfiguration这里有个特别容易踩的坑文件路径必须完全正确比如AutoConfiguration.imports文件名是固定的org.springframework.boot.autoconfigure.AutoConfiguration.imports少一个字符都加载不到。而且这个文件必须在META-INF/spring/目录下不是META-INF/下。我第一次写的时候就把文件放错位置结果 Spring Boot 静默忽略项目不报错但 Starter 就是不生效排查了很久。3.7 构建和本地验证写完之后用 Maven 打包mvn clean install然后新建一个测试工程引入这个 Starterdependency groupIdcom.example/groupId artifactIdoperation-log-spring-boot-starter/artifactId version1.0.0/version /dependency测试工程里写一个简单接口RestController public class TestController { OperationLog(type login, desc 用户登录) GetMapping(/login) public String login(RequestParam String username) { return welcome username; } }启动测试工程访问/login?usernamezhangsan控制台输出INFO 12345 --- [nio-8080-exec-1] c.e.o.service.impl.DefaultOperationLogService : 操作日志 | 操作人: unknown | 类型: login | 描述: 用户登录 | 结果: success, cost2ms到这里一个真正可用的 Starter 就算完工了。业务方引入依赖在方法上加一个注解日志记录就自动生效了。4. 项目里实战常用的进阶技巧条件装配与自动配置排序4.1 条件注解全家桶让 Starter 更聪明前面代码里已经用了ConditionalOnClass、ConditionalOnMissingBean、ConditionalOnProperty但 Spring Boot 的条件注解远不止这几个。我把项目中真正用得上的整理一下。ConditionalOnBean和ConditionalOnMissingBean是互补的。一个判断容器中已有某个 Bean 时生效一个判断没有时生效。这里有一个极大的坑这两个注解的判断时机。如果放在配置类上它是在配置类解析阶段判断的此时很多 Bean 还没注册如果放在Bean方法上它是在方法执行阶段判断的时机要晚一些。所以大多数情况下ConditionalOnMissingBean应该放在Bean方法上而不是配置类上。ConditionalOnExpression可以写 SpEL 表达式。我见过一个场景某个功能开关要同时看两个配置项比如demo.enabledtrue且demo.modefull才生效这时用ConditionalOnExpression(${demo.enabled:true} ${demo.mode:full} full)就能搞定。但要注意 SpEL 表达式里字符串比较的写法少了引号就会报错。ConditionalOnWebApplication和ConditionalOnNotWebApplication是判断应用类型的。比如某个 Starter 只服务于 Web 项目可以加这个注解非 Web 项目里直接跳过省得浪费加载时间。这几个注解组合起来可以让同一个 Starter 在不同场景下表现不同行为。比如我做过一个消息推送 StarterWeb 环境下它自动注册 HTTP 接口用于推送回调非 Web 环境下不注册接口只提供服务实现。一个 jar 包解决了两种项目的需求。4.2 自动配置类的加载顺序控制多个 Starter 之间可能存在依赖关系。比如你写了一个common-spring-boot-starter里面定义了公司统一的RestTemplate配置又写了一个order-spring-boot-starter内部依赖RestTemplate。这时就必须保证common的自动配置先执行否则order的自动配置在装配RestTemplate时可能还没创建。Spring Boot 提供了三个控制顺序的注解AutoConfigureBefore表明当前自动配置在指定的自动配置之前执行。AutoConfigureAfter表明当前自动配置在指定的自动配置之后执行。AutoConfigureOrder用 Order 值排序值越小越先执行。举个例子Configuration AutoConfigureAfter(CommonAutoConfiguration.class) public class OrderAutoConfiguration { // ... }这段代码的含义是OrderAutoConfiguration必须在CommonAutoConfiguration之后加载。这样OrderAutoConfiguration里注入RestTemplate时容器里已经存在了。值得提醒的是顺序注解只在自动配置类之间生效对用户自己Configuration定义的配置类不生效。因为自动配置类的加载时机是在用户的配置类之后顺序只影响自动配置类之间的相对顺序。4.3 与 Spring Boot 3.x、微服务框架的兼容问题Spring Boot 3.x 的变化不仅仅是注册方式还有一个重要升级基于 Java 17 Jakarta EE 9。如果说你的 starter 内部用到了一些旧的javax.*包比如javax.annotation.PostConstruct在 Boot 3.x 里会直接编译失败必须换成jakarta.annotation.PostConstruct。另外如果你所在的团队用的是 Spring Cloud自定义 Starter 可能会和配置中心、注册中心产生联动。我的建议是先不要让你的 Starter 直接依赖 Spring Cloud 的 API除非万不得已。因为 Spring Cloud 版本升级频繁牵一发动全身。更好的方式是定义一个抽象的ConfigurationProvider接口让用户的配置从本地application.yml读取还是从配置中心读取由用户自己去适配。我踩过的一个真实的坑是早期做了一个读写分页的 Starter直接在代码里用了 Nacos 的NacosValue注解实现配置动态刷新。后来公司统一升级 Spring Cloud 版本Nacos 客户端 API 变化我的 Starter 也得跟着改所有接入方都得升级依赖。如果当时设计成暴漏一个接口让用户自己实现配置刷新就没这档子事了。5. 常见问题排查自定义 Starter 不生效的现场实录5.1 自动配置类根本没被加载这是最多人遇到的问题。现象是引用之后启动自定义的 Bean 完全不存在Autowired直接报错。排查思路分三步走第一步确认自动配置类有没有被注册。Spring Boot 启动时加--debug参数控制台会输出Auto-configuration report里面会列出所有匹配成功、匹配失败、排除的自动配置类。如果你的 Starter 的自动配置类连名字都没出现说明压根没注册如果出现在“匹配失败”里说明条件注解的判断没通过。第二步检查注册文件路径和内容。spring.factories的 key 必须是org.springframework.boot.autoconfigure.EnableAutoConfiguration不是org.springframework.context.annotation.ConfigurationAutoConfiguration.imports文件必须放在META-INF/spring/下不是META-INF/下。这两个是静态资源路径问题写错就是静默失败没有任何报错。第三步看看有没有被排除。如果你在启动类上用了SpringBootApplication(exclude XXXAutoConfiguration.class)或者配置文件里配了spring.autoconfigure.exclude...那也会导致不生效。这属于显式排除一般不会忘了但排查的时候也顺带看一眼。5.2 配置属性绑定不生效用户配置了demo.urlxxx但DemoProperties里拿到的还是 null。最常见的原因是ConfigurationProperties的类没有被EnableConfigurationProperties注册也没有被Component标注。如果只是单纯加了一个ConfigurationProperties注解Spring 容器并不知道要创建这个 Bean配置绑定自然无从谈起。另一个原因是 IDE 缓存。spring-boot-configuration-processor生成的配置元数据有时候不会立即刷新导致配置提示和绑定看起来没生效。这时候可以先mvn clean把target目录清掉再重新编译。还有一个易忽略的点getter 和 setter 必须要有。Spring Boot 的配置绑定底层用的是 JavaBean 属性访问器不是字段反射。只写了字段没写 getter/setter绑定会失败。Lombok 的Data可以处理这个但前提是编译期正常生成了方法。5.3 Bean 重复定义或覆盖问题如果你的 Starter 定义了DemoServiceBean用户也定义了一个DemoServiceBean默认情况下 Spring Boot 会以用户的为准吗不一定。Spring Boot 自动配置类里有ConditionalOnMissingBean注解时才会主动避开用户已有的 Bean。如果没有这个注解两个 Bean 同名或者同类型冲突启动阶段会直接报BeanDefinitionOverrideException或者NoUniqueBeanDefinitionException。所以规范的写法是自动配置类里所有对外暴露的 Bean都要加上ConditionalOnMissingBean。这不是可选项是必选项。这样可以保证用户有权利覆盖 Starter 的默认行为。如果确实希望 Starter 的 Bean 覆盖用户的 Bean可以在配置文件里设置spring.main.allow-bean-definition-overridingtrue但我强烈不建议这么做。全局覆盖开关很危险一个服务里几十个依赖你不知道哪个依赖的 Bean 会被悄悄覆盖。5.4 常见问题速查表我把实际工作中积累的问题现象和排查方向整理成了表格方便你遇到问题时快速定位。问题现象可能原因排查/解决方案Starter 引入后没有任何效果自动配置类未注册检查spring.factorieskey 名、检查 imports 文件路径、用--debug看自动配置报告配置项写了一大堆但值全是 null属性类未注册/未绑定确认EnableConfigurationProperties或ConfigurationProperties正确标注检查是否有 getter/setter项目启动报 Bean 重复缺少ConditionalOnMissingBean自动配置类中的Bean方法统一补上该条件注解用户自定义的 Bean 被覆盖全局允许覆盖检查spring.main.allow-bean-definition-overriding是否被打开升级 Spring Boot 3.x 后失效注册方式变化或 javax API 未替换改用 AutoConfiguration.imports检查 javax 到 jakarta 的迁移配置属性在 IDE 里没有提示缺少配置处理器依赖引入spring-boot-configuration-processor重新编译刷新元数据切面不生效缺少 AOP 依赖或切面类未被注册确认引入了spring-boot-starter-aop切面类是否在自动配置类中被声明为 Bean多个 Starter 之间有依赖关系的 Bean 缺失自动配置加载顺序不对使用AutoConfigureAfter/AutoConfigureBefore/AutoConfigureOrder5.5 调试技巧如何快速定位 Starter 的问题我调试自定义 Starter 时最有用的三招分享给你。第一招是启动时加--debug看自动配置报告。这个前面提过再强调一次因为真的大部分定位都靠它。报告里会显示每个自动配置类匹配的条件注解和匹配结果一眼就能看出你的 Starter 是哪一步没通过。第二招是打断点。自动配置类也是普通的Configuration类可以在类上打条件注解的断点或者在Bean方法打断点。Spring 容器刷新时会直接走到这里你就能实时看到ConditionEvaluator的判断过程。第三招是写一个针对自动配置类的测试。用ApplicationContextRunner这个工具类它专门用于测试自动配置Test void testAutoConfiguration() { new ApplicationContextRunner() .withConfiguration(AutoConfigurations.of(OperationLogAutoConfiguration.class)) .withPropertyValues(operation.log.enabledtrue) .run(context - { assertThat(context).hasSingleBean(OperationLogService.class); assertThat(context).hasSingleBean(OperationLogAspect.class); }); }这个测试不需要启动完整的 Spring Boot 应用跑的极快非常适合在本地验证修改后的自动配置行为。我在开发 Starter 时都会搭一套这种测试每次改完代码跑一遍比手动起一个 demo 工程验证快太多了。6. 从能用到优雅我在实际项目中的最后一公里经验前面讲完了技术实现最后聊一点偏工程实践的东西。我经过几个真实项目的打磨现在写自定义 Starter 之前一定会先做一件事画一个“什么该放 Starter什么不该放”的边界图。Starter 的职责是“把重复的初始化过程自动化”而不是“把所有公共代码都塞进去”。工具类、常量类、纯粹的 DTO 对象这些不该进 Starter连接池管理、客户端构建、切面逻辑、生命周期管理这些才是 Starter 的主场。另一个感悟是文档和示例工程不能省。代码写得再飘逸接入方看不懂一样白搭。我给每个 Starter 都配一个独立的demo模块里面是最小的可运行示例。接入方照着 demo 抄五分钟就能跑通。配置项说明我直接用spring-boot-configuration-processor的元数据注释写在字段上用户 IDE 里鼠标悬停就能看到。最后再分享一个小技巧给 Starter 预留一个enabled开关。即使默认是开启的也一定要留一个全局总开关。因为生产环境出问题的时候甲方要求“立刻下线某个功能”如果没有这个开关你只能重新打包发版有了开关运维改一行配置重启就能搞定。这种细节关键时刻能救你一命。写自定义 Starter 这件事技术上并不难难的是理解它背后“约定大于配置”的设计哲学。当你真正理解了 Spring Boot 是怎么发现你写的自动配置类的你对整个框架的理解都会上一个台阶。希望这份经验能帮你少走点弯路。