Mastering Maven: A Complete Guide to Java Build Management

What Is Maven (Everyday Analogy)

Before Maven, Java projects required manually downloading JARs (e.g., MySQL driver, Spring, MyBatis, logging) and copying them into a lib folder, leading to version conflicts and cumbersome sharing. Maven acts as a "housekeeper" and repository manager, handling two major tasks: managing JAR dependencies and managing the full build lifecycle (compile, test, package, install, deploy).

Maven uses a central repository; adding a single line in pom.xml triggers automatic download of the required JARs to a local repository.

The core file is pom.xml (Project Object Model), which stores all configuration.

Maven Core Concepts (Plain Language)

POM ( pom.xml ) : the project description file that defines name, version, dependencies, and packaging. Without a POM, a project is not a Maven project.

Coordinates GAV (GroupId, ArtifactId, Version) : the unique identifier of a JAR, similar to an ID card. groupId: organization or company, e.g.,

org.springframework

artifactId

: project name version: version number, e.g., 5.3.20 Repository (Three Types)

Local repository – a folder on the developer’s machine where downloaded JARs are cached.

Central repository – the public online repository containing virtually all open‑source JARs.

Private repository (Nexus) – an internal company repository that can proxy the central repository and host proprietary JARs.

Lifecycle (Three Sets, Most Important) The default lifecycle runs the steps: validate → compile → test → package → install → deploy . Executing a later command automatically runs the preceding steps. For example, mvn install compiles, runs tests, packages, and installs the artifact to the local repository.

Plugin : The lifecycle defines *when* something happens; plugins perform the actual work (compilation, packaging, testing, etc.). Maven provides default plugins, and custom plugins can be configured when needed.

Scope : Controls when a dependency is active. compile (default): needed for compilation and runtime. test: only for unit tests. provided: required for compilation but supplied by the runtime environment (e.g., servlet-api). runtime: not needed for compilation, only at runtime (e.g., MySQL driver).

Transitive Dependencies & Exclusions : Adding dependency A automatically pulls in its dependencies (B). Version conflicts can be resolved with <exclusions> to exclude unwanted artifacts.

Inheritance & Aggregation (Multi‑module Projects)

Inheritance: A parent POM defines common versions; child modules inherit them, avoiding repetition (e.g., Spring Boot parent).

Aggregation: A parent project aggregates multiple sub‑modules, enabling a single command to build all modules.

Complete Basic Operations

Install and Configure Maven

Download the Maven archive and extract it.

Set MAVEN_HOME and add bin to PATH.

Edit conf/settings.xml to (a) specify the local repository path and (b) configure the Alibaba Cloud mirror for faster downloads in China.

Run mvn -v to verify the installation.

Common Maven Commands mvn clean – removes the target directory. mvn compile – compiles source files to target/classes. mvn test – runs unit tests. mvn package – creates a JAR/WAR in target. mvn install – installs the artifact to the local repository. mvn deploy – uploads the artifact to a private repository.

Typical combo: mvn clean package – clean then package.

Using Maven in IntelliJ IDEA

Create a Maven project; IDEA generates pom.xml and the standard directory layout.

Directory layout:

src
├─main
│  ├─java      # source code
│  └─resources  # configuration files (yml, properties)
└─test
   └─java      # test code
target          # compiled classes and packaged JAR

Add dependencies in pom.xml; IDEA automatically downloads them.

Use the Maven tool window to run clean, compile, package, install, etc.

Maven Application Scenarios

Standalone Java projects – manage third‑party JARs and build.

SSM / Spring Boot web projects – most common; starters are Maven‑based.

Multi‑module distributed projects (e.g., Dubbo) – parent aggregates sub‑modules for one‑click builds.

Internal shared libraries – build, install, and deploy to a private repository for reuse.

CI/CD pipelines (Jenkins) – servers execute Maven commands for automated builds and deployments.

Advantages & Disadvantages of Maven

Pros

Unified JAR management; no manual copying.

Transitive dependencies automatically pull required artifacts.

Complete build lifecycle (compile, test, package, install) covered by simple commands.

Inheritance and aggregation simplify multi‑module version control.

Private repository support enables internal component sharing.

Seamless integration with IDEs (IDEA) and CI tools (Jenkins).

Cons

Steep learning curve; many concepts (POM, scopes, lifecycles) can overwhelm beginners.

Dependency conflicts are common; version clashes may cause NoClassDefFoundError.

Access to the global central repository can be slow; a mirror is often required.

Large transitive dependency trees increase artifact size.

Extensive pom.xml configurations can become unwieldy and hard to read.

Three Typical Project Cases

Case 1: Simple Standalone Java Tool

Scenario: A console program that reads Excel files and processes data. Needs Apache POI for Excel and JUnit for tests.

Steps:

<dependencies>
  <!-- Excel handling -->
  <dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi</artifactId>
    <version>4.1.2</version>
  </dependency>
  <!-- Unit test, scope=test – not packaged -->
  <dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.13.2</version>
    <scope>test</scope>
  </dependency>
</dependencies>

Write code under src/main/java and tests under src/test/java. Run mvn clean compile, then mvn test, and finally mvn clean package to produce a runnable JAR. Maven automatically resolves POI’s transitive dependencies.

Case 2: Spring Boot Web Application

Scenario: Backend management system using Spring Boot, MyBatis‑Plus, and MySQL.

Key point: The project inherits from spring-boot-starter-parent, which centralizes version management.

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>2.7.15</version>
  <relativePath/>
</parent>
<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
  </dependency>
  <dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <scope>runtime</scope>
  </dependency>
</dependencies>

Develop controllers, services, and mappers, configure the database in application.yml, then run mvn clean package to obtain an executable JAR and start it with java -jar demo.jar. The parent POM eliminates the need to specify individual versions.

Case 3: Maven Multi‑module Dubbo Project

Scenario: A distributed Dubbo system split into three modules: demo-api (shared interfaces), demo-provider (service implementation), and demo-consumer (client).

Structure:

demo-parent (packaging=pom) – aggregates sub‑modules
├─demo-api      – interface module
├─demo-provider – service provider
└─demo-consumer – service consumer

Steps:

Create the parent POM with <modules> listing the three sub‑modules.

Create demo-api, write interfaces, then run mvn install to publish it to the local repository.

Develop demo-provider and declare a dependency on demo-api.

Develop demo-consumer and also depend on demo-api.

From the parent directory execute mvn clean install. Maven compiles modules in dependency order (api → provider → consumer) and installs each artifact locally.

In a real team, demo-api would be mvn deploy ed to a private repository; provider and consumer would fetch it from there, avoiding code duplication.

Benefits: Single source of interface definitions, unified version control, and streamlined builds.

Common Maven Pitfalls (Brief Summary)

Jar download failures – configure a mirror (e.g., Alibaba Cloud) or clear the local cache.

Dependency conflicts – use mvn dependency:tree to view the tree and apply <exclusions> as needed.

Incorrect scope – may cause unwanted JARs in the final package or missing JARs at runtime.

Multi‑module issues – ensure each sub‑module is installed before dependent modules are built.

IDEA indexing problems – after modifying pom.xml, refresh the Maven panel to reload dependencies.