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>