在企業級應用開發中，我們經常會遇到一些通用的功能模塊，比如統一的日志處理、RPC 調用客戶端、特定的安全認證邏輯等如果每個項目都重復編寫這些配置和代碼，效率低下且容易出錯

Spring Boot Starter 的出現，正是為了解決這個問題。Starter 是一種特殊的 Maven 或 Gradle 依賴，它能夠將相關的依賴和自動化配置打包在一起，讓其他項目只需要簡單地引入一個 Starter 依賴，就能自動獲得所需的功能，無需手動配置

本文將基于 Spring Boot 的自動化裝配原理，手把手教你如何制作自己的 Spring Boot Starter 依賴

1. Spring Boot Starter 的本質

Spring Boot Starter 的本質是一個依賴聚合器和自動化配置提供者

• 依賴聚合: 一個 Starter 通常會引入實現某個功能所需的所有其他依賴例如，spring-boot-starter-web 會引入 Spring MVC、Tomcat 等依賴
• 自動化配置: Starter 中包含了自動化配置類，這些類會根據當前項目的環境（依賴、配置等）自動配置相關的 Bean，使得用戶無需手動編寫繁瑣的配置

制作自己的 Starter，就是將你的通用功能封裝在一個或多個模塊中，并按照 Spring Boot 的規范提供自動化配置

---

2. Starter 的模塊結構（推薦）

為了清晰起見，通常會將一個 Starter 分為兩個模塊：

• xxx-spring-boot-starter: 這是提供給用戶引入的模塊它本身不包含實際的代碼，只作為依賴的入口，主要依賴于 xxx-spring-boot-autoconfigure 模塊
• xxx-spring-boot-autoconfigure: 這是包含實際自動化配置邏輯的模塊你所有的配置類、條件注解、以及 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 文件都放在這個模塊中

這種分離的好處是：

• 職責分離: Starter 模塊只負責依賴管理，autoconfigure 模塊負責自動化配置邏輯
• 清晰: 用戶引入 Starter 模塊即可，無需關心內部實現

當然，對于簡單的 Starter，你也可以將所有內容放在一個模塊中，但這不符合最佳實踐

---

3. 制作 xxx-spring-boot-autoconfigure 模塊

這是實現自動化配置的核心模塊

3.1 添加必要的依賴

首先，在 xxx-spring-boot-autoconfigure 模塊的 pom.xml (Maven) 或 build.gradle (Gradle) 中添加 Spring Boot 的自動化配置依賴：

Maven:

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-autoconfigure</artifactId>
</dependency>
<!-- 如果你的自動化配置依賴于某個第三方庫，也需要在這里添加 -->
<!-- <dependency><groupId>com.example</groupId><artifactId>some-library</artifactId>
</dependency> -->

Gradle:

implementation 'org.springframework.boot:spring-boot-autoconfigure'
// 如果你的自動化配置依賴于某個第三方庫，也需要在這里添加
// implementation 'com.example:some-library'

spring-boot-autoconfigure 模塊包含了 @ConditionalOn... 等條件注解，以及 Spring Boot 自動化配置所需的基礎設施

3.2 編寫具體功能的配置類

創建包含你通用功能具體 Bean 定義的配置類這些類通常使用 @Configuration 和 @Bean 注解

// src/main/java/com/example/starter/autoconfigure/MyServiceConfig.java
@Configuration
public class MyServiceConfig {// 定義一個通用的服務 Bean@Beanpublic MyService myService() {return new MyService();}// 如果你的服務需要配置屬性，可以使用 @ConfigurationProperties@Bean@ConfigurationProperties(prefix = "my.service")public MyServiceProperties myServiceProperties() {return new MyServiceProperties();}
}

3.3 編寫自動化配置類 (@AutoConfiguration)

創建標記為 @AutoConfiguration 的自動化配置類這個類將作為自動化配置的入口，并使用相應的條件注解來控制何時生效

// src/main/java/com/example/starter/autoconfigure/MyServiceAutoConfiguration.java
@AutoConfiguration // 標記為自動化配置類 (Spring Boot 2.7+)
// @Configuration // 兼容早期版本，但推薦使用 @AutoConfiguration
@ConditionalOnClass(MyService.class) // 條件：只有當 MyService.class 存在時才生效
@EnableConfigurationProperties(MyServiceProperties.class) // 啟用配置屬性綁定
@Import(MyServiceConfig.class) // 導入包含具體 Bean 定義的配置類
public class MyServiceAutoConfiguration {// 這個類本身可以不定義 Bean，主要通過 @Import 導入其他配置類// 也可以在這里直接定義 Bean，并使用條件注解// @Bean// @ConditionalOnMissingBean // 如果沒有 MyService 的 Bean，則創建默認的// public MyService defaultMyService() {//     return new MyService();// }
}

重要提示：

• 使用 @AutoConfiguration 注解（Spring Boot 2.7+）
• 使用 @ConditionalOnClass 等條件注解來控制自動化配置的生效條件通常會判斷某個核心類是否存在，或者某個配置屬性是否設置
• 使用 @Import 注解導入包含具體 Bean 定義的配置類
• 如果你的功能需要配置屬性，使用 @EnableConfigurationProperties 和 @ConfigurationProperties 來綁定屬性

3.4 注冊自動化配置類 (.imports 或 spring.factories)

這是最關鍵的一步，讓 Spring Boot 能夠找到你的自動化配置類

推薦方式 (Spring Boot 2.7+):

在 xxx-spring-boot-autoconfigure 模塊的 src/main/resources/META-INF/spring/ 目錄下創建 org.springframework.boot.autoconfigure.AutoConfiguration.imports 文件

在該文件中，每行填寫一個你的自動化配置類的全限定名：

# src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
com.example.starter.autoconfigure.MyServiceAutoConfiguration

兼容早期版本方式:

在 xxx-spring-boot-autoconfigure 模塊的 src/main/resources/META-INF/ 目錄下創建 spring.factories 文件

在該文件中，添加如下內容：

# src/main/resources/META-INF/spring.factories
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.example.starter.autoconfigure.MyServiceAutoConfiguration

在 Spring Boot 2.7+ 中，你可以同時使用這兩種方式，但推薦優先使用 .imports 文件

---

4. 制作 xxx-spring-boot-starter 模塊

這個模塊非常簡單，它的主要作用就是依賴 xxx-spring-boot-autoconfigure 模塊，并遵循 Starter 的命名規范

在 xxx-spring-boot-starter 模塊的 pom.xml (Maven) 或 build.gradle (Gradle) 中添加依賴：

Maven:

<dependency><groupId>com.example</groupId><artifactId>my-service-spring-boot-autoconfigure</artifactId><version>1.0.0-SNAPSHOT</version>
</dependency>

Gradle:

implementation 'com.example:my-service-spring-boot-autoconfigure:1.0.0-SNAPSHOT'

這個模塊通常不需要編寫任何 Java 代碼

---

5. 使用你的 Starter 依賴

現在，其他 Spring Boot 項目只需要在 pom.xml 或 build.gradle 中引入你的 Starter 依賴即可：

Maven:

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

Gradle:

implementation 'com.example:my-service-spring-boot-starter:1.0.0-SNAPSHOT'

當用戶引入這個依賴后，你的 xxx-spring-boot-autoconfigure 模塊就會被添加到項目的運行時類路徑中。Spring Boot 啟動時，AutoConfigurationImportSelector 會找到并加載 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 文件（或 spring.factories），發現并處理你的 MyServiceAutoConfiguration如果條件滿足，MyServiceAutoConfiguration 中導入的 MyServiceConfig 生效，MyService Bean 就會被自動創建并注冊到 Spring 容器中

用戶可以直接在他們的代碼中注入并使用 MyService：

@Service
public class SomeBusinessLogic {@Autowiredprivate MyService myService; // 直接注入，無需手動配置// ... 使用 myService
}

---

6. 最佳實踐和注意事項

• 命名規范: 遵循 Spring Boot Starter 的命名規范 xxx-spring-boot-starter
• 版本管理: 合理管理你的 Starter 版本
• 文檔: 為你的 Starter 提供清晰的文檔，說明它的功能、如何使用、支持哪些配置屬性等
• 條件注解: 充分利用條件注解，確保你的自動化配置只在需要時生效，避免不必要的 Bean 創建和沖突
• 配置屬性: 如果你的功能需要用戶進行配置，使用 @ConfigurationProperties 提供類型安全的配置
• 日志: 在自動化配置類中使用日志，方便用戶排查問題
• 測試: 編寫自動化測試來驗證你的 Starter 是否按預期工作

---

總結

制作自己的 Spring Boot Starter 依賴，是提升代碼復用性和開發效率的有效手段通過理解 Spring Boot 的自動化裝配原理，特別是 META-INF/spring.factories 和 .imports 文件以及條件注解的作用，你就能輕松地將你的通用功能封裝成易于使用的 Starter，讓其他項目能夠享受到自動化裝配帶來的便利