maven-dependency-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Maven Dependency Management

Maven依赖管理

Master Maven dependency management including dependency declaration, scope management, version resolution, BOMs, and dependency tree optimization.

精通Maven依赖管理，包括依赖声明、范围管理、版本解析、BOM以及依赖树优化。

Overview

概述

Maven's dependency management is a cornerstone of Java project build systems. It handles transitive dependencies, version conflicts, and provides mechanisms for controlling dependency resolution across multi-module projects.

Maven的依赖管理是Java项目构建系统的核心。它处理传递性依赖、版本冲突，并提供机制来控制多模块项目中的依赖解析。

Dependency Declaration

依赖声明

Basic Dependency

基础依赖

xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.2.0</version>
</dependency>

xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.2.0</version>
</dependency>

Dependency with Scope

带范围的依赖

xml

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>5.10.1</version>
    <scope>test</scope>
</dependency>

xml

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>5.10.1</version>
    <scope>test</scope>
</dependency>

Optional Dependencies

可选依赖

xml

<dependency>
    <groupId>com.google.code.findbugs</groupId>
    <artifactId>jsr305</artifactId>
    <version>3.0.2</version>
    <optional>true</optional>
</dependency>

xml

<dependency>
    <groupId>com.google.code.findbugs</groupId>
    <artifactId>jsr305</artifactId>
    <version>3.0.2</version>
    <optional>true</optional>
</dependency>

Dependency Scopes

依赖范围

Available Scopes

可用范围

Scope	Compile CP	Test CP	Runtime CP	Transitive
compile	Yes	Yes	Yes	Yes
provided	Yes	Yes	No	No
runtime	No	Yes	Yes	Yes
test	No	Yes	No	No
system	Yes	Yes	No	No
import	N/A	N/A	N/A	N/A

范围	编译类路径	测试类路径	运行时类路径	传递性
compile	是	是	是	是
provided	是	是	否	否
runtime	否	是	是	是
test	否	是	否	否
system	是	是	否	否
import	不适用	不适用	不适用	不适用

Scope Examples

范围示例

xml

<!-- Compile scope (default) - available everywhere -->
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.14.0</version>
</dependency>

<!-- Provided - available at compile, not packaged -->
<dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <version>6.0.0</version>
    <scope>provided</scope>
</dependency>

<!-- Runtime - only needed at runtime -->
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>42.7.1</version>
    <scope>runtime</scope>
</dependency>

<!-- Test - only for testing -->
<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-core</artifactId>
    <version>5.8.0</version>
    <scope>test</scope>
</dependency>

xml

<!-- Compile范围（默认）- 所有环境可用 -->
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.14.0</version>
</dependency>

<!-- Provided - 编译时可用，不打包 -->
<dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <version>6.0.0</version>
    <scope>provided</scope>
</dependency>

<!-- Runtime - 仅运行时需要 -->
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>42.7.1</version>
    <scope>runtime</scope>
</dependency>

<!-- Test - 仅用于测试 -->
<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-core</artifactId>
    <version>5.8.0</version>
    <scope>test</scope>
</dependency>

Version Management

版本管理

Property-Based Versions

基于属性的版本

xml

<properties>
    <spring-boot.version>3.2.0</spring-boot.version>
    <junit.version>5.10.1</junit.version>
    <jackson.version>2.16.0</jackson.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>${spring-boot.version}</version>
    </dependency>
</dependencies>

xml

<properties>
    <spring-boot.version>3.2.0</spring-boot.version>
    <junit.version>5.10.1</junit.version>
    <jackson.version>2.16.0</jackson.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>${spring-boot.version}</version>
    </dependency>
</dependencies>

Version Ranges

版本范围

xml

<!-- Exact version -->
<version>1.0.0</version>

<!-- Greater than or equal -->
<version>[1.0.0,)</version>

<!-- Less than -->
<version>(,1.0.0)</version>

<!-- Range inclusive -->
<version>[1.0.0,2.0.0]</version>

<!-- Range exclusive -->
<version>(1.0.0,2.0.0)</version>

xml

<!-- 精确版本 -->
<version>1.0.0</version>

<!-- 大于等于 -->
<version>[1.0.0,)</version>

<!-- 小于 -->
<version>(,1.0.0)</version>

<!-- 包含范围 -->
<version>[1.0.0,2.0.0]</version>

<!-- 排除范围 -->
<version>(1.0.0,2.0.0)</version>

Latest Version (Not Recommended)

Dependency Management Section

依赖管理章节

Centralizing Versions

集中版本管理

xml

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>3.2.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson</groupId>
            <artifactId>jackson-bom</artifactId>
            <version>2.16.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<!-- No version needed when declared in dependencyManagement -->
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
    </dependency>
</dependencies>

xml

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>3.2.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson</groupId>
            <artifactId>jackson-bom</artifactId>
            <version>2.16.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<!-- 在dependencyManagement中声明后无需指定版本 -->
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
    </dependency>
</dependencies>

BOM (Bill of Materials) Import

BOM（物料清单）导入

xml

<dependencyManagement>
    <dependencies>
        <!-- Spring Boot BOM -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>3.2.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>

        <!-- AWS SDK BOM -->
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.23.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>

        <!-- JUnit BOM -->
        <dependency>
            <groupId>org.junit</groupId>
            <artifactId>junit-bom</artifactId>
            <version>5.10.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

xml

<dependencyManagement>
    <dependencies>
        <!-- Spring Boot BOM -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>3.2.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>

        <!-- AWS SDK BOM -->
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.23.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>

        <!-- JUnit BOM -->
        <dependency>
            <groupId>org.junit</groupId>
            <artifactId>junit-bom</artifactId>
            <version>5.10.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Exclusions

排除依赖

Excluding Transitive Dependencies

排除传递性依赖

xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<!-- Add alternative -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jetty</artifactId>
</dependency>

xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<!-- 添加替代依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jetty</artifactId>
</dependency>

Excluding Logging Frameworks

排除日志框架

xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-log4j2</artifactId>
</dependency>

xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-log4j2</artifactId>
</dependency>

Dependency Analysis

依赖分析

View Dependency Tree

查看依赖树

bash

undefined

bash

undefined

Full dependency tree

完整依赖树

mvn dependency:tree

Filter by artifact

按构件过滤

mvn dependency:tree -Dincludes=org.slf4j

Output to file

输出到文件

mvn dependency:tree -DoutputFile=deps.txt

Verbose output showing conflict resolution

显示冲突解决的详细输出

mvn dependency:tree -Dverbose

undefined

mvn dependency:tree -Dverbose

undefined

Analyze Dependencies

分析依赖

bash

undefined

bash

undefined

Find unused declared and used undeclared dependencies

查找未使用的已声明依赖和已使用的未声明依赖

mvn dependency:analyze

Show only problems

仅显示问题

mvn dependency:analyze-only

Include test scope

包含测试范围

mvn dependency:analyze -DignoreNonCompile=false

undefined

mvn dependency:analyze -DignoreNonCompile=false

undefined

List Dependencies

列出依赖

bash

undefined

bash

undefined

List all dependencies

列出所有依赖

mvn dependency:list

List with scope

按范围列出

mvn dependency:list -DincludeScope=runtime

undefined

mvn dependency:list -DincludeScope=runtime

undefined

Conflict Resolution

冲突解决

Maven's Default Strategy

Maven默认策略

Maven uses "nearest definition wins" for version conflicts:

A -> B -> C 1.0
A -> C 2.0

Result: C 2.0 is used (nearest to root)

Maven对版本冲突使用“最近定义获胜”原则：

A -> B -> C 1.0
A -> C 2.0

结果：使用C 2.0（距离根最近）

Forcing Versions

强制指定版本

xml

<dependencyManagement>
    <dependencies>
        <!-- Force specific version across all modules -->
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>2.0.9</version>
        </dependency>
    </dependencies>
</dependencyManagement>

xml

<dependencyManagement>
    <dependencies>
        <!-- 在所有模块中强制指定特定版本 -->
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>2.0.9</version>
        </dependency>
    </dependencies>
</dependencyManagement>

Enforcer Plugin for Version Control

使用Enforcer插件进行版本控制

xml

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-enforcer-plugin</artifactId>
            <version>3.4.1</version>
            <executions>
                <execution>
                    <id>enforce</id>
                    <goals>
                        <goal>enforce</goal>
                    </goals>
                    <configuration>
                        <rules>
                            <dependencyConvergence/>
                            <requireUpperBoundDeps/>
                            <banDuplicatePomDependencyVersions/>
                        </rules>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

xml

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-enforcer-plugin</artifactId>
            <version>3.4.1</version>
            <executions>
                <execution>
                    <id>enforce</id>
                    <goals>
                        <goal>enforce</goal>
                    </goals>
                    <configuration>
                        <rules>
                            <dependencyConvergence/>
                            <requireUpperBoundDeps/>
                            <banDuplicatePomDependencyVersions/>
                        </rules>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Multi-Module Projects

多模块项目

Parent POM Dependency Management

父POM依赖管理

xml

<!-- parent/pom.xml -->
<project>
    <groupId>com.example</groupId>
    <artifactId>parent</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>com.example</groupId>
                <artifactId>common</artifactId>
                <version>${project.version}</version>
            </dependency>
        </dependencies>
    </dependencyManagement>
</project>

<!-- module/pom.xml -->
<project>
    <parent>
        <groupId>com.example</groupId>
        <artifactId>parent</artifactId>
        <version>1.0.0</version>
    </parent>

    <artifactId>module</artifactId>

    <dependencies>
        <!-- Version inherited from parent -->
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>common</artifactId>
        </dependency>
    </dependencies>
</project>

xml

<!-- parent/pom.xml -->
<project>
    <groupId>com.example</groupId>
    <artifactId>parent</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>com.example</groupId>
                <artifactId>common</artifactId>
                <version>${project.version}</version>
            </dependency>
        </dependencies>
    </dependencyManagement>
</project>

<!-- module/pom.xml -->
<project>
    <parent>
        <groupId>com.example</groupId>
        <artifactId>parent</artifactId>
        <version>1.0.0</version>
    </parent>

    <artifactId>module</artifactId>

    <dependencies>
        <!-- 版本从父POM继承 -->
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>common</artifactId>
        </dependency>
    </dependencies>
</project>

Repository Configuration

仓库配置

Central Repository

中央仓库

xml

<repositories>
    <repository>
        <id>central</id>
        <url>https://repo.maven.apache.org/maven2</url>
    </repository>
</repositories>

xml

<repositories>
    <repository>
        <id>central</id>
        <url>https://repo.maven.apache.org/maven2</url>
    </repository>
</repositories>

Private Repository

私有仓库

xml

<repositories>
    <repository>
        <id>company-repo</id>
        <url>https://nexus.company.com/repository/maven-public</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

xml

<repositories>
    <repository>
        <id>company-repo</id>
        <url>https://nexus.company.com/repository/maven-public</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

Repository in Settings.xml

Settings.xml中的仓库配置

xml

<!-- ~/.m2/settings.xml -->
<settings>
    <servers>
        <server>
            <id>company-repo</id>
            <username>${env.REPO_USER}</username>
            <password>${env.REPO_PASS}</password>
        </server>
    </servers>
</settings>

xml

<!-- ~/.m2/settings.xml -->
<settings>
    <servers>
        <server>
            <id>company-repo</id>
            <username>${env.REPO_USER}</username>
            <password>${env.REPO_PASS}</password>
        </server>
    </servers>
</settings>

Best Practices

最佳实践

Use dependencyManagement - Centralize versions in parent POMs
Import BOMs - Use well-maintained BOMs for framework dependencies
Avoid Version Ranges - Pin exact versions for reproducibility
Regular Updates - Keep dependencies current for security
Minimize Scopes - Use appropriate scopes to reduce package size
Exclude Unused - Remove unused transitive dependencies
Document Exclusions - Comment why exclusions are needed
Run dependency:analyze - Regularly check for issues
Use Enforcer Plugin - Ensure dependency convergence
Lock Versions - Use versions-maven-plugin for updates

使用dependencyManagement - 在父POM中集中管理版本
导入BOM - 针对框架依赖使用维护良好的BOM
避免版本范围 - 固定精确版本以确保可复现性
定期更新 - 保持依赖为最新版本以保障安全性
最小化范围 - 使用合适的范围来减小包体积
排除未使用依赖 - 移除未使用的传递性依赖
记录排除原因 - 为依赖排除添加注释说明原因
运行dependency:analyze - 定期检查问题
使用Enforcer插件 - 确保依赖一致性
锁定版本 - 使用versions-maven-plugin进行版本更新

Common Pitfalls

常见陷阱

Version Conflicts - Transitive dependency version mismatches
Missing Exclusions - Duplicate classes from different artifacts
Wrong Scope - Compile vs runtime vs provided confusion
Outdated Dependencies - Security vulnerabilities in old versions
Circular Dependencies - Module A depends on B depends on A
Snapshot in Production - Using SNAPSHOT versions in releases
System Scope - Hardcoded paths break portability
Optional Misuse - Marking required dependencies as optional

版本冲突 - 传递性依赖的版本不匹配
缺少排除配置 - 不同构件中的重复类
范围错误 - 混淆compile、runtime和provided范围
依赖过时 - 旧版本中的安全漏洞
循环依赖 - 模块A依赖B，B又依赖A
生产环境使用Snapshot - 在发布版本中使用SNAPSHOT版本
System范围 - 硬编码路径破坏可移植性
可选依赖误用 - 将必需依赖标记为可选

Troubleshooting

故障排除

Debug Dependency Resolution

调试依赖解析

bash

undefined

bash

undefined

Enable debug output

启用调试输出

mvn dependency:tree -X

Show conflict resolution

显示冲突解决过程

mvn dependency:tree -Dverbose=true

undefined

mvn dependency:tree -Dverbose=true

undefined

Force Re-download

强制重新下载

bash

undefined

bash

undefined

Clear local repository cache

清除本地仓库缓存

mvn dependency:purge-local-repository

Force update

强制更新

mvn -U clean install

undefined

mvn -U clean install

undefined

Check Effective POM

查看有效POM

bash

undefined

bash

undefined

See resolved dependency versions

查看已解析的依赖版本

mvn help:effective-pom

undefined

mvn help:effective-pom

undefined

When to Use This Skill

何时使用此技能

Adding new dependencies to a project
Resolving version conflicts
Setting up multi-module project dependencies
Configuring BOM imports
Optimizing dependency trees
Troubleshooting classpath issues
Upgrading dependency versions
Excluding problematic transitive dependencies

为项目添加新依赖
解决版本冲突
配置多模块项目依赖
配置BOM导入
优化依赖树
排查类路径问题
升级依赖版本
排除有问题的传递性依赖

maven-dependency-management

Original

Translation

Maven Dependency Management

Maven依赖管理

Overview

概述

Dependency Declaration

依赖声明

Basic Dependency

基础依赖

Dependency with Scope

带范围的依赖

Optional Dependencies

可选依赖

Dependency Scopes

依赖范围

Available Scopes

可用范围

Scope Examples

范围示例

Version Management

版本管理

Property-Based Versions

基于属性的版本

Version Ranges

版本范围

Latest Version (Not Recommended)

最新版本（不推荐）

Dependency Management Section

依赖管理章节

Centralizing Versions

集中版本管理

BOM (Bill of Materials) Import

BOM（物料清单）导入

Exclusions

排除依赖

Excluding Transitive Dependencies

排除传递性依赖

Excluding Logging Frameworks

排除日志框架

Dependency Analysis

依赖分析

View Dependency Tree

查看依赖树

Full dependency tree

完整依赖树

Filter by artifact

按构件过滤

Output to file

输出到文件

Verbose output showing conflict resolution

显示冲突解决的详细输出

Analyze Dependencies

分析依赖

Find unused declared and used undeclared dependencies

查找未使用的已声明依赖和已使用的未声明依赖

Show only problems

仅显示问题

Include test scope

包含测试范围

List Dependencies

列出依赖

List all dependencies

列出所有依赖

List with scope

按范围列出

Conflict Resolution

冲突解决

Maven's Default Strategy

Maven默认策略

Forcing Versions

强制指定版本

Enforcer Plugin for Version Control

使用Enforcer插件进行版本控制

Multi-Module Projects

多模块项目

Parent POM Dependency Management

父POM依赖管理

Repository Configuration