Meaven

本文集文档发布于灏天文库

五、Maven 最佳实践

文档摘要

五、Maven 最佳实践 五、Maven 最佳实践 5.1 项目结构最佳实践 Maven 约定优于配置的核心思想之一体现在其标准的项目结构上。遵循 Maven 的标准目录结构，可以使得项目组织清晰、易于理解，并能充分利用 Maven 插件的默认行为，减少配置工作量。 最佳实践：遵循 Maven 标准目录结构 结构详解: 项目根目录: 项目的顶层目录，包含 、 等项目级别的文件。 : 存放项目的主要 Java 源代码。 : 存放项目的主要资源文件，如配置文件、国际化文件等。这些资源文件会被打包到最终的 JAR 或 WAR 文件的根目录下。 : 对于 Web 应用，存放 Web 应用相关的资源，如 JSP 页面、静态资源 (CSS, JS, images) 等。

五、Maven 最佳实践

五、Maven 最佳实践

5.1 项目结构最佳实践

Maven 约定优于配置的核心思想之一体现在其标准的项目结构上。遵循 Maven 的标准目录结构，可以使得项目组织清晰、易于理解，并能充分利用 Maven 插件的默认行为，减少配置工作量。

最佳实践：遵循 Maven 标准目录结构

graph TD
    A[项目根目录] --> B{src};
    A --> C{pom.xml};
    A --> D{README.md};
    B --> E{main};
    B --> F{test};
    E --> G{java};
    E --> H{resources};
    F --> I{java};
    F --> J{resources};
    E --> K{webapp};
    K --> L{WEB-INF};
    K --> M{static};
    K --> N{templates};
    L --> O{web.xml};
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#ccf,stroke:#333,stroke-width:1px
    style C fill:#ccf,stroke:#333,stroke-width:1px
    style D fill:#ccf,stroke:#333,stroke-width:1px
    style E fill:#ddf,stroke:#333,stroke-width:1px
    style F fill:#ddf,stroke:#333,stroke-width:1px
    style G fill:#eee,stroke:#333,stroke-width:1px
    style H fill:#eee,stroke:#333,stroke-width:1px
    style I fill:#eee,stroke:#333,stroke-width:1px
    style J fill:#eee,stroke:#333,stroke-width:1px
    style K fill:#ddf,stroke:#333,stroke-width:1px
    style L fill:#eee,stroke:#333,stroke-width:1px
    style M fill:#eee,stroke:#333,stroke-width:1px
    style N fill:#eee,stroke:#333,stroke-width:1px
    style O fill:#eee,stroke:#333,stroke-width:1px
​

结构详解:

  • 项目根目录: 项目的顶层目录，包含 pom.xml、README.md 等项目级别的文件。

  • src/main/java: 存放项目的主要 Java 源代码。

  • src/main/resources: 存放项目的主要资源文件，如配置文件、国际化文件等。这些资源文件会被打包到最终的 JAR 或 WAR 文件的根目录下。

  • src/main/webapp: 对于 Web 应用，存放 Web 应用相关的资源，如 JSP 页面、静态资源 (CSS, JS, images) 等。

  • src/main/webapp/WEB-INF: Web 应用的私有目录，通常包含 web.xml (Servlet 配置文件) 以及其他 Web 应用的配置文件。

  • src/main/webapp/static 或 src/main/webapp/public: 存放静态资源文件，如 CSS、JavaScript、图片等。

  • src/main/webapp/templates 或 src/main/webapp/views: 存放视图模板文件，例如 Thymeleaf 或 FreeMarker 模板。

  • src/test/java: 存放单元测试和集成测试的 Java 源代码。

  • src/test/resources: 存放测试相关的资源文件。

  • pom.xml: Maven 项目的核心配置文件，定义项目的依赖、插件、构建配置等。

  • README.md: 项目的说明文档，通常使用 Markdown 格式编写，用于介绍项目的功能、使用方法、构建步骤等。

代码实践:

在创建 Maven 项目时，使用 Maven 的 Archetype 生成项目骨架，例如使用 maven-archetype-quickstart 或 maven-archetype-webapp 等，Maven 会自动创建符合标准目录结构的项目。

mvn archetype:generate -DgroupId=com.example -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
​

优势:

  • 清晰的项目组织: 结构清晰，易于导航和理解项目组成。

  • 默认配置: 大部分 Maven 插件默认会按照标准结构查找资源和代码，减少配置。

  • 团队协作: 统一的项目结构方便团队成员快速上手和协作。

  • 可维护性: 结构化的项目更易于维护和扩展。

5.2 依赖管理最佳实践

Maven 最强大的功能之一就是其优秀的依赖管理系统。合理的依赖管理能够避免依赖冲突、简化依赖配置、提升构建效率。

最佳实践 1：显式声明依赖版本

不要依赖 Maven 的传递性依赖版本仲裁机制，而应该在 pom.xml 中显式声明所有直接依赖的版本。

代码实践:

<dependencies>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
        <version>5.3.20</version> <!- 显式声明版本 -->
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.13.3</version> <!- 显式声明版本 -->
    </dependency>
    </dependencies>
​

详解:

  • 避免版本冲突: 显式声明版本可以避免由于传递性依赖版本仲裁导致的版本冲突问题，确保依赖版本可控。

  • 可维护性: 清晰的版本声明使得依赖关系更加明确，方便维护和升级依赖。

  • 稳定性: 避免依赖版本意外升级导致项目不稳定。

最佳实践 2：使用 Dependency Management 管理依赖版本

对于大型项目或多模块项目，可以使用 <dependencyManagement> 统一管理依赖版本，在子模块中引用依赖时可以省略版本号，提高版本统一性和可维护性。

代码实践 (父 POM):

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-context</artifactId>
            <version>5.3.20</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.13.3</version>
        </dependency>
    </dependencies>
</dependencyManagement>
​

代码实践 (子模块 POM):

<dependencies>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId> <!- 省略版本号，继承父 POM 的版本管理 -->
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId> <!- 省略版本号，继承父 POM 的版本管理 -->
    </dependency>
</dependencies>
​

详解:

  • 版本统一性: 确保整个项目或多个模块使用统一的依赖版本。

  • 简化依赖配置: 子模块无需重复声明版本号，简化 pom.xml 文件。

  • 易于升级: 升级依赖版本只需在父 POM 的 <dependencyManagement> 中修改，所有子模块自动同步。

最佳实践 3：合理使用 Dependency Scope (依赖范围)

根据依赖的使用场景，选择合适的 dependency scope，避免引入不必要的依赖到最终的构建产物中，减小 JAR/WAR 包大小，并避免运行时冲突。

Dependency Scope 类型:

  • compile (默认): 编译、测试、运行都有效。

  • provided: 编译和测试有效，运行时由容器提供，例如 Servlet API。

  • runtime: 编译和测试时不需要，运行时需要，例如 JDBC 驱动。

  • test: 只在测试时有效，例如 JUnit, Mockito。

  • system: 类似 provided，但需要显式指定系统路径，不推荐使用，容易造成环境依赖。

  • import: 只能在 <dependencyManagement> 中使用，用于导入其他 POM 的 <dependencyManagement> 配置，实现依赖版本管理继承。

代码实践:

<dependencies>
    <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>javax.servlet-api</artifactId>
        <version>4.0.1</version>
        <scope>provided</scope> <!- Servlet API 由 Web 服务器提供 -->
    </dependency>
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.13.2</version>
        <scope>test</scope> <!- JUnit 只用于测试 -->
    </dependency>
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <version>8.0.29</version>
        <scope>runtime</scope> <!- JDBC 驱动运行时需要 -->
    </dependency>
</dependencies>
​

详解:

  • 资源优化: 避免将测试依赖、容器提供的依赖等打包到最终产物中，减小包大小。

  • 避免冲突: provided 范围的依赖避免与运行时环境提供的依赖冲突。

  • 清晰的依赖关系: 通过 scope 可以清晰地表达依赖的使用场景。

最佳实践 4：使用 Bill of Materials (BOM) 管理一组相关依赖的版本

对于一组相关的依赖 (例如 Spring Boot Starter 或 Spring Cloud Dependencies)，使用 BOM 可以简化版本管理，并确保这些相关依赖版本兼容。

代码实践 (引入 Spring Boot BOM):

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>2.7.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId> <!- 版本由 BOM 管理 -->
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId> <!- 版本由 BOM 管理 -->
    </dependency>
</dependencies>
​

详解:

  • 版本兼容性: BOM 确保一组相关依赖的版本兼容，避免版本冲突问题。

  • 简化配置: 引入 BOM 后，可以省略 BOM 管理的依赖的版本号。

  • 易于升级: 升级一组相关依赖只需升级 BOM 的版本。

最佳实践 5：定期检查和更新依赖

定期检查项目依赖，更新到最新的稳定版本，可以修复安全漏洞、提升性能、使用新特性。可以使用 Maven 插件如 versions-maven-plugin 来辅助依赖版本管理和更新。

代码实践 (使用 versions-maven-plugin 检查依赖更新):

mvn versions:display-dependency-updates
mvn versions:display-plugin-updates
​

详解:

  • 安全性和稳定性: 及时更新依赖可以修复已知的安全漏洞和 bug。

  • 性能提升: 新版本依赖通常会包含性能优化。

  • 新特性: 使用新版本依赖可以利用新特性提升开发效率。

5.3 插件管理最佳实践

Maven 插件是 Maven 功能扩展的核心机制。合理配置和使用插件，可以实现自动化构建流程的各个环节，例如编译、测试、打包、部署等。

最佳实践 1：显式声明插件版本

与依赖管理类似，为了保证构建的稳定性和可重复性，应该显式声明 Maven 插件的版本。

代码实践:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.10.1</version> <!- 显式声明插件版本 -->
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>2.22.2</version> <!- 显式声明插件版本 -->
        </plugin>
    </plugins>
</build>
​

详解:

  • 构建稳定性: 避免插件版本自动升级导致构建行为不一致或构建失败。

  • 可重复性: 确保在不同环境或不同时间构建时，插件版本一致，构建结果可重复。

  • 可维护性: 清晰的插件版本声明方便维护和升级插件。

最佳实践 2：使用 Plugin Management 管理插件版本

与依赖管理类似，可以使用 <pluginManagement> 统一管理插件版本，在子模块中引用插件时可以省略版本号，提高版本统一性和可维护性。

代码实践 (父 POM):

<pluginManagement>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.10.1</version>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>2.22.2</version>
        </plugin>
    </plugins>
</pluginManagement>
​

代码实践 (子模块 POM):

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId> <!- 省略版本号，继承父 POM 的版本管理 -->
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId> <!- 省略版本号，继承父 POM 的版本管理 -->
        </plugin>
    </plugins>
</build>
​

详解:

  • 版本统一性: 确保整个项目或多个模块使用统一的插件版本。

  • 简化配置: 子模块无需重复声明版本号，简化 pom.xml 文件。

  • 易于升级: 升级插件版本只需在父 POM 的 <pluginManagement> 中修改，所有子模块自动同步。

最佳实践 3：使用插件前缀 (Plugin Prefix)

为了简化插件配置，可以使用插件前缀来代替完整的 groupId:artifactId。Maven 已经预定义了一些常用的插件前缀，例如 compiler 代表 org.apache.maven.plugins:maven-compiler-plugin，surefire 代表 org.apache.maven.plugins:maven-surefire-plugin 等。

代码实践:

<build>
    <plugins>
        <plugin>
            <artifactId>maven-compiler-plugin</artifactId> <!- 使用插件前缀 -->
            <version>3.10.1</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
        </plugin>
        <plugin>
            <artifactId>maven-surefire-plugin</artifactId> <!- 使用插件前缀 -->
            <version>2.22.2</version>
        </plugin>
    </plugins>
</build>
​

详解:

  • 简化配置: 减少 pom.xml 文件中的冗余信息，提高可读性。

  • 约定优于配置: 利用 Maven 的约定，减少配置工作量。

最佳实践 4：配置插件目标 (Goals) 和生命周期绑定 (Lifecycle Binding)

合理配置插件的目标和生命周期绑定，可以实现自动化构建流程的定制化。可以将插件目标绑定到 Maven 的生命周期阶段，在执行特定生命周期阶段时自动执行插件目标。

代码实践 (将 maven-assembly-plugin 的 single 目标绑定到 package 阶段):

<build>
    <plugins>
        <plugin>
            <artifactId>maven-assembly-plugin</artifactId>
            <version>3.3.0</version>
            <executions>
                <execution>
                    <id>make-assembly</id> <!- execution ID -->
                    <phase>package</phase> <!- 绑定到 package 阶段 -->
                    <goals>
                        <goal>single</goal> <!- 执行 single 目标 -->
                    </goals>
                    <configuration>
                        <descriptorRefs>
                            <descriptorRef>jar-with-dependencies</descriptorRef>
                        </descriptorRefs>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
​

详解:

  • 自动化构建流程: 将插件目标绑定到生命周期阶段，实现自动化构建流程。

  • 定制化构建: 根据项目需求，配置不同的插件目标和生命周期绑定，实现定制化的构建流程。

  • 可扩展性: 通过插件扩展 Maven 的构建功能。

5.4 构建 Profile 最佳实践

Maven Profile 允许根据不同的环境 (例如开发、测试、生产) 或构建目标 (例如本地构建、发布构建) 激活不同的配置，实现构建的灵活性和可移植性。

最佳实践 1：使用 Profile 区分环境配置

使用 Profile 来管理不同环境的配置，例如数据库连接信息、API 地址、日志级别等。避免硬编码环境相关的配置在代码或主配置文件中。

代码实践 (在 pom.xml 中定义不同环境的 Profile):

<profiles>
    <profile>
        <id>dev</id> <!- 开发环境 Profile -->
        <activation>
            <activeByDefault>true</activeByDefault> <!- 默认激活 -->
        </activation>
        <properties>
            <db.url>jdbc:mysql://localhost:3306/dev_db</db.url>
            <api.url>http://localhost:8080/dev-api</api.url>
            <log.level>DEBUG</log.level>
        </properties>
    </profile>
    <profile>
        <id>prod</id> <!- 生产环境 Profile -->
        <properties>
            <db.url>jdbc:mysql://prod-db-server:3306/prod_db</db.url>
            <api.url>http://api.example.com</api.url>
            <log.level>INFO</log.level>
        </properties>
    </profile>
</profiles>
<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering> <!- 开启资源文件过滤 -->
        </resource>
    </resources>
</build>
​

代码实践 (在 src/main/resources/application.properties 中使用 Profile 属性):

spring.datasource.url=${db.url}
api.base.url=${api.url}
logging.level.root=${log.level}
​

详解:

  • 环境隔离: 不同环境使用不同的配置，避免环境配置互相干扰。

  • 可移植性: 同一份代码可以在不同环境部署，只需切换 Profile。

  • 灵活性: 根据需要激活不同的 Profile，实现灵活的构建配置。

最佳实践 2：使用不同的 Profile 激活方式

Maven Profile 提供了多种激活方式，可以根据不同的场景选择合适的激活方式。

Profile 激活方式:

  • 默认激活 (<activeByDefault>): Profile 默认激活。

  • 基于环境属性 (<property>): 根据 Maven 属性的值激活 Profile。

  • 基于操作系统 (<os>): 根据操作系统类型激活 Profile。

  • 基于文件存在性 (<file>): 根据文件是否存在激活 Profile。

  • 命令行显式激活 (-P 参数): 在命令行使用 -P 参数显式激活 Profile。

Mermaid 图示例: Profile 激活方式

详解:

  • 灵活性: 多种激活方式满足不同场景的需求。

  • 自动化激活: 基于条件自动激活 Profile，减少手动操作。

  • 手动控制: 通过命令行显式激活 Profile，方便手动切换环境。

最佳实践 3：避免 Profile 配置过于复杂

Profile 的主要目的是管理环境差异配置，不应该在 Profile 中配置过于复杂的构建逻辑或依赖管理。复杂的构建逻辑应该通过插件或脚本来实现。

详解:

  • 维护性: 过于复杂的 Profile 配置会降低 pom.xml 的可读性和可维护性。

  • 职责分离: Profile 专注于环境配置，构建逻辑和依赖管理应该由插件和 Maven 的其他特性来管理。

  • 避免滥用: 不要将 Profile 当作万能的配置工具，应该合理使用 Profile 的功能。

5.5 仓库管理最佳实践

Maven 仓库是存放 Maven 项目构件 (JAR, WAR, POM 等) 的地方。合理的仓库管理对于项目构建的效率、依赖的可靠性以及团队协作至关重要。

最佳实践 1：配置中央仓库镜像

由于 Maven 中央仓库位于国外，国内访问速度较慢。配置国内的中央仓库镜像可以显著提升依赖下载速度。

代码实践 (在 settings.xml 中配置阿里云 Maven 镜像):

<mirrors>
    <mirror>
        <id>aliyunmaven</id>
        <mirrorOf>central</mirrorOf>
        <name>阿里云公共仓库</name>
        <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
</mirrors>
​

详解:

  • 提升下载速度: 镜像服务器通常位于国内，访问速度更快。

  • 稳定性: 镜像服务器提供缓存，可以提高依赖下载的稳定性。

  • 节省带宽: 减少对国外服务器的访问，节省带宽资源。

最佳实践 2：搭建私有仓库

对于企业内部项目，搭建私有仓库 (例如 Nexus, Artifactory, JFrog) 可以管理企业内部的构件，并提供更精细的权限控制和仓库管理功能。

Mermaid 图示例: Maven 仓库层次结构

详解:

  • 内部构件管理: 管理企业内部开发的构件，例如内部组件、SDK 等。

  • 权限控制: 控制不同团队或用户对仓库的访问权限。

  • 加速内部依赖下载: 内部构件从私有仓库下载速度更快。

  • 构件安全: 私有仓库可以对上传的构件进行安全扫描和审核。

最佳实践 3：合理配置仓库优先级

Maven 仓库的搜索顺序是：本地仓库 -> 私有仓库 -> 中央仓库镜像 -> 中央仓库。可以根据项目需求和网络环境，合理配置仓库优先级。例如，对于内部项目，可以将私有仓库的优先级设置为高于中央仓库镜像。

代码实践 (在 pom.xml 或 settings.xml 中配置仓库):

<repositories>
    <repository>
        <id>my-private-repo</id>
        <url>http://nexus.example.com/repository/maven-public/</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>
​

详解:

  • 优先级控制: 根据需求调整仓库搜索顺序，优化依赖查找效率。

  • 网络优化: 在网络环境不佳的情况下，可以优先使用本地仓库或私有仓库。

  • 构件来源控制: 限制构件的来源，例如只允许从私有仓库下载内部构件。

5.6 版本控制最佳实践

良好的版本控制对于 Maven 项目的版本管理、发布管理和团队协作至关重要。

最佳实践 1：使用语义化版本 (Semantic Versioning)

使用语义化版本 (SemVer) 来管理项目版本号，清晰地表达版本迭代的含义，方便用户和团队理解版本变化。

语义化版本格式: 主版本号.次版本号.修订号 (MAJOR.MINOR.PATCH)

  • 主版本号 (MAJOR): 当进行不兼容的 API 修改时，递增主版本号。

  • 次版本号 (MINOR): 当新增功能时，递增次版本号，同时主版本号归零。

  • 修订号 (PATCH): 当修复 Bug 时，递增修订号，同时主版本号和次版本号归零。

代码实践 (在 pom.xml 中设置语义化版本号):

<groupId>com.example</groupId>
<artifactId>my-app</artifactId>
<version>1.2.3</version> <!- 语义化版本号 -->
<packaging>jar</packaging>
​

详解:

  • 清晰的版本含义: 通过版本号可以快速了解版本迭代类型 (兼容性修改、新增功能、Bug 修复)。

  • 用户友好: 方便用户根据版本号判断是否需要升级或进行兼容性适配。

  • 自动化发布: 语义化版本可以用于自动化发布流程，例如根据版本号自动发布到不同的仓库或环境。

最佳实践 2：使用版本控制系统 (VCS) 管理 pom.xml 和源代码

将 pom.xml 文件和源代码纳入版本控制系统 (例如 Git)，可以追溯版本变更、方便团队协作、实现版本回滚等。

详解:

  • 版本追溯: 可以追溯 pom.xml 和源代码的变更历史，方便问题排查和版本回滚。

  • 团队协作: 版本控制系统支持多人协作开发，管理代码分支和合并。

  • 发布管理: 版本控制系统可以与 Maven 发布插件集成，实现自动化发布流程。

最佳实践 3：使用 Maven Release Plugin 进行版本发布

使用 maven-release-plugin 插件可以自动化 Maven 项目的版本发布流程，包括版本号升级、代码打标签、发布到仓库等。

代码实践 (使用 maven-release-plugin 进行发布):

mvn release:prepare  <!- 准备发布，包括版本号升级、代码打标签 -->
mvn release:perform <!- 执行发布，将构件发布到仓库 -->
​

详解:

  • 自动化发布流程: 简化版本发布流程，减少手动操作。
发布者: 作者: 转发
评论区 (0)
U
0/500