手把手实现一个 Spring Boot Starter：把第三方类自动装入 IOC 容器

在日常开发中，我们经常会引入各种第三方 SDK（OSS、MinIO、短信、支付等）。如果每次都在业务项目里手动 new 对象、手动注入配置，既繁琐又不优雅。Spring Boot 给出的标准解法就是 Starter + AutoConfiguration。

本文以一个极简示例 aliyun-oss-spring-boot-autoconfigure 为例，拆解"如何让一个第三方类被自动注册进 IOC 容器"。

一、整体架构

一个标准的 Starter 通常由两个 Maven 模块组成：

aliyun-oss-spring-boot-starter          (空壳，只做依赖聚合，给用户引入)
        └── aliyun-oss-spring-boot-autoconfigure  (核心：自动配置逻辑)

• starter 模块：本质上是一个"门面"，本身不含代码，只依赖 autoconfigure 模块。业务方只需引入这一个依赖即可。
• autoconfigure 模块：真正干活的地方，包含配置类、Properties、以及自动配置注册文件。

本例中 starter 的 pom.xml 只做了一件事——把 autoconfigure 拉进来：

<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-oss-spring-boot-autoconfigure</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

二、核心三件套

autoconfigure 模块里有三个关键角色，缺一不可：

1. Properties —— 配置绑定

@ConfigurationProperties(prefix = "aliyun.oss")
public class AliyunOSSProperties {
    private String endpoint;
    private String region;
    private String bucketName;
    // getter / setter / toString ...
}

通过 @ConfigurationProperties 把 application.yml 中以 aliyun.oss 为前缀的配置，自动绑定到这个 POJO 上。用户只要写：

aliyun:
  oss:
    endpoint: https://oss-cn-hangzhou.aliyuncs.com
    region: cn-hangzhou
    bucket-name: my-bucket

2. Operator —— 被托管的第三方类

public class AliyunOSSOperator {
    private AliyunOSSProperties aliyunOSSProperties;

    public AliyunOSSOperator(AliyunOSSProperties aliyunOSSProperties) {
        this.aliyunOSSProperties = aliyunOSSProperties;
    }

    public String upload() {
        return "upload success";
    }
}

这就是我们想"塞进 IOC 容器"的第三方类的替身。实际项目中，这里会持有 MinIO/OSS 的 Client 实例，并封装 upload、download 等方法。

3. AutoConfiguration —— 自动装配的核心

@EnableConfigurationProperties(AliyunOSSProperties.class) // 把 Properties 注册进 IOC
@Configuration
public class AliyunOSSAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public AliyunOSSOperator aliyunOSSOperator(AliyunOSSProperties aliyunOSSProperties) {
        return new AliyunOSSOperator(aliyunOSSProperties);
    }
}

这里有两个关键点：

• @EnableConfigurationProperties：让 AliyunOSSProperties 成为一个 Bean，供全局注入。
• @Bean + @ConditionalOnMissingBean：只有当容器里还没有 AliyunOSSOperator 类型的 Bean 时，才自动创建。这给了用户"覆盖默认实现"的能力——只要自己再定义一个同类型的 Bean，Starter 的就不会生效。

三、自动配置如何被发现？

光写配置类还不够，Spring Boot 怎么知道要加载它？答案是 自动配置注册文件：

resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

内容只有一行（全限定类名）：

com.aliyun.oss.AliyunOSSAutoConfiguration

注意：这是 Spring Boot 2.7+ 推荐的新机制，取代了旧版的 spring.factories。Spring Boot 3.x 已彻底移除 spring.factories 的自动配置支持，所以本例用的是 .imports 文件（这也与项目使用的 Boot 3.5.16 一致）。

四、装配流程

业务项目引入 starter 依赖
        │
        ▼
starter 传递依赖 autoconfigure 模块
        │
        ▼
Spring Boot 启动，扫描 META-INF/spring/
org.springframework.boot.autoconfigure.AutoConfiguration.imports
        │
        ▼
加载 AliyunOSSAutoConfiguration
        │
        ▼
@EnableConfigurationProperties
  → 将 AliyunOSSProperties 注册为 Bean
        │
        ▼
@Bean + @ConditionalOnMissingBean
  → 注册 AliyunOSSOperator（容器中无该类型时才创建）
        │
        ▼
业务代码直接 @Autowired 使用

如果你使用的阅读器支持 Mermaid（如部分博客平台、VS Code + Mermaid 插件），也可以用下方等价写法：

五、业务方怎么用？

引入 starter 后，业务代码里零配置即可使用：

@Service
public class FileService {
    @Autowired
    private AliyunOSSOperator aliyunOSSOperator;

    public void doUpload() {
        aliyunOSSOperator.upload();
    }
}

Operator 实例、Properties 配置全部由 Starter 自动注入，用户无需关心创建细节。

六、小结

一个最小可用的 Spring Boot Starter 只需要 4 样东西：

要素	作用
xxxProperties + @ConfigurationProperties	绑定外部配置
xxxOperator（第三方封装类）	真正被托管的核心对象
xxxAutoConfiguration + @Bean	把对象装进 IOC 容器
AutoConfiguration.imports	让 Spring Boot 在启动时"发现"它

掌握了这套模板，你就可以把任何第三方 SDK 封装成自己的 Starter，让团队以"加一个依赖"的成本完成集成。