从零手写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> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-autoconfigure</artifactId> <version>2.7.18</version> <scope>provided</scope> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-configuration-processor</artifactId> <version>2.7.18</version> <optional>true</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.url=xxx。我之前见过有人用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.DemoAutoConfiguration

Spring Boot 2.7 之后，官方推荐改用META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件，内容更简洁：

com.example.demo.DemoAutoConfiguration

到了 Spring Boot 3.x，spring.factories方式被移除了，必须用 imports 文件。

所以如果你要做一个要长期维护的 Starter，我建议在兼容的版本里两个文件都放。2.7 以下的用spring.factories，2.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.enabled=false就行。

@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

然后新建一个测试工程，引入这个 Starter：

<dependency> <groupId>com.example</groupId> <artifactId>operation-log-spring-boot-starter</artifactId> <version>1.0.0</version> </dependency>

测试工程里写一个简单接口：

@RestController public class TestController { @OperationLog(type = "login", desc = "用户登录") @GetMapping("/login") public String login(@RequestParam String username) { return "welcome " + username; } }

启动测试工程，访问/login?username=zhangsan，控制台输出：

INFO 12345 --- [nio-8080-exec-1] c.e.o.service.impl.DefaultOperationLogService : 操作日志 | 操作人: unknown | 类型: login | 描述: 用户登录 | 结果: success, cost=2ms

到这里，一个真正可用的 Starter 就算完工了。业务方引入依赖，在方法上加一个注解，日志记录就自动生效了。

4. 项目里实战常用的进阶技巧：条件装配与自动配置排序

4.1 条件注解全家桶：让 Starter 更聪明

前面代码里已经用了@ConditionalOnClass、@ConditionalOnMissingBean、@ConditionalOnProperty，但 Spring Boot 的条件注解远不止这几个。我把项目中真正用得上的整理一下。

@ConditionalOnBean和@ConditionalOnMissingBean是互补的。一个判断容器中已有某个 Bean 时生效，一个判断没有时生效。这里有一个极大的坑：这两个注解的判断时机。如果放在配置类上，它是在配置类解析阶段判断的，此时很多 Bean 还没注册；如果放在@Bean方法上，它是在方法执行阶段判断的，时机要晚一些。所以大多数情况下，@ConditionalOnMissingBean应该放在@Bean方法上，而不是配置类上。

@ConditionalOnExpression可以写 SpEL 表达式。我见过一个场景，某个功能开关要同时看两个配置项，比如demo.enabled=true且demo.mode=full才生效，这时用@ConditionalOnExpression("${demo.enabled:true} && '${demo.mode:full}' == 'full'")就能搞定。但要注意 SpEL 表达式里字符串比较的写法，少了引号就会报错。

@ConditionalOnWebApplication和@ConditionalOnNotWebApplication是判断应用类型的。比如某个 Starter 只服务于 Web 项目，可以加这个注解，非 Web 项目里直接跳过，省得浪费加载时间。

这几个注解组合起来，可以让同一个 Starter 在不同场景下表现不同行为。比如我做过一个消息推送 Starter，Web 环境下它自动注册 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.Configuration；AutoConfiguration.imports文件必须放在META-INF/spring/下，不是META-INF/下。这两个是静态资源路径问题，写错就是静默失败，没有任何报错。

第三步，看看有没有被排除。如果你在启动类上用了@SpringBootApplication(exclude = XXXAutoConfiguration.class)，或者配置文件里配了spring.autoconfigure.exclude=...，那也会导致不生效。这属于显式排除，一般不会忘了，但排查的时候也顺带看一眼。

5.2 配置属性绑定不生效

用户配置了demo.url=xxx，但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-overriding=true，但我强烈不建议这么做。全局覆盖开关很危险，一个服务里几十个依赖，你不知道哪个依赖的 Bean 会被悄悄覆盖。

5.4 常见问题速查表

我把实际工作中积累的问题现象和排查方向整理成了表格，方便你遇到问题时快速定位。

5.5 调试技巧：如何快速定位 Starter 的问题

我调试自定义 Starter 时，最有用的三招，分享给你。

第一招是启动时加--debug，看自动配置报告。这个前面提过，再强调一次，因为真的大部分定位都靠它。报告里会显示每个自动配置类匹配的条件注解和匹配结果，一眼就能看出你的 Starter 是哪一步没通过。

第二招是打断点。自动配置类也是普通的@Configuration类，可以在类上打条件注解的断点，或者在@Bean方法打断点。Spring 容器刷新时会直接走到这里，你就能实时看到ConditionEvaluator的判断过程。

第三招是写一个针对自动配置类的测试。用ApplicationContextRunner这个工具类，它专门用于测试自动配置：

@Test void testAutoConfiguration() { new ApplicationContextRunner() .withConfiguration(AutoConfigurations.of(OperationLogAutoConfiguration.class)) .withPropertyValues("operation.log.enabled=true") .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 是怎么发现你写的自动配置类的，你对整个框架的理解都会上一个台阶。希望这份经验能帮你少走点弯路。