2.4 Maven 资源过滤

文档摘要

2.4 Maven 资源过滤 2.4 Maven 资源过滤：精细化配置管理之道在软件开发生命周期中，环境差异性是一个普遍存在的挑战。从开发环境到测试环境，再到生产环境，配置参数往往各不相同。例如，数据库连接字符串、API 密钥、日志级别等，都需要根据部署环境进行调整。手动修改配置文件不仅容易出错，而且难以维护和版本控制。Maven 资源过滤机制应运而生，它提供了一种优雅且强大的解决方案，能够帮助我们根据不同的 Maven Profile 或属性，自动替换资源文件中的占位符，实现环境配置的自动化管理。 2.4.

2.4 Maven 资源过滤

2.4 Maven 资源过滤：精细化配置管理之道

在软件开发生命周期中，环境差异性是一个普遍存在的挑战。从开发环境到测试环境，再到生产环境，配置参数往往各不相同。例如，数据库连接字符串、API 密钥、日志级别等，都需要根据部署环境进行调整。手动修改配置文件不仅容易出错，而且难以维护和版本控制。Maven 资源过滤机制应运而生，它提供了一种优雅且强大的解决方案，能够帮助我们根据不同的 Maven Profile 或属性，自动替换资源文件中的占位符，实现环境配置的自动化管理。

2.4.1 资源过滤的概念与意义

概念：

Maven 资源过滤是指在 Maven 构建生命周期的 process-resources 阶段，Maven 将会扫描指定的资源目录下的文件，并根据 pom.xml 文件中的配置，使用 Maven 属性（Properties）的值替换资源文件中预定义的占位符。这个过程就像文本替换，但它是 Maven 构建过程中的自动化步骤，可以根据不同的构建环境动态生成配置文件。

意义：

环境配置自动化： 针对不同的环境（开发、测试、生产等），无需手动修改配置文件，只需通过 Maven Profile 或属性配置，即可自动生成适配环境的配置文件。
提高开发效率： 减少手动配置的繁琐和出错概率，让开发人员更专注于业务逻辑的实现。
增强可维护性： 配置信息集中管理在 pom.xml 文件和 Maven Profile 中，易于维护和版本控制，降低配置管理的复杂度。
提升部署灵活性： 可以轻松地在不同环境中部署相同的构建产物，只需在部署时选择相应的 Maven Profile 或属性即可。
安全性提升： 可以避免将敏感信息（如数据库密码）硬编码在配置文件中，而是通过 Maven 属性在构建时动态注入，提高安全性。

2.4.2 Maven 资源过滤的核心配置

资源过滤的核心配置主要在 pom.xml 文件的 <build> 标签下的 <resources> 和 <filters> 标签中进行配置。

1. <resources> 标签：定义资源目录和过滤规则

<resources> 标签用于配置项目中的资源目录，以及针对这些资源目录的过滤规则。它可以包含多个 <resource> 子标签，每个 <resource> 子标签定义一个资源目录及其过滤配置。


<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory> <!-- 资源目录 -->
            <filtering>true</filtering>           <!-- 是否开启资源过滤，默认为 false -->
            <includes>                               <!-- 包含的文件模式，可选 -->
                <include>**/*.properties</include>
                <include>**/*.xml</include>
            </includes>
            <excludes>                               <!-- 排除的文件模式，可选 -->
                <exclude>**/application.yml</exclude>
            </excludes>
        </resource>
        <resource>
            <directory>src/main/resources-other</directory> <!-- 另一个资源目录 -->
            <filtering>false</filtering>          <!-- 此目录不开启资源过滤 -->
        </resource>
    </resources>
</build>

<directory>: 指定资源目录的路径。通常相对于 pom.xml 文件所在目录。
<filtering>: 关键配置！ 设置为 true 表示对该资源目录下的文件启用资源过滤；设置为 false 则禁用资源过滤。默认为 false。
<includes>: 可选配置，用于指定需要包含的文件模式。可以使用通配符 * (匹配零个或多个字符) 和 ** (匹配零个或多个目录)。如果不配置 <includes>，则默认包含目录下的所有文件。
<excludes>: 可选配置，用于指定需要排除的文件模式。优先级高于 <includes>。

2. <filters> 标签：定义外部属性文件

<filters> 标签用于指定外部属性文件的路径。这些属性文件通常包含环境相关的配置信息。在资源过滤过程中，Maven 会加载这些属性文件，并将其中的属性值用于替换资源文件中的占位符。


<build>
    <filters>
        <filter>src/main/filters/filter.properties</filter> <!-- 外部属性文件路径 -->
        <filter>src/main/filters/dev.properties</filter>   <!-- 可以配置多个属性文件 -->
    </filters>
    <resources>
        </resources>
</build>

<filter>: 指定属性文件的路径。可以配置多个 <filter> 标签，Maven 会按照配置顺序加载这些属性文件，后加载的属性文件会覆盖前面加载的同名属性。

3. 占位符：${property.name}

资源文件中的占位符使用 ${property.name} 格式定义，其中 property.name 是 Maven 属性的名称。在资源过滤过程中，Maven 会查找与 property.name 相匹配的 Maven 属性值，并将其替换占位符。

Maven 属性的来源：

内置属性（Predefined Properties）： Maven 预定义了一系列内置属性，例如：
- project.groupId: 项目的 GroupId
- project.artifactId: 项目的 ArtifactId
- project.version: 项目的版本号
- project.name: 项目名称
- project.description: 项目描述
- basedir: 项目根目录
- java.version: JDK 版本
- maven.version: Maven 版本
- 等等。完整的内置属性列表可以参考 Maven 官方文档。

pom.xml 中 <properties> 标签定义的属性： 可以在 pom.xml 文件的 <properties> 标签中自定义属性。


<properties>
    <application.name>My Application</application.name>
    <application.version>1.0.0</application.version>
    <database.url>jdbc:mysql://localhost:3306/mydb</database.url>
</properties>

外部属性文件（通过 <filters> 标签加载）： 在外部属性文件中定义的属性。

src/main/filters/filter.properties 文件内容示例：
```
database.username=root
database.password=password123
log.level=INFO
```
命令行 -D 参数传递的属性： 可以在 Maven 命令行中使用 -Dproperty.name=property.value 参数传递属性。例如：
```
mvn clean install -Denvironment=dev -Dlog.level=DEBUG
```

Profile 中定义的属性： 可以在 Maven Profile 中定义属性，当激活 Profile 时，这些属性将被加载。


<profiles>
    <profile>
        <id>dev</id>
        <properties>
            <database.url>jdbc:h2:mem:devdb</database.url>
            <log.level>DEBUG</log.level>
        </properties>
    </profile>
    <profile>
        <id>prod</id>
        <properties>
            <database.url>jdbc:mysql://prod-db-server:3306/proddb</database.url>
            <log.level>WARN</log.level>
        </properties>
    </profile>
</profiles>

属性优先级：

当多个来源定义了同名的 Maven 属性时，其优先级顺序通常为（从高到低）：

命令行 -D 参数
Profile 中定义的属性
外部属性文件（<filters> 中配置的文件，后加载的覆盖先加载的）
pom.xml 中 <properties> 标签定义的属性
内置属性

2.4.3 代码实践：资源过滤示例

示例场景： 假设我们需要根据不同的环境（开发环境 dev 和生产环境 prod）部署应用程序，并且需要配置不同的数据库连接信息和日志级别。

项目结构：


my-app
├── pom.xml
├── src
│   └── main
│       ├── filters
│       │   ├── dev.properties
│       │   └── prod.properties
│       └── resources
│           └── config.properties

1. pom.xml 配置：


<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>my-app</artifactId>
    <version>1.0.0</version>
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
    </properties>
    <profiles>
        <profile>
            <id>dev</id>
            <properties>
                <database.url>jdbc:h2:mem:devdb</database.url>
                <database.username>sa</database.username>
                <database.password></database.password>
                <log.level>DEBUG</log.level>
            </properties>
            <activation>
                <activeByDefault>true</activeByDefault> <!-- 默认激活 dev Profile -->
            </activation>
        </profile>
        <profile>
            <id>prod</id>
            <properties>
                <database.url>jdbc:mysql://prod-db-server:3306/proddb</database.url>
                <database.username>prod_user</database.username>
                <database.password>prod_password</database.password>
                <log.level>WARN</log.level>
            </properties>
        </profile>
    </profiles>
    <build>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <filtering>true</filtering> <!-— 开启资源过滤 -->
            </resource>
        </resources>
    </build>
</project>

2. 资源文件 src/main/resources/config.properties：


application.name=My Application
application.version=${project.version}  <!-- 使用内置属性 -->
database.url=${database.url}         <!-- 使用 Profile 中定义的属性 -->
database.username=${database.username}
database.password=${database.password}
log.level=${log.level}

3. 构建和验证：

默认 dev 环境构建：


mvn clean install

构建完成后，查看 target/classes/config.properties 文件，内容应为：


application.name=My Application
application.version=1.0.0
database.url=jdbc:h2:mem:devdb
database.username=sa
database.password=
log.level=DEBUG

prod 环境构建：


mvn clean install -Pprod  <!-- 使用 -P 参数激活 prod Profile -->

构建完成后，查看 target/classes/config.properties 文件，内容应为：


application.name=My Application
application.version=1.0.0
database.url=jdbc:mysql://prod-db-server:3306/proddb
database.username=prod_user
database.password=prod_password
log.level=WARN

代码实践总结：

通过上述示例，我们可以看到 Maven 资源过滤的强大之处。我们只需在 pom.xml 文件中配置资源目录和过滤规则，并在资源文件中使用占位符，Maven 就可以根据不同的 Profile 或属性，自动替换占位符，生成适配不同环境的配置文件。

2.4.4 Mermaid 图形：资源过滤流程可视化

使用 Mermaid graph TD 图形可以更直观地展示 Maven 资源过滤的流程：

图形解释：

Maven 构建生命周期开始，进入 资源处理阶段 (process-resources)。
Maven 检查 pom.xml 中是否存在 <resources> 配置。
如果存在 <resources>，则遍历每个 <resource> 子标签。
对于每个 <resource>，遍历其指定的 <directory> 目录下的文件。
检查 <filtering> 标签是否设置为 true。
如果 <filtering> 为 true，则读取资源文件，解析文件中的占位符 ${...}，查找对应的 Maven 属性值，并将占位符替换为属性值。最后，将过滤后的文件写入到 Maven 的输出目录（通常是 target/classes）。
如果 <filtering> 为 false，则直接将资源文件复制到输出目录，不进行任何过滤操作。
处理完所有 <resource> 配置后，资源处理阶段结束，Maven 构建生命周期继续进行后续阶段。

2.4.5 资源过滤的进阶应用与注意事项

1. 自定义占位符分隔符：

默认的占位符分隔符是 ${ 和 }。如果资源文件中使用了与默认分隔符冲突的字符，可以使用 <delimiters> 标签自定义分隔符。


<resource>
    <directory>src/main/resources</directory>
    <filtering>true</filtering>
    <delimiters>
        <delimiter>@*@</delimiter> <!-— 自定义分隔符为 @*@ 和 @*@ -->
    </delimiters>
</resource>

资源文件中使用自定义分隔符：


application.name=My Application
application.version=@*@project.version@*@
database.url=@*@database.url@*@

2. ${*} 占位符的特殊用法：

${*} 占位符可以匹配任意 Maven 属性。这在某些特殊场景下可能有用，但通常不建议过度使用，因为它可能会降低代码的可读性和维护性。

3. 二进制文件过滤的注意事项：

资源过滤主要用于文本文件，例如 .properties、.xml、.txt 等。对于二进制文件（如图片、视频、字体文件等），不建议启用资源过滤，因为文本替换操作可能会破坏二进制文件的结构。

4. 性能考量：

资源过滤会增加 Maven 构建的时间，特别是当资源文件数量较多或文件较大时。在性能敏感的构建场景中，需要权衡资源过滤带来的便利性和构建时间开销。

5. 安全性考量：

虽然资源过滤可以避免将敏感信息硬编码在配置文件中，但仍然需要注意属性值的安全性。避免在属性文件中或命令行参数中直接暴露敏感信息，可以考虑使用更安全的配置管理方案，例如 Vault、Config Server 等。

6. 编码问题：

确保资源文件的编码与 Maven 项目的编码一致（通常为 UTF-8），避免出现中文乱码等问题。可以在 pom.xml 的 <properties> 中配置 project.build.sourceEncoding 属性。

2.4.6 总结

Maven 资源过滤是 Maven 构建过程中一个非常实用且强大的特性。它通过简单的配置和灵活的占位符机制，实现了环境配置的自动化管理，极大地提高了开发效率、可维护性和部署灵活性。掌握资源过滤的配置方法和应用场景，能够帮助我们更好地构建和管理复杂的 Maven 项目，应对各种环境差异性带来的挑战。在实际项目中，应根据具体需求合理地运用资源过滤，并注意其进阶应用和注意事项，以充分发挥其优势，构建更加健壮和可维护的应用程序。

作者与出处

原作者：灏天文库

来源：灏天文库

原文： https://aiknowledge.cn/collection/210-maven%E9%A1%B9%E7%9B%AE%E6%9E%84%E5%BB%BA%E4%B8%8E%E7%AE%A1%E7%90%86%E6%95%99%E7%A8%8B

整理：灏天文库整理

由灏天文库平台收录，内容或由平台用户上传，仅供学习交流