从零起步打造专属Spring Boot Starter

文章标题：

从零起步打造个性化Spring Boot Starter

文章内容：

目录

• 引言
• 前期相关回顾
• • 基础认知
  • 项目结构情况
  • 实践搭建
  • • Spring Boot Starter项目的创建
  • 自动生成客户端
  • 编写元数据(可选择)
  • Starter安装至本地仓库
  • 测试Starter
  • • 运用注解开启Starter自动构建
  • 打包与发布流程

引言

本次博客是SpringBoot万字长文入门的补充内容，此期将会讲解自定义Spring Boot Starter的方法。

前期相关回顾

万字长文入门SpringBoot，你的入门指南(一)(Maven,SpringMVC,RESTful,JPA,MyBatis Plus,Druid）
万字长文入门SpringBoot，你的入门指南(二)(IOC，AOP，Redis，Spring Security，RabbitMQ，Elasticsearch）

基础认知

Spring Boot Starter本质上是一个封装好的依赖模块，方便开发者快速引入所需功能。自定义Starter一般包含自动配置类、条件注解、属性配置类，还有Maven/Gradle的依赖管理。
核心组成部分：

• 配置属性类（@ConfigurationProperties）：将application.properties中的自定义配置进行绑定。
• 自动配置类（@Configuration + 条件注解）：通过@ConditionalOnClass、@ConditionalOnProperty等实现有条件地注册Bean。
• 依赖声明（pom.xml）：最小化依赖传递，通过optional=true来控制非必要依赖。

项目结构情况

我们来看看即将创建的SpringBootStarter项目的文件结构：

实践搭建

Spring Boot Starter项目的创建

首先用Maven创建一个空的Java项目spring-boot-starter-demo，在pom.xml中加入SpringBoot依赖以及Starter规范依赖
1 Spring Boot Starter Maven依赖

     <dependencies>
         <!-- Spring Boot 自动配置核心依赖 -->
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-autoconfigure</artifactId>
         </dependency>
         <!-- Starter 配置元数据处理器 -->
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-configuration-processor</artifactId>
             <optional>true</optional>
         </dependency>
         <!-- Lombok 依赖 -->
         <dependency>
             <groupId>org.projectlombok</groupId>
             <artifactId>lombok</artifactId>
             <optional>true</optional>
         </dependency>
     </dependencies>

此外，为了之后在SpringBoot测试项目中引入，pom文件中必须有这样的信息声明：

    <groupId>com.cxytiandi</groupId>
    <artifactId>spring-boot-starter-demo</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <name>Spring Boot Starter Demo</name>
    <description>自定义 Spring Boot Starter 示例</description>

2 创建一个配置类，用于在属性文件中配置值，将application.properties中自定义的配置进行绑定。

    package com.cxytiandi.demo;
    import org.springframework.boot.context.properties.ConfigurationProperties;
    import lombok.Data;
    @Data
    @ConfigurationProperties("spring.user")
    public class UserProperties { 
        private String name;
    }

3 再定义一个Client，里面定义一个方法，用来获取配置中的值。

    package com.cxytiandi.demo;
    public class UserClient {
        private final UserProperties userProperties; // 使用 final 增强不可变性

        // 有参构造函数
        public UserClient(UserProperties userProperties) {
            this.userProperties = userProperties;
        }

        public String getName() {
            return userProperties.getName();
        }
    }

自动生成客户端

上面已经具备了最基本的Starter的包，不过现在还不能使用UserClient，因为还没有它的实例，我们通过编写自动配置类，使用@configuration和@Conitional注解实现有条件地自动配置，创建实例。

    @Bean
    @ConditionalOnProperty(
        prefix = "spring.user",
        name = "enabled",
        havingValue = "true"
    )
    public UserClient userClient(UserProperties userProperties) {
        return new UserClient(userProperties);
    }

Spring Boot通过SPI（Service Provider Interface）识别自动配置类，Spring Boot会默认扫描跟启动类平级的包，假如我们的Starter跟启动类不在同一个主包下，如何能让UserAutoConfigure生效？在resources下创建一个META-INF文件夹，然后在META-INF文件夹中创建一个spring.factories文件，文件中指定自动配置的类：

    org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.cxytiandi.demo.UserAutoConfigure

编写元数据(可选择)

生成配置提示信息，方便开发者在IDE中使用。
路径：src/main/resources/META-INF/spring-configuration-metadata.json

    {
        "groups": [
            {
                "name": "spring.user",
                "type": "com.cxytiandi.demo.UserProperties", 
                "sourceType": "com.cxytiandi.demo.UserProperties" 
            }
        ],
        "properties": [
            {
                "name": "spring.user.name",
                "type": "java.lang.String",
                "description": "用户名称配置，用于标识当前用户",
                "defaultValue": null
            }
        ]
    }

Starter安装至本地仓库

当我们在Starter项目中执行mvn install命令时，Maven会编译代码并打包成JAR文件，同时将JAR文件、POM文件等元数据存入本地仓库，路径为：

    ~/.m2/repository/com/cxytiandi/spring-boot-starter-demo/1.0.0-SNAPSHOT/

其中包含spring-boot-starter-demo-1.0.0-SNAPSHOT.jar和spring-boot-starter-demo-1.0.0-SNAPSHOT.pom。本地开发时，只要Starter已通过mvn install安装到本地仓库，测试项目就能直接引用。接下来我们进行一下测试自定义的Starter。

测试Starter

新建一个SpringBoot项目，在pom.xml添加本地Starter依赖。
1 SpringBootStarter使用Maven配置

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>com.cxytiandi</groupId>
            <artifactId>spring-boot-starter-demo</artifactId>
            <version>1.0.0-SNAPSHOT</version>
        </dependency>
    </dependencies>

引入之后就直接可以使用UserClient，UserClient在项目启动的时候已经自动初始化好。
2 客户端使用

    @RestController
    public class UserController {

        @Autowired
        private UserClient userClient;

        @GetMapping("/user/name")
        public String getUserName() {
            return userClient.getName();
        }

    }

3 配置属性文件中启动

    spring.user.name=yinjihuan
    spring.user.enabled=true

4 结果
访问/user/name就可以返回我们配置的yinjihuan。

运用注解开启Starter自动构建

在之前我们使用的是通过在resources下创建一个META-INF文件夹的spring.factories文件，其实也可以通过注解的方式来开启是否自动配置，如果用注解的方式，那么spring.factories就不需要编写了。注解定义如下：

    @Target({ElementType.TYPE})
    @Retention(RetentionPolicy.RUNTIME)
    @Documented
    @Inherited
    @Import({UserAutoConfigure.class})
    public @interface EnableUserClient {

    }

这段代码的核心是@Import({UserAutoConfigure.class})，通过导入的方式实现把UserAutoConfigure实例加入SpringIOC容器中，这样就能开启自动配置了。使用方式就是我们在测试项目SpringBootDemoApplication中的启动类上加上该注解，就能使用自定义Starter了。

    @SpringBootApplication
    @EnableUserClient 
    public class SpringBootDemoApplication {
        public static void main(String[] args) {
            SpringApplication.run(SpringBootDemoApplication.class, args);
        }
    }

打包与发布流程

当然自定义Starter完后，我们可以构建Jar包并发布到Maven仓库，Maven仓库分为公共库以及私有库。
1 构建Jar包 ：
使用Maven命令打包

    # 清理并编译项目，生成 Jar 包（存放在 target/ 目录）
    mvn clean package

    # 同时将 Jar 包安装到本地仓库（供本地其他项目依赖）
    mvn clean install

2 发布到Maven仓库 ：

• 如果是公共库，注册到Maven Central。
  Maven Central是全球最大的公共Maven仓库，需通过Sonatype Nexus Repository Manager提交。详细步骤：
  1） 访问Sonatype Jira注册页面，创建账号并提交项目申请（需提供groupId对应的域名所有权证明，如com.cxytiandi需拥有cxytiandi.com域名）。
  2） 生成GPG签名

    # 安装 GPG 工具（Linux/macOS: gpg, Windows: Gpg4win）
    # 生成密钥对
    gpg --gen-key

    # 导出公钥（提交到 Sonatype 及 Maven Central）
    gpg --export -a your_email@example.com > public.key

3） 配置POM文件

    <project>
        <!-- 其他配置 -->

        <properties>
            <!-- 强制使用 GPG 签名 -->
            <gpg.executable>gpg</gpg.executable>
            <gpg.passphrase>你的 GPG 密钥密码</gpg.passphrase>
        </properties>

        <distributionManagement>
            <!-- 快照仓库（开发版本） -->
            <snapshotRepository>
                <id>sonatype-nexus-snapshots</id>
                <url>https://s01.oss.sonatype.org/content/repositories/snapshots/</url>
            </snapshotRepository>
            <!-- 发布仓库（正式版本） -->
            <repository>
                <id>sonatype-nexus-staging</id>
                <url>https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/</url>
            </repository>
        </distributionManagement>
        <licenses>
            <license>
                <name>The Apache License, Version 2.0</name>
                <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
            </license>
        </licenses>
        <developers>
            <developer>
                <name>Your Name</name>
                <email>your-email@example.com</email>
            </developer>
        </developers>
    </project>

4） 执行发布命令

    # 发布快照版本（版本号需包含 -SNAPSHOT）
    mvn clean deploy -P release-sonatype

    # 发布正式版本（需先移除 -SNAPSHOT 后缀）
    mvn clean deploy -P release-sonatype -DskipTests

5） 在 Maven Central 验证
提交后等待 Sonatype 审核（通常 1-2 小时），审核通过后，运行以下命令同步索引：

    mvn versions:update-release-repository

• 如果是私有库，配置Nexus/Artifactory等仓库，并更新pom.xml中的发布信息：
  以Nexus为例，假设私有仓库地址为http://your-nexus-server/repository/maven-releases/。
  1） 配置仓库信息

    <distributionManagement>
        <!-- 快照仓库（开发版本，路径包含 snapshots/） -->
        <snapshotRepository>
            <id>nexus-snapshots</id>
            <url>http://your-nexus-server/repository/maven-snapshots/</url>
        </snapshotRepository>
        <!-- 发布仓库（正式版本，路径包含 releases/） -->
        <repository>
            <id>nexus-releases</id>
            <url>http://your-nexus-server/repository/maven-releases/</url>
        </repository>
    </distributionManagement>

2 ）配置认证信息

    <servers>
        <server>
            <id>nexus-snapshots</id> <!-- 需与 pom.xml 中的 id 一致 -->
            <username>仓库用户名</username>
            <password>仓库密码</password>
        </server>
        <server>
            <id>nexus-releases</id>
            <username>仓库用户名</username>
            <password>仓库密码</password>
        </server>
    </servers>

3） 执行发布命令

    # 发布快照版本（版本号为 x.x.x-SNAPSHOT）
    mvn clean deploy -DaltSnapshotRepository=nexus-snapshots::default::http://your-nexus-server/repository/maven-snapshots/

    # 发布正式版本（版本号为 x.x.x）
    mvn clean deploy -DaltRepository=nexus-releases::default::http://your-nexus-server/repository/maven-releases/

总结

本期博客从无到有搭建Spring Boot Starter，学习完后，我们能更深入理解Spring Boot Starter的内部原理，能更好地理解SpringBoot的启动流程以及增强对SpringBoot自动配置的理解。

写在文末

有疑问的朋友，欢迎在评论区交流 ，笔者看到会及时回复 。

创作不易，求关注，点赞，收藏，谢谢~