如何开发一个 Spring Boot Starter：以定时任务 Starter 为例及常见踩坑点

在 Spring Boot 生态中，自定义 Starter 是一种常见的封装方式，能够简化模块化开发。本文基于一个定时任务 Starter 的示例代码，分析其实现流程，并重点讲解开发 Starter 时容易踩坑的地方，尤其是 SPI 机制 和配置封装的关键点。

一、SPI 机制与 Starter 封装流程

SPI（Service Provider Interface） 是 Java 的一种服务发现机制，Spring Boot 的自动配置正是基于此实现。开发 Starter 的核心流程如下：

定义功能组件：编写核心业务类（如定时任务）。
封装配置类 ：通过 @ConfigurationProperties 绑定外部配置。
自动配置类 ：使用 @Configuration 和 @Bean 注册组件。
SPI 注册 ：在 META-INF/spring.factories 中声明自动配置类路径。

二、代码结构解析

以下是示例 Starter 的代码结构及关键点：

1. 自动配置类

java 复制代码

@Configuration
@EnableScheduling
public class ScheduledStarterAutoConfiguration {
    @Bean
    public Message message() { return new Message(); }
    
    @Bean
    public TimeTask timeTask() { return new TimeTask(); }
}

关键点 ：@EnableScheduling 启用定时任务，@Bean 注册组件。

2. 配置属性类

java 复制代码

@ConfigurationProperties(prefix = "xyc.config")
public class Message {
    private String name;
    private String message;
    private String cron;
    // getters/setters...
}

作用：绑定 application.yml 中以 xyc.config 开头的配置。

3. 定时任务类

java 复制代码

public class TimeTask {
    @Autowired
    private Message message;
    
    @Scheduled(cron = "${xyc.config.cron}")
    public void notice() { 
        System.out.println(message.getName() + "说：" + message.getMessage()); 
    }
}

关键点 ：通过 @Scheduled 声明定时任务，cron 表达式从配置中读取。

4. SPI 注册文件

在 resources/META-INF/spring.factories 中声明：

properties 复制代码

org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.xiaoyongcai.io.scheduledstarter.Config.ScheduledStarterAutoConfiguration

三、易踩坑点详解

1. 自动配置类未生效

问题：spring.factories 文件路径错误或内容格式错误。
解决：
- 确保文件路径为 META-INF/spring.factories。
- 检查类全路径是否正确，避免拼写错误。
- 注意：Spring Boot 2.7+ 推荐使用 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports，但示例代码基于旧版本。

2. 配置属性未绑定

问题：@ConfigurationProperties 类未生效，配置无法注入。
解决：
- 在启动类添加 @EnableConfigurationProperties(Message.class)，或在自动配置类中显式注册 Message 为 Bean。
- 确保配置前缀与 application.yml 中的一致，例如：
  yaml 复制代码
```
xyc.config:
  name: "XiaoYong"
  message: "Hello World"
  cron: "0/5 * * * * ?"
```

3. 定时任务未触发

问题：TimeTask 未被 Spring 容器管理。
- 错误示例 ：在 TimeTask 类上遗漏 @Component，但未通过 @Bean 显式注册。
- 正确做法 ：示例代码通过 @Bean 注册 TimeTask，但需确保该类未被其他方式重复注册（如被组件扫描）。
问题：cron 表达式未正确读取。
- 解决：检查配置文件中 xyc.config.cron 是否存在，且值符合 cron 格式。

4. 包扫描路径冲突

问题：自动配置类的包路径未被主项目扫描到。
解决：确保 Starter 的包路径与主项目无重叠，或通过 @ComponentScan 显式指定扫描范围。

5. 依赖注入失败

问题：TimeTask 中 Message 依赖注入为 null。
- 原因：TimeTask 未通过 Spring 容器创建（如直接 new TimeTask()）。
- 解决：确保 TimeTask 通过 @Bean 或 @Component 由 Spring 管理。

6. Spring Boot 版本兼容性

问题：Spring Boot 2.7+ 弃用 spring.factories，改用 AutoConfiguration.imports。
解决：根据版本调整注册方式，或保持旧版本依赖。

四、正确实践建议

显式启用配置属性绑定：

java 复制代码

@Configuration
@EnableConfigurationProperties(Message.class)
public class ScheduledStarterAutoConfiguration { ... }

避免组件扫描冲突：
- 将 Starter 的包路径命名为唯一值（如 com.yourcompany.starter）。
测试属性加载：
- 在单元测试中验证 Message 的属性是否从配置文件正确加载。
版本适配：
- 明确 Starter 支持的 Spring Boot 版本，并在文档中注明。

补充：`spring.factories` 中不要注册启动类，而是注册配置类

在开发 Spring Boot Starter 时，spring.factories 文件的作用是告诉 Spring Boot 自动配置机制需要加载哪些配置类。这是一个非常关键的细节，但很容易被忽略或误解。

1. 问题描述

在 spring.factories 文件中，开发者可能会错误地将启动类（如 ScheduledStarterApplication）注册为自动配置类，例如：

properties 复制代码

org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.xiaoyongcai.io.scheduledstarter.ScheduledStarterApplication

这种做法是错误的，因为：

启动类通常包含 @SpringBootApplication 注解，它是一个组合注解，包含了 @Configuration、@EnableAutoConfiguration 和 @ComponentScan。
如果将启动类注册为自动配置类，可能会导致 Spring Boot 重复扫描组件，甚至引发 Bean 冲突或加载顺序问题。

2. 正确做法

在 spring.factories 中，应该注册的是 自动配置类 （即包含 @Configuration 注解的类），而不是启动类。例如：

properties 复制代码

org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.xiaoyongcai.io.scheduledstarter.Config.ScheduledStarterAutoConfiguration

这里的 ScheduledStarterAutoConfiguration 是一个配置类，负责定义和注册 Starter 的核心 Bean。

3. 为什么不能注册启动类？

启动类的职责 ：启动类的主要职责是启动 Spring Boot 应用，它通常包含 main 方法，并通过 SpringApplication.run 启动应用。
自动配置类的职责：自动配置类的职责是定义 Starter 的核心逻辑和 Bean 注册。它应该是一个独立的、专注于 Starter 功能的类。
潜在问题 ：
- 如果注册启动类，Spring Boot 会尝试将其作为配置类加载，可能导致组件扫描范围扩大，引入不必要的 Bean。
- 启动类通常包含 @ComponentScan，这会导致 Spring Boot 扫描整个包路径，可能与用户的应用程序冲突。

4. 示例代码

以下是正确的 spring.factories 文件内容：

properties 复制代码

org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.xiaoyongcai.io.scheduledstarter.Config.ScheduledStarterAutoConfiguration

对应的自动配置类：

java 复制代码

@Configuration
@EnableScheduling
public class ScheduledStarterAutoConfiguration {
    @Bean
    public Message message() { return new Message(); }
    
    @Bean
    public TimeTask timeTask() { return new TimeTask(); }
}

5. 总结

spring.factories 中注册的是自动配置类，而不是启动类。
自动配置类应该专注于 Starter 的核心功能，避免引入不必要的组件扫描或 Bean 注册。
启动类的职责是启动应用，不应该被当作配置类使用。

如何开发一个 Spring Boot Starter：以定时任务 Starter 为例及常见踩坑点