Maven核心插件之maven-resources-plugin

前言

  Maven 插件是 Maven 构建系统的重要组成部分，它们为 Maven 提供了丰富的功能和扩展能力，使得 Maven 不仅是一个构建工具，更是一个强大的项目管理平台。在 Maven 项目中，插件的使用通常通过配置 pom.xml 文件来完成。每个插件都有自己的配置参数，通过配置这些参数，可以控制插件的行为。插件为 Maven 项目提供了强大的扩展能力，使得开发者能够自定义项目的构建过程，实现自动化构建、代码生成、代码检查等多种功能。

一、插件概述

1.1 插件简介

  在项目当中进行编译的时候，默认是不会对某些文件进行编译的，例如在java文件夹下的mybatis当中的 xml 文件，还有在resources文件夹当中有时候会存储一些资源文件，默认也是不进行编译的。注意，这里的不进行编译指的是不会编译到target文件夹当中，并且打包也是。在正常开发项目的时候，有时候获取资源是获取的编译后的路径地址，在编译后的路径找不到文件（target文件夹），就是这个原因。这时候就需要用到 maven-resources-plugin 插件，在pom.xml添加，告诉maven这些文件也需要编译，并且打包的时候需要打包进去。maven-resources-plugin 是 Maven 中一个非常重要的插件，用于处理项目的资源文件。资源文件通常包括配置文件、静态文件（如 HTML、CSS、JavaScript）、图像等。这个插件提供了多种功能，如复制资源文件、过滤资源文件、设置资源文件的输出目录等。

官网介绍：https://maven.apache.org/plugins/maven-resources-plugin/

  为了使项目结构更为清晰，Maven 区别对待Java代码文件和资源文件，maven-compiler-plugin 用来编译Java代码，maven-resources-plugin 则用来处理资源文件。默认的主资源文件目录是 src/main/resources，很多用户会需要添加额外的资源文件目录，这个时候就可以通过配置 maven-resources-plugin 来实现。

  此外，资源文件过滤也是Maven的一大特性，你可以在资源文件中使用 ${propertyName} 形式的Maven属性，然后配置 maven-resources-plugin 开启对资源文件的过滤，之后就可以针对不同环境通过命令行或者Profile传入属性的值，以实现更为灵活的构建。

  注意，这个插件只要我们编译代码就会用到该插件，就算我们项目没有声明该插件也照样会使用到，如下图所示：

1.2 使用方式

  在pom.xml文件中，插件配置通常位于 <build> 标签下的 <plugins> 标签内，每个插件配置由 <plugin> 标签包裹，并包含以下基本信息：

配置项	简要说明
groupId	插件所属的组织ID。
artifactId	插件的构件ID，用于唯一标识插件。
version	插件的版本号。
configuration	插件的配置参数，用于控制插件的行为。

  以下是一个简单的Maven插件配置示例，展示了如何使用 Maven Resources Plugin 插件来配置为使用 Java 1.8 版本编译源代码：

<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-resources-plugin</artifactId><configuration><encoding>UTF-8</encoding></configuration>
</plugin>

【说明】在这个示例中，maven-resources-plugin 被配置为使用 UTF-8 编码处理资源文件。

二、插件常用配置

2.1 字符集编码

  既然插件是copy资源文件那必然涉及到文件的编码，可以选择的编码有ASCII、UTF-8 或者 UTF-16，设置编码的方式有两种：

  第一种：使用properties标签声明 project.build.sourceEncoding，声明好后，插件当中的 <encoding> 标签会取这个编码，如下所示：

<properties><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding></properties>

  第二种通过插件配置：

<build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-resources-plugin</artifactId><configuration><encoding>UTF-8</encoding></configuration></plugin></plugins>
</build>

注意：只要官网当中提到了可以使用${…}的方式配置，那么我们就可以不声明插件，可以直接在properties当中配置。

2.2 resources 配置结构

  resources 标签其实就是 maven-resources-plugin 的配置，主要用来配置资源目录的，如下所示：

<build><resources><resource><directory>${project.basedir}/src/main/resources</directory><filtering></filtering><includes><include></include></includes><excludes><exclude></exclude></excludes></resource><!--假如资源目录有多个可以在这里声明--><resource></resource></resources>
</build>

标签	简要说明
directory	指定资源文件目录，这里是 src/main/resources。
includes	指定资源文件目录中，仅包含哪些文件被打包，例如 **/*.properties 表示所有子目录下的 .properties 文件。
excludes	指定资源文件目录中，仅哪些文件不被打包
filtering	一个boolea值，默认值为false，指定打包时的配置文件中是否进行变量替换

2.3 resources 默认配置

  所谓默认配置就是在项目当中不设置resources标签，默认生效的。

2.3.1 maven超级pom默认配置

  maven 项目默认继承了一个父pom.xml，配置主要包含了如下，其中一些配置就是对 maven-resources-plugin 插件的配置，如下所示：

<build><directory>${project.basedir}/target</directory><!-- 主资源默认输出的位置 --><outputDirectory>${project.build.directory}/classes</outputDirectory><!--打出来的默认jar、war包名--><finalName>${project.artifactId}-${project.version}</finalName><!-- 测试资源默认输出的位置 --><testOutputDirectory>${project.build.directory}/test-classes</testOutputDirectory><!--默认的主源代码地址--><sourceDirectory>${project.basedir}/src/main/java</sourceDirectory><scriptSourceDirectory>${project.basedir}/src/main/scripts</scriptSourceDirectory><!--默认的测试源代码地址--><testSourceDirectory>${project.basedir}/src/test/java</testSourceDirectory><!--默认的主源代码当中的资源文件地址--><resources><resource><directory>${project.basedir}/src/main/resources</directory></resource></resources><!--默认的测试源代码当中的资源文件地址--><testResources><testResource><directory>${project.basedir}/src/test/resources</directory></testResource></testResources>
</build>

2.3.2 Spring Boot对resources插件的默认配置

  Spring Boot 项目一般我们都会继承一个 spring-boot-starter-parent，而其 pom 当中就默认给我们做了一些 resources 插件的配置，那么我们的的项目 resources 默认配置如下，其会将maven默认配置给替换掉，如下所示：

<resources><resource><directory>${basedir}/src/main/resources</directory><filtering>true</filtering><includes><include>**/application*.yml</include><include>**/application*.yaml</include><include>**/application*.properties</include></includes></resource><resource><directory>${basedir}/src/main/resources</directory><excludes><exclude>**/application*.yml</exclude><exclude>**/application*.yaml</exclude><exclude>**/application*.properties</exclude></excludes></resource>
</resources>

这里需要注意一点：假如我们项目当中去声明resources标签，那么他会将继承的父类当中的resources标签给替换掉，说白了就是重写的会覆盖继承的。

三、resources下的标签详解

3.1、filtering 的使用

  若是要将src/main/java路径下.fxml文件结尾的编译打包进去，当有两个同类型文件，只想打包进去一个文件，可以在include标签当中指定文件名称。

<build><resources><resource><directory>src/main/java</directory><filtering>true</filtering><includes><include>**/*.fxml</include></includes></resource><resource><directory>src/main/resources</directory><filtering>true</filtering></resource></resources>
</build>

  filtering 默认为 false，作用是是否允许指定任意文件可以以 ${...} or @...@ 的语法来提取pom.xml当中的配置。假设在 src/main/resources 目录下有一个application.properties 文件，内容如下：

userName=${userName}
userName=@userName@

  这时候可以在pom.xml文件中定义变量的取值：

<propweties><userName>zhangsan</userName>
</propweties>

  如果需要对配置文件中变量进行替换实际值，就需要开启 <filtering>，该值设置为true。这里使用了includes标签指定了文件，也就是允许application.properties文件读取变量值。

<build><resources><resource><directory>src/main/resources</directory><filtering>true</filtering><includes><include>application.properties</include></includes></resource></resources>
</build>

  执行mvn clean package -DskipTests 打包，然后打开target/classes目录当中查看资源文件，会发现使用 @...@取值成功了，而${...} 没有成功。这是因为项目继承了spring-boot-starter-parent，而 Spring Boot 的xml当中有一个这个标签 <resource.delimiter> 将取值语法改为了 @...@，因为spring害怕和其他语法有冲突，所以使用了这个配置。

  我们也可以通过手动声明来覆盖springboot父类的配置，这样便可以通过${...}语法进行取值了。

<properties><resource.delimiter>${*}</resource.delimiter>
</properties>

  这里需要特别注意的是，没有必要使用变量取值的，千万不要将filtering设置为true，针对于这一点官网也明确指出二进制文件一定不要过滤。例如在resources文件夹当中存放有Excel模板，导出模板后发现是乱码的，但是通过源代码打开Excel就是正常的，原因就是将文件给进行过滤了，导致编译过后target当中的Excel都是乱码的。解决方案就是在编译时不进行过滤，但也要被放到resource目录下。修改配置如下：

3.2 include和excludes的使用

关于这个标签官网也有叙述：https://maven.apache.org/plugins/maven-resources-plugin/examples/include-exclude.html

  其实实际开发当中很多人对这都是不理解，配置起来也是一顿乱配置。来看下这个图，多看几篇，一旦理解了，就彻底懂了！

**/代表的是根目录，/src/main/resources 和 /src/main/java 这两个都属于根目录，一个*可以代表一个占位符，可以是多个字母组成的。

四、总结

  maven-resources-plugin 是一个功能强大且灵活的插件，用于处理项目中的资源文件。通过合理配置，可以实现资源的复制、过滤、设置输出目录等功能。了解并掌握这些配置，可以大大提高项目的灵活性和可维护性。

  Apache Maven 插件是 Maven 的核心组成部分，它们扩展了 Maven 的功能，使得 Maven 能够完成各种复杂的构建任务。了解和使用 Maven 插件对于提高项目的构建效率和质量具有重要意义，有效地利用插件来提高 Maven 项目的构建效率和质量。在实际开发中，应根据项目需求选择合适的插件，并合理配置和使用它们，增强项目的可维护性和可扩展性。