2.3 Maven Profile

2.3 Maven Profile

2.3 Maven Profile 详解：灵活配置构建环境

2.3.1 什么是 Maven Profile？

Maven Profile，顾名思义，即 Maven 的“配置文件”。它本质上是一组配置信息的集合，可以定义在 pom.xml 文件或 settings.xml 文件中。Profile 的核心作用在于 允许我们定义多组配置，并在不同的场景下激活不同的配置，从而影响 Maven 构建过程的行为。

想象一下这样的场景：你的项目需要部署到开发环境、测试环境和生产环境。每个环境的数据库连接信息、资源文件路径、甚至依赖的外部服务都可能有所不同。如果每次部署到不同环境都需要手动修改 pom.xml 文件，这将变得繁琐且容易出错。Maven Profile 正是为了解决这类问题而诞生的。

通过 Profile，我们可以将不同环境的配置信息分别定义在不同的 Profile 中，然后在构建时通过简单的命令或条件激活相应的 Profile，Maven 将会自动加载并应用该 Profile 中定义的配置，无需手动修改 pom.xml 文件。

2.3.2 Profile 的定义位置：pom.xml vs. settings.xml

Maven Profile 可以定义在两个主要的位置：

• pom.xml (项目 POM): 定义在项目 pom.xml 文件中的 Profile 是 项目级别的，它们只对当前项目生效。项目 POM 中的 Profile 通常用于定义项目特定环境的配置，例如不同环境的资源文件路径、插件版本等。

• settings.xml (Maven 设置): 定义在 Maven settings.xml 文件中的 Profile 是 全局级别的，它们对所有使用该 Maven 设置文件的项目都生效。settings.xml 中的 Profile 通常用于定义用户级别的配置，例如不同的 Maven 仓库、服务器认证信息等。

选择在哪个位置定义 Profile 取决于配置的 作用范围。如果配置是项目特定的，例如不同环境的构建配置，那么应该将其定义在 pom.xml 中。如果配置是用户级别的，例如不同的 Maven 仓库或代理设置，那么应该将其定义在 settings.xml 中。

2.3.2.1 pom.xml 中的 Profile 定义

在 pom.xml 文件中，Profile 定义在 <profiles> 标签下，每个 Profile 使用 <profile> 标签包裹。每个 <profile> 必须有一个唯一的 <id> 标签，用于标识该 Profile。

<project>
    ...
    <profiles>
        <profile>
            <id>dev</id>
            <properties>
                <environment>dev</environment>
                <database.url>jdbc:mysql://dev.example.com/mydb</database.url>
            </properties>
            <dependencies>
                <dependency>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-devtools</artifactId>
                    <optional>true</optional>
                </dependency>
            </dependencies>
            <build>
                <plugins>
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-compiler-plugin</artifactId>
                        <configuration>
                            <source>1.8</source>
                            <target>1.8</target>
                        </configuration>
                    </plugin>
                </plugins>
                <resources>
                    <resource>
                        <directory>src/main/resources-dev</directory>
                    </resource>
                    <resource>
                        <directory>src/main/resources</directory>
                        <excludes>
                            <exclude>*-dev.*</exclude>
                        </excludes>
                    </resource>
                </resources>
            </build>
        </profile>
        <profile>
            <id>prod</id>
            <properties>
                <environment>prod</environment>
                <database.url>jdbc:mysql://prod.example.com/mydb</database.url>
            </properties>
            <dependencies>
                <dependency>
                    <groupId>com.newrelic.agent.java</groupId>
                    <artifactId>newrelic-api</artifactId>
                </dependency>
            </dependencies>
            <build>
                <plugins>
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-compiler-plugin</artifactId>
                        <configuration>
                            <source>1.8</source>
                            <target>1.8</target>
                        </configuration>
                    </plugin>
                </plugins>
                <resources>
                    <resource>
                        <directory>src/main/resources-prod</directory>
                    </resource>
                    <resource>
                        <directory>src/main/resources</directory>
                        <excludes>
                            <exclude>*-prod.*</exclude>
                        </excludes>
                    </resource>
                </resources>
            </build>
        </profile>
    </profiles>
    ...
</project>
​

在上面的例子中，我们定义了两个 Profile：dev 和 prod，分别代表开发环境和生产环境。每个 Profile 中都定义了：

• <properties>: 定义了环境相关的属性，如 environment 和 database.url。

• <dependencies>: 定义了环境相关的依赖，例如开发环境引入 spring-boot-devtools，生产环境引入 newrelic-api。

• <build>: 定义了环境相关的构建配置，例如资源文件路径。

2.3.2.2 settings.xml 中的 Profile 定义

在 settings.xml 文件中，Profile 的定义方式与 pom.xml 类似，也是在 <profiles> 标签下定义 <profile>。

<settings>
    ...
    <profiles>
        <profile>
            <id>repository-aliyun</id>
            <repositories>
                <repository>
                    <id>aliyun-maven</id>
                    <name>aliyun maven</name>
                    <url>https://maven.aliyun.com/repository/public</url>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                    <snapshots>
                        <enabled>false</enabled>
                    </snapshots>
                </repository>
            </repositories>
            <pluginRepositories>
                <pluginRepository>
                    <id>aliyun-plugin</id>
                    <name>aliyun plugin</name>
                    <url>https://maven.aliyun.com/repository/public</url>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                    <snapshots>
                        <enabled>false</enabled>
                    </snapshots>
                </pluginRepository>
            </pluginRepositories>
        </profile>
        <profile>
            <id>jdk-1.8</id>
            <properties>
                <maven.compiler.source>1.8</maven.compiler.source>
                <maven.compiler.target>1.8</maven.compiler.target>
            </properties>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>repository-aliyun</activeProfile>
    </activeProfiles>
    ...
</settings>
​

在上面的例子中，我们定义了两个 settings.xml 中的 Profile：

• repository-aliyun: 配置了 Maven 使用阿里云的 Maven 仓库，用于加速国内 Maven 依赖下载。

• jdk-1.8: 设置了 Maven 编译的 JDK 版本为 1.8。

需要注意的是，settings.xml 中可以使用 <activeProfiles> 标签来 默认激活 某些 Profile。例如上面的例子中，repository-aliyun Profile 被默认激活。

2.3.3 Profile 的激活方式

Maven Profile 提供了多种激活方式，可以根据不同的场景和需求选择合适的激活方式。主要有以下几种激活方式：

2.3.3.1 显式激活 (命令行激活)

最常用的激活方式是在 Maven 命令行中使用 -P 参数显式指定要激活的 Profile ID。

mvn clean install -P dev
mvn package -P prod,repository-aliyun
​

• -P dev：激活 dev Profile。

• -P prod,repository-aliyun：同时激活 prod 和 repository-aliyun 两个 Profile，多个 Profile ID 之间用逗号分隔。

2.3.3.2 隐式激活 (默认 Profile)

可以在 <profile> 标签下使用 <activation> 标签定义 Profile 的激活条件。当满足激活条件时，Profile 将被自动激活。

a) 默认激活 (<default>)

使用 <default>true</default> 可以将 Profile 设置为默认 Profile。当没有其他 Profile 被显式激活时，默认 Profile 将会被激活。一个项目中只能有一个默认 Profile。

<profile>
    <id>default-profile</id>
    <activation>
        <default>true</default>
    </activation>
    ...
</profile>
​

b) 基于 JDK 版本激活 (<jdk>)

使用 <jdk> 标签可以根据当前 JDK 版本激活 Profile。可以指定 JDK 版本范围，例如 1.8、!1.7、[1.6,1.8] 等。

<profile>
    <id>jdk8-profile</id>
    <activation>
        <jdk>1.8</jdk>
    </activation>
    ...
</profile>
​

c) 基于操作系统激活 (<os>)

使用 <os> 标签可以根据操作系统类型激活 Profile。可以指定操作系统的一些属性，例如 name、family、arch、version。

<profile>
    <id>windows-profile</id>
    <activation>
        <os>
            <family>windows</family>
        </os>
    </activation>
    ...
</profile>
​

d) 基于文件存在/缺失激活 (<file>)

使用 <file> 标签可以根据文件是否存在或缺失激活 Profile。可以使用 <exists> 和 <missing> 子标签指定文件路径。

<profile>
    <id>enable-debug-profile</id>
    <activation>
        <file>
            <exists>${basedir}/debug.flag</exists>
        </file>
    </activation>
    ...
</profile>
<profile>
    <id>disable-debug-profile</id>
    <activation>
        <file>
            <missing>${basedir}/debug.flag</missing>
        </file>
    </activation>
    ...
</profile>
​

e) 基于属性激活 (<property>)

使用 <property> 标签可以根据 Maven 属性的值激活 Profile。可以使用 <name> 和 <value> 子标签指定属性名和属性值。

<profile>
    <id>env-dev-profile</id>
    <activation>
        <property>
            <name>env</name>
            <value>dev</value>
        </property>
    </activation>
    ...
</profile>
<profile>
    <id>env-test-profile</id>
    <activation>
        <property>
            <name>env</name>
            <value>test</value>
        </property>
    </activation>
    ...
</profile>
<profile>
    <id>env-prod-profile</id>
    <activation>
        <property>
            <name>env</name>
            <value>prod</value>
        </property>
    </activation>
    ...
</profile>
​

可以通过在 Maven 命令行中使用 -D 参数设置属性值来激活相应的 Profile。

mvn clean install -Denv=dev
mvn package -Denv=prod
​

f) 基于环境属性激活 (<property>)

<property> 标签也可以用于检查 环境变量 的存在或值。

<profile>
    <id>ci-profile</id>
    <activation>
        <property>
            <name>env.CI</name> <!- 注意使用 env. 前缀 -->
        </property>
    </activation>
    ...
</profile>
<profile>
    <id>jenkins-profile</id>
    <activation>
        <property>
            <name>env.BUILD_TAG</name>
            <value>jenkins-*</value> <!- 可以使用通配符 -->
        </property>
    </activation>
    ...
</profile>
​

Maven 会将环境变量作为属性进行访问，并使用 env. 前缀。

2.3.3.3 Profile 激活优先级

当多种激活方式同时满足时，Profile 的激活优先级如下（从高到低）：

1. 命令行显式激活 (-P)

2. settings.xml 中的 <activeProfiles> 默认激活

3. pom.xml 中的 <activation> 隐式激活 (按定义顺序)

4. 默认 Profile (<default>true</default>)

这意味着，如果一个 Profile 被命令行显式激活，即使其他 Profile 的激活条件也满足，命令行激活的 Profile 仍然具有最高的优先级。

2.3.3.4 Profile 激活逻辑 Mermaid 图

2.3.4 Profile 可以定制的内容

Profile 可以定制 Maven 构建过程的各个方面，主要包括以下内容：

• <properties>: 定义属性，可以覆盖或新增 pom.xml 中定义的属性。

• <dependencies>: 管理依赖，可以添加、移除或修改 pom.xml 中定义的依赖。

• <repositories> 和 <pluginRepositories>: 配置仓库和插件仓库，可以覆盖或新增 pom.xml 或 settings.xml 中定义的仓库。

• <build>: 配置构建过程，包括：

  • <defaultGoal>: 定义默认的 Maven Goal。

  • <resources>: 配置资源文件，可以包含或排除不同的资源文件目录。

  • <testResources>: 配置测试资源文件。

  • <plugins>: 配置插件，可以添加、移除或修改 pom.xml 中定义的插件，并可以定制插件的配置。

  • <directory>、<outputDirectory>、<finalName>、<filters> 等: 其他构建相关的配置。

• <reporting>: 配置 Maven Reporting 插件。

• <dependencyManagement>、<distributionManagement>、<modules> 等: 其他 POM 元素也可以在 Profile 中进行定制，但相对较少使用。

2.3.4.1 定制 Properties

Profile 中定义的 <properties> 可以覆盖或新增 pom.xml 中定义的属性。

示例：

pom.xml:

<project>
    ...
    <properties>
        <app.name>MyApp</app.name>
        <log.level>INFO</log.level>
    </properties>
    <profiles>
        <profile>
            <id>dev</id>
            <properties>
                <log.level>DEBUG</log.level> <!- 覆盖 log.level 属性 -->
                <database.url>jdbc:mysql://dev.example.com/mydb</database.url> <!- 新增 database.url 属性 -->
            </properties>
        </profile>
    </profiles>
    ...
</project>
​

当 dev Profile 激活时，log.level 属性会被覆盖为 DEBUG，同时会新增 database.url 属性。

2.3.4.2 定制 Dependencies

Profile 可以添加、移除或修改 pom.xml 中定义的依赖。

示例：

pom.xml:

<project>
    ...
    <dependencies>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.12</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>1.7.25</version>
        </dependency>
    </dependencies>
    <profiles>
        <profile>
            <id>dev</id>
            <dependencies>
                <dependency>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-devtools</artifactId> <!- 添加依赖 -->
                    <optional>true</optional>
                </dependency>
                <dependency>
                    <groupId>ch.qos.logback</groupId>
                    <artifactId>logback-classic</artifactId> <!- 替换 slf4j-simple 为 logback-classic -->
                    <version>1.2.3</version>
                    <scope>runtime</scope>
                </dependency>
                <dependency>
                    <groupId>org.slf4j</groupId>
                    <artifactId>slf4j-simple</artifactId> <!- 移除 slf4j-simple 依赖 -->
                    <version>1.7.25</version>
                    <scope>runtime</scope>
                    <optional>true</optional> <!- 使用 optional 配合 exclude 可以实现移除依赖的效果 -->
                </dependency>
            </dependencies>
        </profile>
    </profiles>
    ...
</project>
​

当 dev Profile 激活时，会添加 spring-boot-devtools 依赖，并将 slf4j-simple 依赖替换为 logback-classic。

2.3.4.3 定制 Build 配置

Profile 可以定制 <build> 标签下的各种配置，例如资源文件、插件配置等。

示例：定制资源文件

pom.xml:

<project>
    ...
    <build>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
            </resource>
        </resources>
    </build>
    <profiles>
        <profile>
            <id>dev</id>
            <build>
                <resources>
                    <resource>
                        <directory>src/main/resources-dev</directory> <!- 添加 dev 环境资源目录 -->
                    </resource>
                    <resource>
                        <directory>src/main/resources</directory> <!- 修改默认资源目录配置 -->
                        <filtering>true</filtering> <!- 启用资源文件过滤 -->
                        <excludes>
                            <exclude>*-dev.*</exclude> <!- 排除 dev 环境特定的资源文件 -->
                        </excludes>
                    </resource>
                </resources>
            </build>
        </profile>
    </profiles>
    ...
</project>
​

当 dev Profile 激活时，会添加 src/main/resources-dev 目录作为资源目录，并修改默认的 src/main/resources 目录配置，启用资源文件过滤，并排除以 -dev. 结尾的文件，从而实现环境特定的资源文件管理。

示例：定制插件配置

pom.xml:

<project>
    ...
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
    <profiles>
        <profile>
            <id>jdk11</id>
            <build>
                <plugins>
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-compiler-plugin</artifactId>
                        <configuration>
                            <source>11</source> <!- 修改 JDK 版本 -->
                            <target>11</target>
                        </configuration>
                    </plugin>
                </plugins>
            </build>
        </profile>
    </profiles>
    ...
</project>
​

当 jdk11 Profile 激活时，maven-compiler-plugin 插件的配置会被修改，将 JDK 版本设置为 11。

2.3.5 Profile 的最佳实践和注意事项

• Profile ID 的命名规范: Profile ID 应该具有描述性，能够清晰地表达 Profile 的用途，例如 dev、prod、test、jdk8、windows 等。

• 避免过度使用 Profile: Profile 应该用于环境或场景相关的配置差异，而不是用于管理项目的所有配置。过度使用 Profile 会导致 pom.xml 文件过于复杂，难以维护。

• 保持 Profile 的简洁性: Profile 中只应该包含必要的配置差异，避免在 Profile 中重复定义相同的配置。

• 测试 Profile 的有效性: 应该充分测试不同 Profile 的配置是否生效，可以使用 mvn help:active-profiles 命令查看当前激活的 Profile。

• 合理选择 Profile 的激活方式: 根据不同的场景选择合适的激活方式，例如开发环境可以使用默认 Profile，生产环境可以使用命令行显式激活或属性激活。

• 使用 Profile 变量: 在 Profile 中可以使用 ${property.name} 引用在 Profile 或 pom.xml 中定义的属性，方便配置的复用和管理。

• 结合 Maven 属性和 Profile: 可以将 Maven 属性和 Profile 结合使用，例如使用属性来控制 Profile 的激活条件，或者在 Profile 中使用属性来配置不同的值。