Maven

本文缩写（英文全称与中文含义）

缩写	英文全称／名称	中文含义
BOM	Bill Of Materials	物料清单；Maven 中用于统一依赖版本
CI	Continuous Integration	持续集成
JaCoCo	Java Code Coverage	Java 代码覆盖率工具
JDK	Java Development Kit	Java 开发工具包
JVM	Java Virtual Machine	Java 虚拟机
POM	Project Object Model	Maven 项目对象模型

Links#

https://maven.apache.org/guides/
https://maven.apache.org/guides/introduction/introduction-to-the-pom.html
https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html
https://maven.apache.org/ref/current/maven-model/maven.html
https://maven.apache.org/settings.html

1. Important Points#

Maven 是 Java 项目的 build / dependency / release 工具:
    pom.xml 描述项目、依赖、插件、构建规则
    lifecycle 定义构建阶段
    plugin 执行具体任务
    repository 存放 dependency 和 artifact

适合:
    Java / Spring Boot 项目
    多模块项目
    企业私服和 CI 发布
    需要统一依赖版本和插件版本的项目

不适合:
    需要高度自定义构建图的复杂 polyglot monorepo
    不愿意遵守固定目录和生命周期约定的项目

mental model:
    source code
        -> pom.xml
        -> Maven lifecycle phase
        -> Maven plugins run goals
        -> dependency resolved from repositories
        -> jar / war / image / published artifact

2. Core Files#

File	Purpose
`pom.xml`	项目构建入口
`settings.xml`	用户/CI 的仓库、认证、mirror、proxy 配置
`.mvn/wrapper/maven-wrapper.properties`	固定 Maven Wrapper 版本
`.mvn/jvm.config`	给 Maven 进程传 JVM 参数
`.mvn/maven.config`	给 Maven 命令提供默认参数
`toolchains.xml`	选择编译用的 JDK

3. Handbook Pages#

QuickStart:
    最小项目、Wrapper、test/package

POM / Parent / Profiles:
    pom.xml、继承、profile 激活和 effective POM

Dependency / Plugins / Quality:
    依赖治理、常用 plugin、JaCoCo、SonarQube

Spring Boot / Multi Module:
    starter parent、BOM、多模块 reactor build

Repository / Dockerfile / CI / Release / Security:
    私服、Java 镜像、流水线、发布和供应链安全

Troubleshooting:
    常见问题定位命令和修复方向

4. Standard Layout#

order-api
├── pom.xml
├── .mvn
│   ├── wrapper
│   │   └── maven-wrapper.properties
│   ├── jvm.config
│   └── maven.config
├── src
│   ├── main
│   │   ├── java
│   │   └── resources
│   └── test
│       ├── java
│       └── resources

5. Commands#

./mvnw -v
./mvnw clean test
./mvnw clean package
./mvnw clean verify
./mvnw clean install
./mvnw clean deploy

command rules:
    use ./mvnw in project and CI
    use -B in CI for batch mode
    use clean only when stale output is suspected or release build needs it
    avoid -DskipTests unless the pipeline has another test stage

6. Production Rules#

本地和 CI 使用项目 Maven Wrapper；构建参数与依赖版本可追溯，生产 Secret 不进入 POM。

dependency:
    lock versions in dependencyManagement or BOM
    avoid RELEASE / LATEST / version ranges
    use mvn dependency:tree before overriding transitive dependencies

plugin:
    define plugin versions in pluginManagement
    use maven-enforcer-plugin to enforce Java/Maven/plugin rules
    keep compiler/surefire/failsafe versions explicit

repository:
    do not put secrets in pom.xml
    use settings.xml server id for credentials
    use private proxy repository for enterprise builds

release:
    separate SNAPSHOT and release repositories
    publish from CI with a dedicated deploy identity
    record security overrides and release tags

7. Debug Commands#

./mvnw help:effective-pom
./mvnw help:effective-settings
./mvnw help:active-profiles
./mvnw dependency:tree
./mvnw dependency:tree -Dincludes=org.example:vulnerable-lib
./mvnw help:describe -Dplugin=compiler -Ddetail
./mvnw -X clean test

effective POM:
    当前项目最终生效的 POM，包括 super POM、parent、profile、pluginManagement 合并结果

dependency tree:
    依赖图，用来排查 transitive dependency、版本冲突和漏洞来源