Maven Multi-module Project Management

A Maven multi-module project refers to a project structure where a parent project contains multiple submodules. This structure allows us to split a large project into multiple logically independent yet interrelated modules, each of which can be built separately or together as a whole.

Advantages of Multi-module Projects

1. Code reuse: Common code can be extracted into a separate module for use by other modules
2. Separation of concerns: Different teams can focus on developing different modules
3. Build efficiency: Only changed modules are built, reducing build time
4. Dependency management: Centrally manage the dependency relationships of all modules
5. Version control: All modules use a unified version number for easier management

Applicable Scenarios

• Layering large projects (e.g.,web、service、dao）

• Microservices architecture (one module per service)

• Sharing common code (e.g.,commonModule)

Standard Directory Structure

parent-project/          # 父项目根目录
├── pom.xml             # 父POM（packaging=pom）
├── module-a/           # 子模块A
│   ├── src/
│   └── pom.xml         # 子模块A的POM
├── module-b/           # 子模块B
│   ├── src/
│   └── pom.xml         # 子模块B的POM
└── module-web/         # Web模块
    ├── src/
    └── pom.xml

Key features:

1. Parent POM：

   • Must set<packaging>pom</packaging>

   • via<modules>Manage submodules

2. Submodules：

   • via<parent>inherit the parent POM

   • can have their own dependencies and build configurations

Creating a Maven Multi-module Project

1. Create the Parent Project

The parent project itself usually does not contain any code; it is mainly used to manage submodules and common configuration.

To create the parent project's pom.xml file, you need to set packaging to pom:

2. Create Submodules

Submodules are actual code modules, which can be ordinary Java projects, web applications, etc. Each submodule has its own pom.xml file, but it must declare the parent project:

Dependency Management in Multi-module Projects

In a multi-module project, modules can depend on each other. For example, module2 depends on module1:

Dependency Inheritance

The parent project can define common dependencies, and submodules will automatically inherit these dependencies:

The submodule only needs to declare the dependency's groupId and artifactId, without specifying the version:

Building Multi-module Projects

1. Build the Entire Project

Run the following in the parent project directory:

This will build all submodules in dependency order.

2. Build a Single Module

Enter the specific module directory and run:

Or specify the module from the parent project directory:

3. Build a Module and Its Dependencies

Best Practices for Multi-module Projects

1. Reasonable Module Partitioning

• Divide modules by function
• Divide modules by layer (e.g., dao, service, web)
• Extract common utilities into a separate module

2. Version Management

• Use the parent project to centrally manage version numbers
• Consider using Maven's versions plugin to manage version upgrades

3. Build Optimization

• Configure an appropriate build order
• Use profiles to manage builds for different environments
• Consider parallel builds to improve efficiency

4. Dependency Management

• Centrally manage common dependencies in the parent project
• Use dependencyManagement to unify versions
• Avoid circular dependencies

Common Problems and Solutions

1. Circular Dependency Issues

Problem: Module A depends on module B, and module B depends on module A.
Solution：

• Redesign the module structure and extract common code into a third module
• Use interfaces to decouple

2. Build Order Issues

Problem: Maven cannot correctly identify the dependency order between modules.
Solution：

• Explicitly declare module dependencies
• Use the reactor plugin to analyze the build order

3. Version Inconsistency Issues

Problem: Different modules use different versions of dependencies.
Solution：

• Centrally manage dependency versions in the parent project
• Use dependencyManagement

By making reasonable use of Maven multi-module project management, you can significantly improve the maintainability and build efficiency of large projects. Mastering these techniques will help you better organize and manage complex Java projects.