Maven 打包程序如何使用可在外部修改的配置文件

这半年来接触的事情很杂，好久没更博了。这两天开始摸索 Java 开发，遇到一个挺折腾的问题，正好记录下来备查。问题是在将 XML 文件信息写入数据库时遇到的，这个 XML 文件比较特殊，标签与数据库中对应的字段名称不一样，需要维护一个单独的配置文件，我将其整理成了一个 JSON 配置文件，以便后期直接修改。正好最近在看 Java 相关的内容，就想用 Java 练一下手。功能实现倒是很快就搞定了，结果如何动态配置文件这卡了整整一天。

问题描述

如何将 maven 中的资源文件（配置文件）使用 maven-assembly-plugin 打包时不打包进 jar 包中，之后可以手动修改

解决过程

踩坑 1: SqlServer 驱动问题

Maven 仓库网站直接给出的 SqlServer 驱动依赖如下：

<!-- https://mvnrepository.com/artifact/com.microsoft.sqlserver/mssql-jdbc -->
<dependency>
    <groupId>com.microsoft.sqlserver</groupId>
    <artifactId>mssql-jdbc</artifactId>
    <version>7.4.1.jre11</version>
    <scope>test</scope>
</dependency>

在使用过程中需要将 <scope>test</scope> 删除掉，否则这个依赖仅在 test 时会添加，专坑我这种小白

获取资源文件所在目录

资源文件所在目录可用以下方式获得，注意，不同环境下获取到的路径有所差异

private static String getBasePath() {
    // 该函数在不同环境下获得的路径是不同的
    // 编译环境下得到的路径是 .../target/classes/
    // 打包成 jar 文件后，得到的路径是 jar 文件的位置
    // 此处获得的路径，即使在 windows 下，使用的也是 linux 下的文件分隔符
    String basePath = AppConfig.class.getProtectionDomain().getCodeSource().getLocation().getPath();

    // 如果包含中文路径，则对其进行 decode 处理
    basePath = URLDecoder.decode(basePath, StandardCharsets.UTF_8);

    // 将路径中的文件分割符更换为当前运行环境的文件分隔符
    basePath = basePath.replace('/', System.getProperty("file.separator").charAt(0));

    // 在打包环境下，取得 jar 文件所在的文件夹路径，而不是 jar 文件路径
    int firstIndex = basePath.indexOf(System.getProperty("file.separator")) + 1;
    int lastIndex = basePath.lastIndexOf(System.getProperty("file.separator")) + 1;
    basePath = basePath.substring(firstIndex, lastIndex);

    // 设定配置文件目录，结尾带文件分隔符
    basePath = basePath + "config" + System.getProperty("file.separator");
    return basePath;
    }

在 pom.xml 中排除原有的资源文件

<build>
    ...
    <resources>
        <!-- 排除默认资源文件 -->
        <resource>
            <directory>src/main/resources</directory>
            <excludes>
                <exclude>**/*</exclude>
            </excludes>
            <filtering>true</filtering>
        </resource>
    </resources>
    ...
</build>

编译前拷贝配置文件

编译时拷贝配置文件至 target/class 下的指定文件夹中（此处是 config 文件夹）以供程序直接执行时使用，此处借助了 maven-resources-plugin 插件

<build>
    <plugins>
        ...
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-resources-plugin</artifactId>
            <version>3.1.0</version>
            <executions>
                <execution>
                    <id>copy-resources</id>
                    <!-- 绑定到 maven 生命周期的哪一节段 -->
                    <phase>validate</phase>
                    <goals>
                        <goal>copy-resources</goal>
                    </goals>
                    <configuration>
                        <encoding>UTF-8</encoding>
                        <!-- ${project.build.outputDirectory} 为构建过程输出目录，缺省为target/classes -->
                        <outputDirectory>${project.build.outputDirectory}/config</outputDirectory>
                        <resources>
                            <resource>
                                <!-- 需要拷贝的资源文件位置 -->
                                <directory>src/main/resources</directory>
                                <!-- 开启变量替换，将 pom.xml 中的相关变量替换至 properties 文件中，该项目中未使用该特性 -->
                                <filtering>true</filtering>
                            </resource>
                        </resources>
                    </configuration>
                </execution>
            </executions>
            <configuration>
                <encoding>UTF-8</encoding>
            </configuration>
        </plugin>
        ...
    </plugins>
</build>

打包时拷贝资源文件

由于借助了 maven-assembly-plugin 插件，设置分为两个部分，一个是 pom.xml 中的配置，一个是 assembly.xml 中的配置

• pom.xml

<build>
    <plugins>
        ...
        <plugin>
            <artifactId>maven-assembly-plugin</artifactId>
            <version>3.2.0</version>
            <configuration>
                <!-- 配置描述符文件 -->
                <appendAssemblyId>true</appendAssemblyId>
                <descriptors>
                    <descriptor>src/main/assembly/assembly.xml</descriptor>
                </descriptors>
            </configuration>
            <executions>
                <execution>
                    <id>make-assembly</id>
                    <!-- 将组装绑定到maven生命周期的哪一阶段 -->
                    <phase>package</phase>
                    <goals>
                        <!-- 指定assembly插件的打包方式 -->
                        <goal>single</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        ...
    </plugins>
</build>

• assembly.xml

<assembly>
    ...
    <fileSets>
        ...
        <!-- 对资源文件进行打包 -->
        <fileSet>
            <!-- ${project.build.outputDirectory} 为构建过程输出目录，缺省为 target/classes -->
            <directory>${project.build.outputDirectory}/config</directory>
            <outputDirectory>config</outputDirectory>
            <includes>
                <include>**/*</include>
            </includes>
        </fileSet>
        ...
    </fileSets>
    ...
</assembly>

其他

还有一些外部依赖相关的设置，不是本篇关注的重点，在此就不叙述了，完整的 pom.xml 文件和 assembly.xml 文件如下

• pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<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>...</groupId>
    <artifactId>...</artifactId>
    <version>...</version>

    <properties>
        <java.version>11</java.version>
    </properties>

    <dependencies>
        <!-- https://mvnrepository.com/artifact/commons-io/commons-io -->
        <dependency>
            <groupId>commons-io</groupId>
            <artifactId>commons-io</artifactId>
            <version>2.6</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/org.projectlombok/lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.10</version>
            <scope>provided</scope>
        </dependency>
        <!-- https://mvnrepository.com/artifact/com.microsoft.sqlserver/mssql-jdbc -->
        <dependency>
            <groupId>com.microsoft.sqlserver</groupId>
            <artifactId>mssql-jdbc</artifactId>
            <version>7.4.1.jre11</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-databind -->
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.10.1</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <target>11</target>
                    <source>11</source>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-resources-plugin</artifactId>
                <version>3.1.0</version>
                <executions>
                    <execution>
                        <id>copy-resources</id>
                        <phase>validate</phase>
                        <goals>
                            <goal>copy-resources</goal>
                        </goals>
                        <configuration>
                            <encoding>UTF-8</encoding>
                            <!-- ${project.build.outputDirectory} 为构建过程输出目录，缺省为target/classes -->
                            <outputDirectory>${project.build.outputDirectory}/config</outputDirectory>
                            <resources>
                                <resource>
                                    <!-- 需要拷贝的资源文件位置 -->
                                    <directory>src/main/resources</directory>
                                    <!-- 开启变量替换，将 pom.xml 中的相关变量替换至 properties 文件中，该项目中未使用该特性 -->
                                    <filtering>true</filtering>
                                </resource>
                            </resources>
                        </configuration>
                    </execution>
                </executions>
                <configuration>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.2.0</version>
                <configuration>
                    <archive>
                        <manifest>
                            <addClasspath>true</addClasspath>
                            <classpathPrefix>lib/</classpathPrefix>
                            <mainClass>cn.scodi.catia_xml2db.ApplicationRunner</mainClass>
                        </manifest>
                    </archive>
                    <!--过滤掉不希望包含在jar中的文件-->
                    <excludes>
                        <!-- 排除不需要的文件夹(路径是jar包内部的路径) -->
                        <exclude>**/assembly/</exclude>
                    </excludes>
                </configuration>
            </plugin>
            <plugin>
                <artifactId>maven-assembly-plugin</artifactId>
                <version>3.2.0</version>
                <configuration>
                    <!-- 配置描述符文件 -->
                    <appendAssemblyId>true</appendAssemblyId>
                    <descriptors>
                        <descriptor>src/main/assembly/assembly.xml</descriptor>
                    </descriptors>
                </configuration>
                <executions>
                    <execution>
                        <id>make-assembly</id>
                        <!-- 将组装绑定到maven生命周期的哪一阶段 -->
                        <phase>package</phase>
                        <goals>
                            <!-- 指定assembly插件的打包方式 -->
                            <goal>single</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
        <resources>
            <!-- 排除默认资源文件 -->
            <resource>
                <directory>src/main/resources</directory>
                <excludes>
                    <exclude>**/*</exclude>
                </excludes>
                <filtering>true</filtering>
            </resource>
        </resources>
    </build>
</project>

• assembly.xml

<assembly>
    <id>assembly</id>

    <formats>
        <format>zip</format>
    </formats>

    <includeBaseDirectory>true</includeBaseDirectory>

    <!-- 文件设置，你想把哪些文件包含进去，或者把某些文件排除掉，都是在这里配置-->
    <fileSets>
        <!-- 把项目自己编译出来的可执行jar，打包进zip文件的根目录 -->
        <fileSet>
            <directory>${project.build.directory}</directory>
            <outputDirectory></outputDirectory>
            <includes>
                <include>*.jar</include>
            </includes>
        </fileSet>
        <!-- 对资源文件进行打包 -->
        <fileSet>
            <!-- ${project.build.outputDirectory} 为构建过程输出目录，缺省为 target/classes -->
            <directory>${project.build.outputDirectory}/config</directory>
            <outputDirectory>config</outputDirectory>
            <includes>
                <include>**/*</include>
            </includes>
        </fileSet>
    </fileSets>

    <dependencySets>
        <dependencySet>
            <unpack>false</unpack>
            <scope>runtime</scope>
            <outputDirectory>lib</outputDirectory>
        </dependencySet>
    </dependencySets>
</assembly>