How to Build a Scalable SpringBoot Multi‑Module Maven Project Step‑by‑Step

1. Create the parent project

In IntelliJ IDEA choose File → New → Project , select Spring Initializr , set a GroupId (e.g., com.example) and an ArtifactId (e.g., parent-demo), pick Maven pom packaging, do not add any dependencies, and finish the wizard.

<?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>
    <version>3.1.0</version>
    <relativePath/>
  </parent>
  <groupId>com.example</groupId>
  <artifactId>parent-demo</artifactId>
  <version>1.0.0‑SNAPSHOT</version>
  <packaging>pom</packaging>
  <name>parent-demo</name>
  <description>SpringBoot 多模块父工程</description>
  <properties>
    <java.version>17</java.version>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
  </properties>
  <!-- 子模块声明 -->
  <modules>
    <!-- 后续添加 -->
  </modules>
  <!-- 依赖管理 -->
  <dependencyManagement>
    <dependencies>
      <!-- Spring Boot 依赖版本管理 -->
      <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-dependencies</artifactId>
        <version>3.1.0</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      <!-- Spring Cloud 依赖管理（可选） -->
      <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-dependencies</artifactId>
        <version>2022.0.3</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      <!-- 其他公共依赖版本 -->
      <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson</artifactId>
        <version>2.0.34</version>
      </dependency>
    </dependencies>
  </dependencyManagement>
</project>

2. Add submodules

2.1 Common module

This module holds shared utilities, constants, and custom exceptions.

<project>
  <parent>
    <artifactId>parent-demo</artifactId>
  </parent>
  <groupId>com.example</groupId>
  <artifactId>common</artifactId>
  <version>1.0.0‑SNAPSHOT</version>
  <dependencies>
    <!-- Spring 基础依赖 -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <!-- Lombok -->
    <dependency>
      <groupId>org.projectlombok</groupId>
      <artifactId>lombok</artifactId>
      <optional>true</optional>
    </dependency>
  </dependencies>
</project>

2.2 Business module (user‑service)

Implements user‑related APIs and depends on the common module. It includes Spring Boot starter, Lombok, web, JPA and MySQL driver.

<project>
  <parent>
    <artifactId>parent-demo</artifactId>
  </parent>
  <groupId>com.example</groupId>
  <artifactId>user-service</artifactId>
  <version>1.0.0‑SNAPSHOT</version>
  <dependencies>
    <!-- 依赖 common 模块 -->
    <dependency>
      <groupId>com.example</groupId>
      <artifactId>common</artifactId>
    </dependency>
    <!-- Web 支持 -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- 数据库支持 -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
      <groupId>mysql</groupId>
      <artifactId>mysql-connector-java</artifactId>
    </dependency>
    <!-- 可执行模块才需要 -->
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
    </plugin>
  </dependencies>
</project>

2.3 API gateway module

Acts as the entry point and also depends on common. It adds Spring Cloud Gateway.

<project>
  <parent>
    <artifactId>parent-demo</artifactId>
  </parent>
  <groupId>com.example</groupId>
  <artifactId>api-gateway</artifactId>
  <version>1.0.0‑SNAPSHOT</version>
  <dependencies>
    <dependency>
      <groupId>com.example</groupId>
      <artifactId>common</artifactId>
    </dependency>
    <!-- Spring Cloud Gateway -->
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-starter-gateway</artifactId>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

3. Declare modules in the parent pom

<modules>
  <module>common</module>
  <module>user-service</module>
  <module>api-gateway</module>
</modules>

4. Project structure example

parent-demo/
├── pom.xml (parent)
├── common/
│   └── pom.xml
├── user-service/
│   └── pom.xml
└── api-gateway/
    └── pom.xml

5. Configure each module’s main class

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

6. Isolate logs per module

spring:
  application:
    name: user-service
logging:
  file:
    name: logs/${spring.application.name}.log

7. Build and run

Build the whole project: mvn clean install Run a specific module: mvn spring-boot:run -pl user-service Package a module:

mvn clean package -pl user-service -am

8. Common pitfalls

Submodule cannot see common – execute mvn clean install first so the common module is installed to the local repository.

Parent should not contain a main class – keep @SpringBootApplication only in executable submodules.

Do not add spring-boot-maven-plugin to the parent – add it only to modules that produce a runnable jar.

9. Recommended enterprise‑grade layout

parent-demo/
├── common-core/      # utilities
├── common-dto/       # DTO / VO
├── common-db/        # database configuration
├── common-security/  # unified authentication / authorization
├── user-service/     # user domain
├── order-service/    # order domain
├── api-gateway/      # gateway
├── auth-service/     # auth & token service
└── pom.xml