Spring Boot 中如何自定义一个 Starter

一、什么是 Spring Boot Starter

Spring Boot Starter 的作用是：

复制代码

封装自动配置
 +
封装常用依赖
 +
提供开箱即用的功能

很多常见组件其实都是 Starter，例如：

复制代码

spring-boot-starter-web
spring-boot-starter-data-redis
spring-boot-starter-security

Starter 的目标是：

复制代码

使用方只需要引入依赖
 +
在 application.yaml 写配置
 +
就可以直接 @Autowired 使用

二、自定义 Starter 的核心结构

核心就三步：

复制代码

属性类 → 自动配置类 → 注册文件

完整结构示例：

复制代码

my-spring-boot-starter/
├── pom.xml
└── src/main/java/com/example/mystarter/
│   ├── MyService.java
│   ├── MyStarterProperties.java
│   └── MyStarterAutoConfiguration.java
└── src/main/resources/
    └── META-INF/spring/
        └── org.springframework.boot.autoconfigure.AutoConfiguration.imports

三、第1步：属性类（绑定 application.yaml）

使用 @ConfigurationProperties 绑定配置。

java 复制代码

@ConfigurationProperties(prefix = "my.starter")
public class MyStarterProperties {

    private String name = "默认名字";
    private int timeout = 3000;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getTimeout() {
        return timeout;
    }

    public void setTimeout(int timeout) {
        this.timeout = timeout;
    }
}

对应的 application.yaml：

yaml 复制代码

my:
  starter:
    name: 小助
    timeout: 5000

Spring Boot 会自动把 YAML 配置映射到 MyStarterProperties。

四、第2步：提供服务类

这是 Starter 对外提供的核心功能。

java 复制代码

public class MyService {

    private final String name;
    private final int timeout;

    public MyService(String name, int timeout) {
        this.name = name;
        this.timeout = timeout;
    }

    public String sayHello() {
        return "你好，我是 " + name + "，超时时间 " + timeout + "ms";
    }
}

五、第3步：自动配置类

自动配置类负责在 Spring Boot 启动时创建 Bean。

java 复制代码

@AutoConfiguration
@EnableConfigurationProperties(MyStarterProperties.class)
public class MyStarterAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public MyService myService(MyStarterProperties properties) {
        return new MyService(
                properties.getName(),
                properties.getTimeout()
        );
    }
}

关键逻辑：

复制代码

读取配置
 ↓
创建 Bean
 ↓
注册到 Spring 容器

六、第4步：注册自动配置类

在目录：

复制代码

src/main/resources/META-INF/spring/

创建文件：

复制代码

org.springframework.boot.autoconfigure.AutoConfiguration.imports

内容：

复制代码

com.example.mystarter.MyStarterAutoConfiguration

这一步的作用是：

复制代码

告诉 Spring Boot
启动时加载你的自动配置类

七、Starter 的核心依赖

Starter 项目只需要两个核心依赖：

xml 复制代码

<dependencies>

 <!-- 自动配置核心注解 -->
 <dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-autoconfigure</artifactId>
  <version>${spring-boot.version}</version>
 </dependency>

 <!-- 生成配置元数据（IDE yaml 自动提示） -->
 <dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-configuration-processor</artifactId>
  <version>${spring-boot.version}</version>
  <optional>true</optional>
 </dependency>

</dependencies>

八、两个依赖的作用

依赖	作用	是否必须
spring-boot-autoconfigure	提供 `@AutoConfiguration`、`@ConditionalOnMissingBean`、`@EnableConfigurationProperties` 等注解	必须
spring-boot-configuration-processor	生成 `spring-configuration-metadata.json`，让 IDE 提示 yaml 配置	可选但建议

九、optional 的作用

xml 复制代码

<optional>true</optional>

含义：

复制代码

只在编译 Starter 时使用
不会传递给使用方

运行时不需要该依赖。

十、Starter 依赖其他组件

如果 Starter 内部需要 Redis：

xml 复制代码

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

当用户引入你的 Starter 时：

复制代码

Redis 依赖会自动传递

用户不需要再单独引入。

十一、Starter 项目 vs Spring Boot 应用

类型	Starter 项目	Spring Boot 应用
父工程	不需要	需要
主类	没有 main()	有 @SpringBootApplication
打包	普通 jar	可执行 fat jar
是否可运行	不能	能
本质	被依赖的库	独立应用

十二、Starter 开发流程

复制代码

1 创建普通 Maven 项目
2 编写属性类（ConfigurationProperties）
3 编写自动配置类（AutoConfiguration）
4 创建 AutoConfiguration.imports 注册文件
5 mvn install
6 Spring Boot 项目引入依赖
7 直接 @Autowired 使用

总结

Spring Boot Starter 的核心就是：

复制代码

@ConfigurationProperties
 +
AutoConfiguration
 +
AutoConfiguration.imports

完成这三步，就可以实现一个完整的 Spring Boot Starter。

Starter 项目完整 pom.xml 示例

Starter 项目本质是一个普通 Maven 项目，只需要少量依赖即可。

完整示例：

xml 复制代码

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
 https://maven.apache.org/xsd/maven-4.0.0.xsd">

 <modelVersion>4.0.0</modelVersion>

 <groupId>com.example</groupId>
 <artifactId>my-spring-boot-starter</artifactId>
 <version>1.0.0</version>

 <properties>
  <java.version>17</java.version>
  <spring-boot.version>3.5.7</spring-boot.version>
 </properties>

 <dependencies>

  <!-- 核心：自动配置相关注解（@AutoConfiguration、@ConditionalOnXxx 等） -->
  <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-autoconfigure</artifactId>
   <version>${spring-boot.version}</version>
  </dependency>

  <!-- 核心：让 @ConfigurationProperties 编译时生成元数据（IDE 提示 yaml 属性） -->
  <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-configuration-processor</artifactId>
   <version>${spring-boot.version}</version>
   <optional>true</optional>
  </dependency>

 </dependencies>

</project>

说明：

复制代码

spring-boot-autoconfigure
提供自动配置相关注解

spring-boot-configuration-processor
生成 spring-configuration-metadata.json
让 IDE 在 application.yaml 中有自动提示

configuration-processor 使用：

复制代码

<optional>true</optional>

含义是：

复制代码

只在编译 Starter 时使用
不会传递给使用方项目

因此 Starter 运行时并不依赖该组件。