Maven 中 filtering 的使用方法

原文：Maven 中 filter 的使用

参考：Maven 中 filtering 的作用是什么？

1. filtering 的使用

Maven 提供了一种过滤机制，这种机制能够在资源文件被复制到目标目录的同时，当 filtering=true 时替换资源文件中的占位符；当 filtering=false 时不进行占位符的替换。

1.1 使用项目中属性

在资源文件中可以使用${...}来表示变量。变量的定义可以为系统属性，项目中属性，筛选的资源以及命令。

例如：在src/main/resources/hello.txt中包含以下内容：

Hello ${name}

并且 pom.xml 文件中代码如下：

<project>
  ...
  <name>My Resources Plugin Practice Project</name>
  ...
  <build>
    ...
    <resources>
      <resource>
        <directory>src/main/resources</directory>
      </resource>
      ...
    </resources>
    ...
  </build>
  ...
</project>

执行mvn resources:resources产生的target文件夹中生成的target/classes/hello.txt文件和src/main/resources/hello.txt文件有着一样的内容：

Hello ${name}

然而，在 pom 文件<resource>标签下加入<filtering>标签并且设置为true：

...
  <resource>
    <directory>src/main/resources</directory>
    <filtering>true</filtering>
  </resource>
...

执行mvn resources:resources命令后，target/classes/hello.txt文件内容发生了变化：

hello My Resources Plugin Practice Project

这是因为定义在 pom 中的<name>标签中的值替换了hello.txt文件中name变量。

1.2 使用命令行参数

此外，也可以使用-D后面加上声明的命令行的方式来指定内容，例如：mvn resources:resources -Dname="world"命令执行后，target/classes/hello.txt文件内容为：

hello world

1.2 使用自定义属性

更近一步，不仅可以使用预先定义的项目变量，也可以使用在<properties>标签下自定义变量。例如：

在src/main/resources/hello.txt文件中将文件内容更改为：

Hello ${your.name}

在 pom 中<properties>标签下定义自定义变量your.name：

<project>
  ...
  <properties>
    <your.name>world</your.name>
  </properties>
  ...
</project>

1.3 SpringBoot 框架 与 filtering 的使用

如果在 pom 文件中继承了spring-boot-starter-parent pom 文件，那么 maven-resources-plugins 的 filtering 默认的过滤符号就从${*}改为@...@（i.e. @maven.token@ instead of ${maven.token}）来防止与 Spring 中的占位符冲突。

2. filter 的使用

为了管理项目，可以将所有变量和其对应的值写入一个独立的文件，这样就不需要重写 pom 文件或者每次构建都设置值。为此可以增加一个filter：

<project>
  ...
  <name>My Resources Plugin Practice Project</name>
  ...
  <build>
    ...
    <filters>
      <filter>[a filter property]</filter>
    </filters>
    ...
  </build>
  ...
</project>

例如：新建文件my-filter-values.properties内容为：

your.name = world

在 pom 中增加 filter：

...
  <filters>
    <filter>my-filter-values.properties</filter>
  </filters>
...

注：不要过滤二进制内容的文件（如：图像）！会导致输出损坏。

有文本和二进制资源文件情况下，推荐使用两个独立的文件夹。文件夹src/main/resources中存放不需要过滤的资源文件，src/main/resources-filtered文件夹存放需要过滤的资源文件。

<project>
  ...
  <build>
    ...
    <resources>
      <resource>
        <directory>src/main/resources-filtered</directory>
        <filtering>true</filtering>
      </resource>
      ...
    </resources>
    ...
  </build>
  ...
</project>

注：正如前面所提到的，过滤图像、pdf 等二进制文件可能导致损坏的输出。为了防止这样的问题，可以配置文件扩展名不会被过滤。

3. Binary filtering

该插件将阻止二进制文件过滤，而无需为以下文件扩展名添加一些排除配置：

jpg, jpeg, gif, bmp 以及 png

如果想要添加补充文件扩展名，可以使用以下配置简单地实现

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-resources-plugin</artifactId>
        <version>3.1.0</version>
        <configuration>
          ...
          <nonFilteredFileExtensions>
            <nonFilteredFileExtension>pdf</nonFilteredFileExtension>
            <nonFilteredFileExtension>swf</nonFilteredFileExtension>
          </nonFilteredFileExtensions>
          ...
        </configuration>
      </plugin>
    </plugins>
    ...
  </build>
  ...
</project>

4. 练习

在单独文件中定义变量以及值，并且将值对 resources 文件夹下 hello.txt 文件中的变量定义符号进行替换。文件结构：

├─ src
│    └─ main
│           ├─ resources
│           │    └─ hello.txt
│           └─ resources-filtered
│                  └─ my-filter-values.properties
└─ pom.xml

hello.txt

hello ${your.name}

my-filter-values.properties

your.name = nomiracle

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project ...>
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.example</groupId>
    <artifactId>test</artifactId>
    <version>1.0</version>

    <name>My Resources Plugin Practice Project</name>

    <build>
        <filters>
            <filter>src/main/resources-filtered/my-filter-values.properties</filter>
        </filters>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <filtering>true</filtering>
            </resource>
        </resources>
    </build>

</project>

执行mvn clean resources:resources命令，生成的 target 文件夹目录结构为：

target
└─ classes
       └─ hello.txt

其中 hello.txt 文件中变量已经被替换：

hello nomiracle