Профили Maven: объявление, активация, -P и activeByDefault

В pom.xml два профиля: dev с <activeByDefault>true</activeByDefault>, задающий адрес базы db.url, и it для интеграционных тестов. Разработчик запускает mvn verify -P it, сборка проходит, но в target/classes/app.properties вместо адреса базы лежит строка db.url=${db.url}. Профиль dev молча выключился: activeByDefault действует, только пока в этом POM не активирован никакой другой профиль.

Профиль Maven (Maven profile) — это именованный набор настроек POM внутри элемента <profiles>, который применяется поверх основной модели только при активации: вручную ключом -P или автоматически по условию из <activation> (свойство, версия JDK, операционная система, наличие файла). Профили позволяют одной сборке вести себя по-разному в разных окружениях без копий pom.xml. Примеры рассчитаны на Maven 3.9.x.

Зачем нужны профили Maven

Профили нужны, когда один и тот же проект надо собирать немного по-разному: с другими свойствами для окружения, с дополнительными проверками на CI, с медленными тестами или модулем только по запросу, с настройками под конкретную версию JDK или ОС. Вместо нескольких копий pom.xml различия описываются профилями, а нужный набор включается при запуске.

Профиль меняет то, что получается на выходе сборки: jar, собранный с -P prod, отличается от собранного без него. Поэтому настройки, которые можно задать при запуске приложения (переменные окружения, внешний конфиг), лучше не зашивать в сборку — подробнее в разделах Профили Maven и Spring profiles и Почему не хранить пароли.

Как объявить профиль: profiles, profile, id

Профили объявляют в элементе <profiles> файла pom.xml: каждый <profile> обязан иметь уникальный <id>, по которому его включают ключом -P, может содержать условие <activation> и любые разделы, которые профилю разрешено переопределять (<properties>, <dependencies>, <build> и др.).

<profiles>
    <profile>
        <id>dev</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
            <app.env>dev</app.env>
            <db.url>jdbc:h2:mem:shop</db.url>
        </properties>
    </profile>
    <profile>
        <id>prod</id>
        <properties>
            <app.env>prod</app.env>
            <db.url>jdbc:postgresql://db.example.com/shop</db.url>
        </properties>
    </profile>
</profiles>

Свойства профиля подставляются туда же, куда и обычные свойства из <properties>: в зависимости, настройки плагинов, фильтруемые ресурсы. Включение вручную:

mvn package -P prod          # activate prod
mvn package -P prod,it       # several profiles
mvn package -P '!dev'        # deactivate dev (quote the ! in bash)

В многомодульном проекте профиль из -P включается во всех модулях reactor, где профиль с таким id объявлен (в том числе через родительский POM). Внешний файл profiles.xml рядом с pom.xml, который встречается в старых статьях, был в Maven 2; Maven 3 его не поддерживает.

Что можно переопределить в профиле

Профиль в pom.xml может содержать почти те же разделы, что и сам POM: свойства, зависимости, модули, плагины, ресурсы, репозитории. Недоступны профилю координаты проекта, <parent> и часть настроек <build> — каталоги исходников и вывода, а также расширения сборки.

Сценарий «дополнительный модуль». Медленные сквозные тесты выносят в модуль shop-e2e-tests и подключают его к reactor только в профиле:

<!-- shop-parent/pom.xml -->
<profiles>
    <profile>
        <id>e2e</id>
        <modules>
            <module>shop-e2e-tests</module>
        </modules>
    </profile>
</profiles>

Обычная mvn verify собирает три модуля магазина, а mvn verify -P e2e — четыре. Как устроены агрегация и reactor, разобрано в уроке Многомодульный проект Maven.

Сценарий «плагин только в профиле». Плагин, объявленный в <build><plugins> профиля, добавляется к плагинам основной модели; execution с тем же id объединяется с основным. Так в профиль it кладут maven-failsafe-plugin (зачем он нужен — в разделе surefire и failsafe, как писать executions — в разделе Привязка к фазе: executions).

Активация профиля: -P, activeByDefault, activation

Профиль Maven активируется тремя путями: явно ключом -P (или через <activeProfiles> в settings.xml), по умолчанию через <activeByDefault> или автоматически, когда выполнено условие <activation>: есть свойство, подходит версия JDK, ОС или существует файл. Явная деактивация -P '!id' выключает профиль, даже если его условие выполнено.

Пример автоматической активации: профиль ci включается, когда задано свойство -Dci, а профиль legacy-jdk — на JDK от 17 включительно до 21 не включая:

<profile>
    <id>ci</id>
    <activation>
        <property>
            <name>ci</name>
        </property>
    </activation>
    <!-- static analysis plugins, coverage etc. -->
</profile>
<profile>
    <id>legacy-jdk</id>
    <activation>
        <jdk>[17,21)</jdk>
    </activation>
</profile>

Если в одном <activation> указано несколько условий, в Maven 3.2.2 и новее профиль активируется, только когда выполнены все (в более старых версиях хватало одного). Переменные окружения в Maven 3 доступны условию <property> как свойства с префиксом env. (например, env.CI). В пути <file> допустимы ${basedir}, системные свойства и переменные окружения, но не значения из <properties>. Проверяйте результат командой help:active-profiles, а не по памяти.

Профиль и ресурсы для разных окружений

Чтобы приложение получило настройки окружения, свойства профиля подставляют в фильтруемые ресурсы: профиль задаёт db.url, а Maven при копировании src/main/resources заменяет в файлах выражения ${db.url} значением из активного профиля. Как включить фильтрацию (<filtering>true</filtering>) и какие файлы ей подвергать, разобрано в разделе Раздел build: ресурсы и фильтрация.

С профилями dev и prod из раздела Как объявить профиль и включённой фильтрацией шаблон и результат выглядят так:

# src/main/resources/app.properties
app.env=${app.env}
db.url=${db.url}

# target/classes/app.properties after: mvn package
app.env=dev
db.url=jdbc:h2:mem:shop

# target/classes/app.properties after: mvn package -P prod
app.env=prod
db.url=jdbc:postgresql://db.example.com/shop

Если свойств окружений много, их держат не в POM, а в отдельных файлах фильтров: профиль задаёт <build><filters><filter>src/main/filters/prod.properties</filter></filters></build>, и значения из этого файла тоже подставляются в фильтруемые ресурсы. Помните, что результат — разные артефакты: jar для prod нельзя проверить на тестовом стенде, не пересобрав его.

Профили в settings.xml и activeProfiles

Профили можно объявить и в ~/.m2/settings.xml, но там они ограничены: допустимы только <activation>, <properties>, <repositories> и <pluginRepositories>. Обычно там хранят настройки конкретной машины — адрес корпоративного репозитория или локальные пути, а профиль включают постоянно через <activeProfiles>.

<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0">
    <profiles>
        <profile>
            <id>company</id>
            <repositories>
                <repository>
                    <id>company-snapshots</id>
                    <url>https://nexus.example.com/repository/maven-snapshots/</url>
                </repository>
            </repositories>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>company</activeProfile>
    </activeProfiles>
</settings>

Id из <activeProfiles> активирует профиль с таким именем при каждом запуске Maven на этой машине, как если бы его передали в -P. Всё, что влияет на результат сборки, держите в pom.xml, иначе у коллег и на CI проект соберётся по-другому. Остальное устройство settings.xml (зеркала, логины, путь к репозиторию) — в разделе settings.xml: зеркала, логины и путь к репозиторию.

Какие профили активны: help:active-profiles

Узнать, какие профили Maven реально применил, можно командой mvn help:active-profiles: для каждого модуля она выводит активные профили и источник каждого (POM или settings.xml). Полный список объявленных профилей с признаком активности даёт mvn help:all-profiles, а итоговую модель с применёнными профилями — mvn help:effective-pom с теми же ключами -P.

Примерный вид для модуля, родитель которого объявляет dev с activeByDefault:

mvn help:active-profiles -pl shop-web

Active Profiles for Project 'com.examclouds:shop-web:jar:1.0-SNAPSHOT':

The following profiles are active:

 - dev (source: com.examclouds:shop-parent:1.0-SNAPSHOT)

Для help:all-profiles примерный вид (формат зависит от версии maven-help-plugin):

mvn help:all-profiles -N

[INFO] Listing Profiles for Project: com.examclouds:shop-parent:pom:1.0-SNAPSHOT
  Profile Id: dev (Active: true, Source: pom)
  Profile Id: prod (Active: false, Source: pom)
  Profile Id: e2e (Active: false, Source: pom)

Чтобы проверить, что даст профиль, не запуская сборку, сравните mvn help:effective-pom и mvn help:effective-pom -P prod. Профиль, указанный в -P, но не найденный ни в одном POM, Maven 3.9.x отмечает предупреждением вида The requested profile "prd" could not be activated because it does not exist. — частая опечатка в CI-скриптах, которая не роняет сборку.

Профили Maven и Spring profiles

Профили Maven и профили Spring — разные механизмы с одинаковым названием: профиль Maven действует во время сборки и меняет сам артефакт, а профиль Spring действует при запуске приложения и выбирает конфигурацию внутри одного и того же артефакта. Их можно связать, но заменять один другим не стоит.

Для настроек окружения (адреса, логины, уровни логирования) обычно удобнее профили Spring или переменные окружения: один и тот же jar проходит тестовый стенд и уходит в прод. Профили Maven оставляют для того, что действительно меняет сборку: состав модулей, плагины проверок, зависимости под конкретную JDK.

Почему не хранить пароли в профилях

Пароли, токены и другие секреты не стоит класть в профили pom.xml: файл хранится в Git, а при mvn deploy публикуется в репозиторий артефактов вместе со всеми профилями. Если секрет ещё и подставляется фильтрацией в ресурсы, он оказывается внутри собранного jar.

Частые ошибки с профилями

Большинство проблем с профилями Maven молчаливые: сборка проходит, но не с теми настройками. Поэтому при любом сомнении первым делом запускайте help:active-profiles с теми же ключами, что и сборку.