Spring Boot 3.x 如何自定义 Starter

最新推荐文章于 2025-10-31 09:08:56 发布

原创最新推荐文章于 2025-10-31 09:08:56 发布 · 1.3k 阅读

27 ·

CC 4.0 BY-SA版权

文章标签：

#spring boot #后端 #java #spring

java 同时被 3 个专栏收录

69 篇文章

订阅专栏

spring

52 篇文章

订阅专栏

spring boot

26 篇文章

订阅专栏

Spring Boot 3.x 自定义 Starter 的完整实现指南，快速构建一个兼容 Spring Boot 3.x 的 Starter 模块。

🧠 一、Spring Boot 3.x Starter 核心机制

✅ 1. Starter 的结构

一个典型的 Starter 模块包含以下部分：

部分	说明
AutoConfiguration	定义自动配置逻辑（如 `@Bean` 方法）
ConfigurationProperties	提供外部化配置支持（如 `application.properties`）
依赖管理	在 `pom.xml` 或 `build.gradle` 中声明依赖
Starter 模块	提供对外暴露的接口或工具类
AutoConfiguration.imports	替代 `spring.factories`，用于注册自动配置类

📦 二、创建自定义 Starter 的完整步骤

✅ 步骤 1：创建 Maven 项目结构

my-spring-boot-starter/
├── my-spring-boot-starter-autoconfigure
│   └── src/
│       └── main/
│           ├── java/
│           └── resources/
│               └── META-INF/
│                   └── spring/
│                       └── org.springframework.boot.autoconfigure.AutoConfiguration.imports
└── my-spring-boot-starter
    └── src/
        └── main/
            └── java/

my-spring-boot-starter-autoconfigure：包含自动配置逻辑
my-spring-boot-starter：提供对外 API 接口或工具类

✅ 步骤 2：添加 Spring Boot 3.x 依赖（`pom.xml`）

`my-spring-boot-starter-autoconfigure/pom.xml`

<dependencies>
    <!-- Spring Boot 3.x 起始依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-autoconfigure</artifactId>
    </dependency>

    <!-- Jakarta EE 9+ 支持 -->
    <dependency>
        <groupId>jakarta.servlet</groupId>
        <artifactId>jakarta.servlet-api</artifactId>
        <version>6.0.0</version>
    </dependency>

    <!-- 配置属性支持 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-configuration-processor</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

`my-spring-boot-starter/pom.xml`

<dependencies>
    <!-- 引入自动配置模块 -->
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>my-spring-boot-starter-autoconfigure</artifactId>
        <version>1.0.0</version>
    </dependency>

    <!-- 其他公共依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
</dependencies>

🧱 三、实现自动配置模块（AutoConfigure）

✅ 1. 创建自动配置类

package com.example.autoconfigure;

import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@ConditionalOnClass(MyService.class) // 仅当类路径存在 MyService 时生效
public class MyAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public MyService myService() {
        return new MyService();
    }
}

✅ 2. 创建服务类

package com.example.autoconfigure;

public class MyService {
    public void doSomething() {
        System.out.println("MyService is working!");
    }
}

✅ 3. 配置属性类（可选）

package com.example.autoconfigure;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "my.service")
public class MyServiceProperties {
    private String name = "default";

    public String getName() {
        return name;
    }

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

✅ 4. 注册自动配置类（`AutoConfiguration.imports`）

在 resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 文件中添加自动配置类：

com.example.autoconfigure.MyAutoConfiguration

🔄 四、实现 Starter 模块

✅ 1. 提供对外 API 或工具类

package com.example.starter;

import org.springframework.stereotype.Component;

@Component
public class MyServiceClient {
    private final MyService myService;

    public MyServiceClient(MyService myService) {
        this.myService = myService;
    }

    public void execute() {
        myService.doSomething();
    }
}

✅ 2. 提供配置属性类（可选）

package com.example.starter;

import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableConfigurationProperties(MyServiceProperties.class)
public class MyStarterConfig {
}

🧪 五、测试自定义 Starter

✅ 1. 在另一个 Spring Boot 项目中引入 Starter

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

✅ 2. 使用 Starter 中的 Bean

@Service
public class ApplicationService {
    private final MyServiceClient client;

    public ApplicationService(MyServiceClient client) {
        this.client = client;
    }

    public void run() {
        client.execute();
    }
}

✅ 3. 配置属性（application.properties）

my.service.name=customName

🧩 六、Spring Boot 3.x Starter 的关键改进

改进点	说明
自动配置文件	使用 `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` 替代 `spring.factories`
包名迁移	使用 `jakarta.` 替代 `javax.`
AOT 支持	可通过 `@ImportRuntimeHints` 提供 AOT 编译支持
模块化支持	支持 Java 9+ 的 JPMS 模块系统
性能优化	自动配置加载更高效，减少启动时间

📦 七、发布 Starter 到 Maven Central

✅ 1. 配置 `pom.xml` 发布插件

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-deploy-plugin</artifactId>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-source-plugin</artifactId>
            <executions>
                <execution>
                    <id>attach-sources</id>
                    <goals><goal>jar</goal></goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

✅ 2. 执行发布命令

mvn clean deploy

🧱 八、完整 Starter 模块结构示例

`my-spring-boot-starter-autoconfigure`

src/
└── main/
    ├── java/
    │   └── com.example.autoconfigure/
    │       ├── MyAutoConfiguration.java
    │       ├── MyService.java
    │       └── MyServiceProperties.java
    └── resources/
        └── META-INF/
            └── spring/
                └── org.springframework.boot.autoconfigure.AutoConfiguration.imports

`my-spring-boot-starter`

src/
└── main/
    └── java/
        └── com.example.starter/
            ├── MyServiceClient.java
            └── MyStarterConfig.java

❗ 九、常见问题与解决方案

问题	原因	解决方案
自动配置未生效	未正确注册 `AutoConfiguration.imports`	确保配置类路径正确
包名错误（如 `javax`）	未替换为 `jakarta`	使用 IDE 全局替换 `javax.` → `jakarta.`
AOT 编译失败	未提供 `RuntimeHints`	添加 `@ImportRuntimeHints` 并实现 `RuntimeHintsRegistrar`
启动失败	依赖版本不兼容	使用 `spring-boot-dependencies` 统一管理版本
模块化编译失败	未正确配置 `module-info.java`	添加 `requires spring.boot.autoconfigure;` 等模块声明

✅ 十、Spring Boot 3.x Starter 关键类与接口

类/接口	作用
`AutoConfiguration.imports`	注册自动配置类
`@ConditionalOnClass`	条件化自动装配
`@ConditionalOnMissingBean`	避免重复注册 Bean
`@ImportRuntimeHints`	提供 AOT 编译支持
`RuntimeHintsRegistrar`	注册运行时依赖（如反射、资源）
`@ConfigurationProperties`	绑定外部配置
`@EnableConfigurationProperties`	启用配置属性绑定

🧩 十一、Spring Boot 3.x Starter 的高级功能（可选）

✅ 1. AOT 支持（Ahead-of-Time Compilation）

@ImportRuntimeHints(MyRuntimeHints.class)
@Configuration
public class MyAutoConfiguration {
    // ...
}

public class MyRuntimeHints implements RuntimeHintsRegistrar {
    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
        hints.reflection().registerType(MyService.class);
    }
}

✅ 2. 模块化支持（Java 9+）

module com.example.starter {
    requires spring.boot.autoconfigure;
    exports com.example.starter;
}

✅ 3. GraalVM Native Image 支持

# 使用 Spring Boot 3.x 的 Native Image 插件
./mvnw install -Pnative

📦 十二、Starter 项目依赖管理建议

依赖	推荐版本
Spring Boot 3.x	`3.0.0`
Spring Framework 6	`6.0.0`
Jakarta EE 9+	`9.0.0`
Hibernate ORM 6.x	`6.1.0`
Micrometer 2.x	`2.0.0`
Spring Security 6.x	`6.0.0`

🧪 十三、完整示例：`my-spring-boot-starter-autoconfigure`

`MyAutoConfiguration.java`

package com.example.autoconfigure;

import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@ConditionalOnClass(MyService.class)
public class MyAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public MyService myService() {
        return new MyService();
    }
}

`MyService.java`

package com.example.autoconfigure;

public class MyService {
    public void doSomething() {
        System.out.println("MyService is working!");
    }
}

`MyServiceProperties.java`

package com.example.autoconfigure;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "my.service")
public class MyServiceProperties {
    private String name = "default";

    public String getName() {
        return name;
    }

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

`AutoConfiguration.imports`

com.example.autoconfigure.MyAutoConfiguration

✅ 十四、总结

特性	Spring Boot 3.x Starter 实现
自动配置机制	使用 `AutoConfiguration.imports` 替代 `spring.factories`
包名迁移	从 `javax` 迁移到 `jakarta`
条件装配	使用 `@ConditionalOnClass`, `@ConditionalOnMissingBean`
配置属性	使用 `@ConfigurationProperties` 和 `@EnableConfigurationProperties`
AOT 支持	使用 `@ImportRuntimeHints` 和 `RuntimeHintsRegistrar`
模块化支持	使用 `module-info.java` 支持 JPMS
GraalVM 支持	支持 Native Image 编译
依赖管理	使用 Spring Boot 3.x 的依赖版本（如 Spring Framework 6.x）
性能优化	启动速度提升 20%~30%，内存占用降低 10%~20%