搭建 Spring Boot 多模块工程(通过 Maven Archetype)

犬小哈 2023-11-24 约 2,840 字 大约 10 分钟 共 31 张图 6,925

友情提示

推荐您使用 Chrome 浏览器来阅读本实战专栏,其他浏览器可能存在兼容性问题。

本小节为补充内容,原因是部分球友反馈说,IDEA 新建项目时,如果通过 Spring Initializr 来创建 Spring Boot , 已经无法选择 Java 8 版本,通过上小节的教程,不知道该如何创建 Spring Boot 多模块工程。如下图所示:

本小节中,小哈就来演示一下另一种方式,通过 Maven Archetype 来创建 Spring Boot 多模块工程。

IDEA 搭建 Spring Boot 多模块工程骨架

开始动手

首先选择一个位置,新建一个名为 weblog 的工程目录,用于统一存放后续要创建的后端项目、前端项目,方便管理:

创建父项目

打开 IDEA, 依次点击菜单 File -> New -> Project, 准备新建父项目 :

  • ①:选择 Maven Archetype 来创建项目;
  • ②:填写工程名称;
  • ③:工程路径;
  • ④:选择 JDK 1.8 版本;
  • ⑤: IDEA 需要知道 Maven Archetype Catalog 的位置,以便从中获取可用的 Archetype 列表。这个 Catalog 文件通常包含了 Maven 官方仓库或其他远程仓库中可用的 Archetype 信息。我这里选择的是 Default Local , 也就是我本地安装的 Maven 路径:

    TIP: 如果选择 Default Local 后,Archetype 下拉框没有相关选项,就选择 Internal, 都差不多的。

  • ⑥:通过使用 Archetype,你可以基于已有的项目模板创建一个新项目,从而加快项目的启动和初始化过程,选择 maven-archetype-site-simple
  • ⑦:填写 Group 组织名称,通常为公司域名倒写,如 com.quanxiaoha
  • ⑧:项目的唯一标识符;
  • ⑨:项目版本号,默认就行;

所有选项填写完成后,点击 Create 创建项目:

因为这是个父项目,专门负责统一管理子模块、依赖版本等,不包含功能代码,所以,创建完成后,在左边导航栏中,还需要将 /src 这个文件夹删除掉,最终目录结构如下:

接下来,整理一下父项目的 pom.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>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <!-- 将 Spring Boot 的版本号切换成 2.6 版本 -->
        <version>2.6.3</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <groupId>com.quanxiaoha</groupId>
    <artifactId>weblog-springboot</artifactId>
    <version>${revision}</version>
    <name>weblog-springboot</name>
    <!-- 项目描述 -->
    <description>前后端分离博客 Weblog By 犬小哈</description>

    <!-- 多模块项目父工程打包模式必须指定为 pom -->
    <packaging>pom</packaging>

    <!-- 子模块管理 -->
    <modules>
    </modules>


    <!-- 版本号统一管理 -->
    <properties>
        <!-- 项目版本号 -->
        <revision>0.0.1-SNAPSHOT</revision>
        <java.version>1.8</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        
        <!-- Maven 相关 -->
        <maven.compiler.source>${java.version}</maven.compiler.source>
        <maven.compiler.target>${java.version}</maven.compiler.target>
        
    </properties>

    <!-- 统一依赖管理 -->
    <dependencyManagement>

    </dependencyManagement>

    <build>
        <!-- 统一插件管理 -->
        <pluginManagement>

        </pluginManagement>
    </build>
    
    <!-- 使用阿里云的 Maven 仓库源,提升包下载速度 -->
    <repositories>
        <repository>
            <id>aliyunmaven</id>
            <name>aliyun</name>
            <url>https://maven.aliyun.com/repository/public</url>
        </repository>
    </repositories>
</project>

创建 web 访问模块(打包也在这个模块中进行)

接下来,我们开始创建父项目下面的子模块。在父项目上右键,添加模块 Module:

还是和上面创建父项目差不多的步骤,创建一个 weblog-web 模块,此模块是项目的入口,Maven 打包插件也是放在此模块下,另外,和博客前台页面展示相关的功能也统一放在该模块下:

TIP : 唯一多的一个选项就是 Parent , 用于指定该模块的父项目。

点击 Create 创建子模块,创建完成后,打开父项目的 pom.xml 文件,就可以看到在 <modules> 子节点下,已经自动添加了 weblog-web 模块了。接着,我们还需要再添加一个 spring-boot-maven-plugin 插件,代码如下:

<!-- 子模块管理 -->
<modules>
    <!-- 入口模块 -->
    <module>weblog-web</module>
</modules>

<build>
        <!-- 统一插件管理 -->
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                    <configuration>
                        <excludes>
                            <exclude>
                                <groupId>org.projectlombok</groupId>
                                <artifactId>lombok</artifactId>
                            </exclude>
                        </excludes>
                    </configuration>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>

添加完成后,开始编辑 weblog-web 模块中的 pom.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>
    <!-- 指定父项目为 weblog-springboot -->
    <parent>
        <groupId>com.quanxiaoha</groupId>
        <artifactId>weblog-springboot</artifactId>
        <version>${revision}</version>
    </parent>

    <groupId>com.quanxiaoha</groupId>
    <artifactId>weblog-web</artifactId>
    <name>weblog-web</name>
    <description>weblog-web (入口项目,负责博客前台展示相关功能,打包也放在这个模块负责)</description>

    <dependencies>
        <!-- Spring Boot Web 依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- 免写冗余的 Java 样板式代码 -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <!-- 单元测试 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

手动添加 Spring Boot 启动类

然后,将 weblog-web 子模块中 /com/quanxiaoha 包下的 App.java 文件删除掉,并新创建包 /weblog/web , 然后手动添加 Spring Boot 的启动类,类名为 WeblogWebApplication , 代码如下:

package com.quanxiaoha.weblog.web;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class WeblogWebApplication {

    public static void main(String[] args) {
        SpringApplication.run(WeblogWebApplication.class, args);
    }

}

手动添加单元测试类

启动类添加完成后,将 /test/java/com/quanxiaoha 下自动生成的测试类删除掉,并添加 /weblog/web 包,在里面手动添加单元测试类,类名为 WeblogWebApplicationTests , 代码如下:

package com.quanxiaoha.weblog.web;

import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
@Slf4j
public class WeblogWebApplicationTests {

    @Test
    public void test() {
        // 编写单元测试
    }
}

你可能会遇到的问题

依赖爆红解决方案

pom.xml 文件中的依赖出现爆红等情况,通过点击右侧栏 Reload 图标,重新加载 Maven 项目,拉取依赖包来解决:

控制台出现警告的解决方案

在执行 Maven 命令时,若使用 IDEA 默认的 Maven 配置,可能会导致后面打包控制台出现如下警告:

可在点击 File -> Settings 找到 Maven 选项,默认是使用 IDEA 自带的 Maven 版本, 这里将 Maven home path 设置为前面小节中,我们手动安装好的 Maven 路径,再次执行 Maven 命令,即警告信息消失了:

执行 mvn clean package 命令报错

执行 mvn clean package 等相关命令时, 控制台提示如下图所示的错误,这个问题星球内好多人反馈都有犯:

问题原因是,在子模块中的 <parent></parent> 节点下添加了 <relativePath/> ,注意,它只需要在父级项目中添加一次即可,子模块中是无需添加这个的,一定要去掉:

启动项目

接下来,我们来启动一下这个简单版本的 Spring Boot 多模块项目,看看能否启动成功。打开 WeblogWebApplication 类,点击左边的运行按钮来启动项目:

若控制台能够正确打印如下日志,则表示 Spring Boot 启动成功了,运行端口为 8080

再打开浏览器,访问地址:http://localhost:8080/ ,若能够显示以下错误页面,则项目的的确确运行成功了:

创建 Admin 管理后台功能模块

接着,再次新建一个负责 Admin 管理后台功能的子模块,命名为 weblog-module-admin ,此模块用于统一放置和 Admin 管理后台相关的功能:

创建成功后,在父项目的 pom.xml 文件中,就会自动添加好了该子模块:

 <!-- 子模块管理 -->
    <modules>
        <!-- 入口模块 -->
        <module>weblog-web</module>
        <!-- 管理后台 -->
        <module>weblog-module-admin</module>
    </modules>

然后,删除掉一些无用的文件夹、文件,如 App.java , 以及 /test 测试文件夹,并在 /main/java/com/quanxiaoha 的包下,新创建 /weblog/admin 包,如下图所示:

最后,再整理一下此模块的 pom.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>
	<!-- 指定父项目为 weblog-springboot -->
	<parent>
		<groupId>com.quanxiaoha</groupId>
		<artifactId>weblog-springboot</artifactId>
		<version>${revision}</version>
	</parent>

	<groupId>com.quanxiaoha</groupId>
	<artifactId>weblog-module-admin</artifactId>
	<name>weblog-module-admin</name>
	<description>weblog-admin (负责管理后台相关功能)</description>

	<dependencies>
		<!-- 免写冗余的 Java 样板式代码 -->
		<dependency>
			<groupId>org.projectlombok</groupId>
			<artifactId>lombok</artifactId>
			<optional>true</optional>
		</dependency>

		<!-- 单元测试 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
	</dependencies>

</project>

创建 common 通用功能子模块

依葫芦画瓢,按照上面的步骤,再次创建 weblog-module-common 子模块,此模块专门用于存放一些通用的功能,如接口的日志切面、全局异常管理等等,后续小节会讲到,这里先把子模块建好。

创建成功后,在父项目的 pom.xml 文件中,也就有了该子模块:

    <!-- 子模块管理 -->
    <modules>
        <!-- 入口模块 -->
        <module>weblog-web</module>
        <!-- 管理后台 -->
        <module>weblog-module-admin</module>
        <!-- 通用模块 -->
        <module>weblog-module-common</module>
    </modules>

weblog-mudule-admin 子模块一样,再删除掉无用的文件,并在 /main/java/com/quanxiaoha 包下,创建 /weblog/common 包,如下图所示:

最终其 pom.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>
	<parent>
		<groupId>com.quanxiaoha</groupId>
		<artifactId>weblog-springboot</artifactId>
		<version>${revision}</version>
	</parent>

	<groupId>com.quanxiaoha</groupId>
	<artifactId>weblog-module-common</artifactId>
	<name>weblog-module-common</name>
	<description>weblog-module-common (此模块用于存放一些通用的功能)</description>

	<dependencies>
		<!-- 免写冗余的 Java 样板式代码 -->
		<dependency>
			<groupId>org.projectlombok</groupId>
			<artifactId>lombok</artifactId>
			<optional>true</optional>
		</dependency>

		<!-- 单元测试 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
	</dependencies>

</project>

父项目统一版本管理

接着,在父项目的 pom.xml 中,将这几个子模块统一纳入管理,另外添加相关常用的工具包,如 commons-lang3guava

<!-- 版本号统一管理 -->
    <properties>
        ...

        <!-- 依赖包版本 -->
        <lombok.version>1.18.28</lombok.version>
        <guava.version>31.1-jre</guava.version>
        <commons-lang3.version>3.12.0</commons-lang3.version>
    </properties>
    
<!-- 统一依赖管理 -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>com.quanxiaoha</groupId>
                <artifactId>weblog-module-admin</artifactId>
                <version>${revision}</version>
            </dependency>

            <dependency>
                <groupId>com.quanxiaoha</groupId>
                <artifactId>weblog-module-common</artifactId>
                <version>${revision}</version>
            </dependency>

            <!-- 常用工具库 -->
            <dependency>
                <groupId>com.google.guava</groupId>
                <artifactId>guava</artifactId>
                <version>${guava.version}</version>
            </dependency>

            <dependency>
                <groupId>org.apache.commons</groupId>
                <artifactId>commons-lang3</artifactId>
                <version>${commons-lang3.version}</version>
            </dependency>
        </dependencies>
    </dependencyManagement>    

子模块之间的依赖关系

这几个子模块之间,互相还存在依赖关系,我们也需要引入一下。如入口模块 weblog-web 依赖于 weblog-module-adminweblog-module-common,在其 pom.xml 添加如下:

<dependencies>
        <dependency>
            <groupId>com.quanxiaoha</groupId>
            <artifactId>weblog-module-common</artifactId>
        </dependency>

        <dependency>
            <groupId>com.quanxiaoha</groupId>
            <artifactId>weblog-module-admin</artifactId>
        </dependency>

        ...
    </dependencies>

以及 weblog-module-admin 依赖于 weblog-module-common,在其 pom.xml 添加如下:

<dependencies>
		<dependency>
			<groupId>com.quanxiaoha</groupId>
			<artifactId>weblog-module-common</artifactId>
		</dependency>

		...
	</dependencies>

打包测试看看,有没有报错

在 IDEA 中执行 Maven 的 clean package 打包命令,看看是否能够正常给项目打包:

⚠️ 注意:企业开发中,一般都比较追求敏捷开发,可能不会写太多的单元测试。本实战项目同样为了追求进度,不会编写单元测试,所以多模块的单元测试并未配置完成,这里,需要如下图所示,将跳过单元测试勾选上

  • ①:执行 mvn clean 命令;
  • ②:执行 mvn package 打包命令;

如果没有问题,控制台会提示 BUILD SUCCESS 表示构建成功:

打包成功后的 Jar 包,可以在项目目录的 weblog-web 入口模块中的 /target 目录下找到:

再次启动该 Spring Boot 项目

进入 weblog-web 入口项目,找到 WeblogWebApplication 启动类,点击启动图标,看看包含多个子模块的 Spring Boot 项目,能否正常运行:

若控制台能够正确打印如下日志,则表示 Spring Boot 启动成功:

至此,搭建 Spring Boot 多模块工程就成功啦,是不是还挺简单的。

本小节对应源码

https://t.zsxq.com/14db9BatT

最后编辑于 2024-06-07 11:49:37