Перейти к основному содержимому

Файл settings.xml в Maven

· 8 мин. чтения

1. Обзор​

При использовании Maven мы сохраняем большую часть конфигурации для конкретного проекта в файле pom.xml .

Maven предоставляет файл настроек settings.xml, который позволяет нам указать, какие локальные и удаленные репозитории он будет использовать. Мы также можем использовать его для хранения настроек, которые нам не нужны в нашем исходном коде, таких как учетные данные.

В этом руководстве мы узнаем, как использовать файл settings.xml . Мы рассмотрим прокси, зеркалирование и профили. Мы также обсудим, как определить текущие настройки, применимые к нашему проекту.

2. Конфигурации​

Файл settings.xml настраивает установку Maven . Он похож на файл pom.xml , но определяется глобально или для каждого пользователя.

Давайте рассмотрим элементы, которые мы можем настроить в файле settings.xml . Основной элемент настроек файла settings.xml может содержать девять возможных предопределенных дочерних элементов:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository/>
    <interactiveMode/>
    <offline/>
    <pluginGroups/>
    <servers/>
    <mirrors/>
    <proxies/>
    <profiles/>
    <activeProfiles/>
</settings>

2.1. Простые значения​

Некоторые из элементов конфигурации верхнего уровня содержат простые значения:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository>${user.home}/.m2/repository</localRepository>
    <interactiveMode>true</interactiveMode>
    <offline>false</offline>
</settings>

Элемент localRepository указывает путь к локальному репозиторию системы. В локальном репозитории кэшируются все зависимости от наших проектов . По умолчанию используется домашний каталог пользователя. Однако мы могли бы изменить его, чтобы разрешить всем вошедшим в систему пользователям выполнять сборку из общего локального репозитория.

Флаг InteractiveMode определяет, разрешаем ли мы Maven взаимодействовать с пользователем, запрашивающим ввод. Этот флаг по умолчанию имеет значение true .

Флаг автономного режима определяет, может ли система сборки работать в автономном режиме. По умолчанию это значение false; однако мы можем переключить его на true в тех случаях, когда серверы сборки не могут подключиться к удаленному репозиторию.

2.2. Группы плагинов​

Элемент pluginGroups содержит список дочерних элементов, у которых указан groupId . GroupId — это уникальный идентификатор организации, создавшей определенный артефакт Maven:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <pluginGroups>
        <pluginGroup>org.apache.tomcat.maven</pluginGroup>
    </pluginGroups>
</settings>

Maven выполняет поиск в списке групп подключаемых модулей, когда подключаемый модуль используется без идентификатора группы, указанного в командной строке . Список содержит группы org.apache.maven.plugins и org.codehaus.mojo по умолчанию.

Определенный выше файл settings.xml позволяет нам выполнять усеченные команды подключаемого модуля Tomcat:

mvn tomcat7:help
mvn tomcat7:deploy
mvn tomcat7:run

2.3. Прокси​

Мы можем настроить прокси для некоторых или всех HTTP-запросов Maven. Элемент прокси позволяет список дочерних элементов прокси, но одновременно может быть активен только один прокси :

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <proxies>
        <proxy>
            <id>foreach-proxy</id>
            <active>true</active>
            <protocol>http</protocol>
            <host>foreach.proxy.com</host>
            <port>8080</port>
            <username>demo-user</username>
            <password>dummy-password</password>
            <nonProxyHosts>*.foreach.com|*.apache.org</nonProxyHosts>
        </proxy>
    </proxies>
</settings>

Мы определяем текущий активный прокси через активный флаг. Затем с помощью элемента nonProxyHosts мы указываем, какие хосты не проксируются. Используемый разделитель зависит от конкретного прокси-сервера. Наиболее распространенными разделителями являются вертикальная черта и запятая.

2.4. Зеркала​

Репозитории могут быть объявлены внутри проекта pom.xml. Это означает, что `` разработчики, совместно использующие код проекта, получают нужные настройки репозитория из коробки.

Мы можем использовать зеркала в тех случаях, когда мы хотим определить альтернативное зеркало для определенного репозитория . Это переопределяет то, что находится в pom.xml .

Например, мы можем заставить Maven использовать один репозиторий, зеркалируя все запросы к репозиторию:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <mirrors>
        <mirror>
            <id>internal-foreach-repository</id>
            <name>ForEach Internal Repo</name>
            <url>https://foreach.com/repo/maven2/</url>
            <mirrorOf>*</mirrorOf>
        </mirror>
    </mirrors>
</settings>

Мы можем определить только одно зеркало для данного репозитория, и Maven выберет первое совпадение. Обычно мы должны использовать официальный репозиторий , распространяемый по всему миру через CDN.

2.5. Серверы​

Определение репозиториев в проекте pom.xml является хорошей практикой. Однако мы не должны помещать параметры безопасности, такие как учетные данные, в наш репозиторий исходного кода с pom.xml . Вместо этого мы определяем эту безопасную информацию в файле settings.xml :

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <server>
            <id>internal-foreach-repository</id>
            <username>demo-user</username>
            <password>dummy-password</password>
            <privateKey>${user.home}/.ssh/bael_key</privateKey>
            <passphrase>dummy-passphrase</passphrase>
            <filePermissions>664</filePermissions>
            <directoryPermissions>775</directoryPermissions>
            <configuration></configuration>
        </server>
    </servers>
</settings>

Следует отметить, что идентификатор сервера в settings.xml должен соответствовать элементу идентификатора репозитория, указанному в pom.xml . XML также позволяет нам использовать заполнители для получения учетных данных из переменных среды.

3. Профили​

Элемент profiles позволяет нам создавать несколько дочерних элементов профиля , отличающихся своим идентификатором дочернего элемента. Элемент profile в settings.xml представляет собой усеченную версию того же элемента, доступного в pom.xml .

Он может содержать только четыре дочерних элемента: активация , репозитории , pluginRepositories и properties. Эти элементы настраивают систему сборки в целом, а не какой-либо конкретный проект.

Важно отметить, что значения из активного профиля в settings.xml переопределяют любые эквивалентные значения профиля в файле pom.xml или profiles.xml . Профили сопоставляются по ID .

3.1. Активация​

Мы можем использовать профили для изменения определенных значений только при определенных обстоятельствах. Мы можем указать эти обстоятельства, используя элемент активации . Следовательно, активация профиля происходит при соблюдении всех указанных критериев :

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <profiles>
        <profile>
            <id>foreach-test</id>
            <activation>
                <activeByDefault>false</activeByDefault>
                <jdk>1.8</jdk>
                <os>
                    <name>Windows 10</name>
                    <family>Windows</family>
                    <arch>amd64</arch>
                    <version>10.0</version>
                </os>
                <property>
                    <name>mavenVersion</name>
                    <value>3.0.7</value>
                </property>
                <file>
                    <exists>${basedir}/activation-file.properties</exists>
                    <missing>${basedir}/deactivation-file.properties</missing>
                </file>
            </activation>
        </profile>
    </profiles>
</settings>

Есть четыре возможных активатора, и не все из них нужно указывать:

  • jdk: активируется на основе указанной версии JDK (поддерживаются диапазоны)
  • os: активируется на основе свойств операционной системы
  • свойство: активирует профиль, если Maven обнаруживает определенное значение свойства
  • файл: активирует профиль, если данное имя файла существует или отсутствует

Чтобы проверить, какой профиль активирует определенную сборку, мы можем использовать плагин справки Maven:

mvn help:active-profiles

На выходе будут отображаться текущие активные профили для данного проекта:

[INFO] --- maven-help-plugin:3.2.0:active-profiles (default-cli) @ core-java-streams-3 ---
[INFO]
Active Profiles for Project 'com.foreach.core-java-modules:core-java-streams-3:jar:0.1.0-SNAPSHOT':
The following profiles are active:
 - foreach-test (source: com.foreach.core-java-modules:core-java-streams-3:0.1.0-SNAPSHOT)

3.2. Характеристики​

Свойства Maven можно рассматривать как именованные заполнители для определенного значения. Значения доступны в файле pom.xml с использованием нотации ${property_name} :

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <profiles>
        <profile>
            <id>foreach-test</id>
            <properties>
                <user.project.folder>${user.home}/foreach-tutorials</user.project.folder>
            </properties>
        </profile>
    </profiles>
</settings>

В файлах pom.xml доступны четыре различных типа свойств :

  • Свойства, использующие префикс env , возвращают значение переменной среды, например ${env. ДОРОЖКА}.
  • Свойства, использующие префикс проекта , возвращают значение свойства, установленное в элементе проекта pom.xml , например ${project.version}.
  • Свойства, использующие префикс settings , возвращают значение соответствующего элемента из settings.xml , например ${settings.localRepository}.
  • Мы можем напрямую ссылаться на все свойства, доступные через метод System.getProperties в Java, например ${java.home}.
  • Мы можем использовать набор свойств внутри элемента properties без префикса, например ${junit.version}.

3.3. Репозитории​

Удаленные репозитории содержат коллекции артефактов, которые Maven использует для заполнения нашего локального репозитория. Для определенных артефактов могут потребоваться разные удаленные репозитории. Maven ищет репозитории, включенные в активном профиле :

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <profiles>
        <profile>
            <id>adobe-public</id>
            <repositories>
            <repository>
                <id>adobe-public-releases</id>
                <name>Adobe Public Repository</name>
                <url>https://repo.adobe.com/nexus/content/groups/public</url>
                <releases>
                    <enabled>true</enabled>
                    <updatePolicy>never</updatePolicy>
                </releases>
                <snapshots>
                    <enabled>false</enabled>
                </snapshots>
            </repository>
        </repositories>
        </profile>
    </profiles>
</settings>

Мы можем использовать элемент репозитория , чтобы включить только выпуски или моментальные снимки артефактов из определенного репозитория.

3.4. Репозитории плагинов​

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

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <profiles>
        <profile>
            <id>adobe-public</id>
            <pluginRepositories>
               <pluginRepository>
                  <id>adobe-public-releases</id>
                  <name>Adobe Public Repository</name>
                  <url>https://repo.adobe.com/nexus/content/groups/public</url>
                  <releases>
                      <enabled>true</enabled>
                      <updatePolicy>never</updatePolicy>
                  </releases>
                  <snapshots>
                      <enabled>false</enabled>
                  </snapshots>
            </pluginRepository>
        </pluginRepositories>
        </profile>
    </profiles>
</settings>

Примечательно, что структура элемента pluginRepositories очень похожа на элемент repositories .

3.5. Активные профили​

Элемент activeProfiles содержит дочерние элементы, которые относятся к определенному идентификатору профиля . Maven автоматически активирует любой профиль, указанный здесь :

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <activeProfiles>
        <activeProfile>foreach-test</activeProfile>
        <activeProfile>adobe-public</activeProfile>
    </activeProfiles>
</settings>

В этом примере каждый вызов mvn выполняется так, как если бы мы добавили -P foreach-test,adobe-public в командную строку.

4. Уровень настроек​

Файл settings.xml обычно находится в нескольких местах:

  • Глобальные настройки в домашнем каталоге Mavens: ${maven.home}/conf/settings.xml
  • Настройки пользователя в доме пользователя: ${user.home}/.m2/settings.xml

Если оба файла существуют, их содержимое объединяется. Конфигурации из пользовательских настроек имеют приоритет .

4.1. Определить местоположение файла​

Чтобы определить расположение глобальных и пользовательских настроек, мы можем запустить Maven, используя флаг отладки, и искать «настройки» в выводе:

$ mvn -X clean | grep "settings"
[DEBUG] Reading global settings from C:\Program Files (x86)\Apache\apache-maven-3.6.3\bin\..\conf\settings.xml
[DEBUG] Reading user settings from C:\Users\ForEach\.m2\settings.xml

4.2. Определите эффективные настройки​

Мы можем использовать плагин справки Maven, чтобы узнать содержимое объединенных глобальных и пользовательских настроек :

mvn help:effective-settings

Это описывает настройки в формате XML:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository>C:\Users\ForEach\.m2\repository</localRepository>
    <pluginGroups>
        <pluginGroup>org.apache.tomcat.maven</pluginGroup>
        <pluginGroup>org.apache.maven.plugins</pluginGroup>
        <pluginGroup>org.codehaus.mojo</pluginGroup>
    </pluginGroups>
</settings>

4.3. Переопределить местоположение по умолчанию​

Maven также позволяет нам переопределить расположение глобальных и пользовательских настроек через командную строку:

$ mvn clean --settings c:\user\user-settings.xml --global-settings c:\user\global-settings.xml

Мы также можем использовать более короткую версию той же команды –s : 

$ mvn clean --s c:\user\user-settings.xml --gs c:\user\global-settings.xml

5. Вывод​

В этой статье мы рассмотрели конфигурации, доступные в файле Maven settings.xml .

Мы научились настраивать прокси, репозитории и профили. Далее мы рассмотрели разницу между файлами глобальных и пользовательских настроек и то, как определить, какие из них используются.

Наконец, мы рассмотрели определение используемых эффективных настроек и переопределение расположения файлов по умолчанию.