必须使用meta-inf/spring/org.springframework.boot.autoconfigure.autoconfiguration.imports文件声明配置类,而非已废弃的spring.factories;需分starter(纯依赖)与autoconfigure(含自动装配逻辑)两模块,严格按路径、命名、条件注解规范实现。

要在Spring Boot 2.7版本中正确开发一个可复用、可传递、能被自动加载的自定义Starter,必须绕过已被废弃的spring.factories机制,严格使用META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件声明配置类,否则项目启动时根本不会扫描你的自动配置。
创建 starter 模块与 autoconfigure 模块
先建两个独立 Maven 模块:一个叫 mylog-spring-boot-starter(纯依赖管理,不写 Java 代码),另一个叫 mylog-spring-boot-autoconfigure(含全部自动装配逻辑)。
starter 模块的 pom.xml 只保留 <packaging>jar</packaging> 和对 autoconfigure 模块的依赖,其他所有插件、测试依赖、<build></build> 块全删掉——多留一行就可能污染使用者的 classpath。
autoconfigure 模块的 pom.xml 必须显式引入:spring-boot-autoconfigure(核心)、spring-boot-configuration-processor(可选但强烈建议,用于生成 spring-configuration-metadata.json)、以及你封装功能所依赖的三方库(如 slf4j-api 或 aspectjweaver)。
编写配置属性类并绑定前缀
在 autoconfigure 模块中新建 com.example.mylog.config.MyLogProperties 类:
添加 @ConfigurationProperties(prefix = "mylog") 注解,并声明 enabled、level 等字段;字段必须有 getter/setter,且类型要明确(不能用 Object)。
【prefix 值必须小写字母+短横线,不能含下划线或大写字母】 否则 application.yml 中写 myLog.enabled: true 将完全不生效——Spring Boot 配置绑定器对大小写和符号极其敏感。
别忘了在 @ConfigurationProperties 类上加 @Getter @Setter(Lombok)或手写方法,否则 Spring 无法反射赋值。
实现业务功能类与自动配置类
方法一:最简路径(推荐新手)
在 autoconfigure 模块中新建 com.example.mylog.service.MyLogService,提供日志记录方法;再建 com.example.mylog.config.MyLogAutoConfiguration,用 @Configuration + @EnableConfigurationProperties(MyLogProperties.class) + @Bean 注册服务实例。
方法二:条件化装配(生产级必需)
给 @Bean 方法加上 @ConditionalOnProperty(name = "mylog.enabled", havingValue = "true"),确保用户没配 mylog.enabled=true 时,整个 Bean 不注册;再加 @ConditionalOnClass(Aspect.class) 控制 AOP 功能只在有 AspectJ 时才加载。
这一步漏掉任一条件注解,就会导致 Starter 在无相关依赖的项目里启动失败或产生冲突 Bean。
注册自动配置类到 Spring Boot 加载链
第一步:在 autoconfigure 模块的 src/main/resources/META-INF/spring/ 目录下,手动创建完整路径,不能少一级。
第二步:新建文件 org.springframework.boot.autoconfigure.AutoConfiguration.imports(注意是纯文本文件,无扩展名)。
第三步:在该文件中,**每行写一个自动配置类的全限定名**,例如:com.example.mylog.config.MyLogAutoConfiguration
【文件名拼写错误、路径错位、类名大小写不对、多空格或 BOM 头,都会导致自动配置彻底静默失效】 这是 Spring Boot 2.7+ 最常见也最难排查的故障点。
打包发布与引用验证
① 进入 autoconfigure 模块根目录,执行 mvn clean install -Dmaven.test.skip=true,确保本地仓库生成了 mylog-spring-boot-autoconfigure-1.0.0.jar。
② 进入 starter 模块根目录,同样执行 mvn clean install,生成 mylog-spring-boot-starter-1.0.0.jar。
③ 在新 Spring Boot 2.7 项目中,pom.xml 添加依赖:
<dependency><br> <groupid>com.example</groupid><br> <artifactid>mylog-spring-boot-starter</artifactid><br> <version>1.0.0</version><br></dependency>
④ 在 application.yml 中添加:
mylog:<br> enabled: true<br> level: DEBUG
⑤ 启动应用,观察控制台是否输出 “MyLogAutoConfiguration loaded” 类似日志——有即成功,无则回溯检查 AutoConfiguration.imports 文件路径和内容。











