Плагины Maven: подключение, настройка, executions и обзор плагинов

В проекте нет ни одного упоминания версии Java в pom.xml, а в коде есть public record Order(String id, int total) {}. JDK 25 установлен, но mvn compile падает: Order.java:[3,8] records are not supported in -source 8 (use -source 16 or higher to enable records). Компилирует не Maven, а плагин maven-compiler-plugin, и если его не настроить, он берёт свои значения по умолчанию. В свежих версиях Maven 3.9.x это плагин 3.13.0, а у него по умолчанию версия языка 8, независимо от установленного JDK.

Плагин Maven (plugin) — это артефакт с набором действий, которые Maven выполняет при сборке: компиляция, запуск тестов, упаковка в jar, проверка стиля кода, генерация документации. Каждое действие плагина называется целью (goal). Сам Maven почти ничего не умеет: всю работу делают цели плагинов, привязанные к фазам жизненного цикла или вызванные из командной строки. Плагин подключают и настраивают в разделе <build><plugins> файла pom.xml.

Плагин и цель (goal): как запустить плагин

Чтобы запустить плагин Maven, указывают его цель: mvn checkstyle:check, где checkstyle — префикс плагина, а check — цель. У одного плагина может быть несколько целей: у maven-compiler-plugin это compile и testCompile, у maven-pmd-plugin — pmd, cpd, check и cpd-check. Ту же цель можно вызвать по полным координатам плагина.

Короткий префикс Maven ищет только в группах плагинов из настройки pluginGroups: по умолчанию это org.apache.maven.plugins и org.codehaus.mojo. Префикс плагина из другой группы, например spotbugs (com.github.spotbugs), работает, только если плагин объявлен в pom.xml проекта. Имя артефакта префиксом не является, поэтому форма из старых статей mvn maven-checkstyle-plugin:check не работает:

[ERROR] No plugin found for prefix 'maven-checkstyle-plugin' in the current project and in the plugin groups [org.apache.maven.plugins, org.codehaus.mojo] available from the repositories

Цель, вызванная напрямую, выполняется одна, без предыдущих шагов сборки. Чем это отличается от запуска фазы и почему mvn jar:jar может дать пустой jar, разобрано в разделе Фаза и цель (goal).

Объявление плагина в pom.xml

Плагин объявляют в pom.xml внутри <build><plugins> элементом <plugin> с координатами groupId, artifactId и version (GAV) — так же, как зависимости, плагины идентифицируются по GAV. Объявление позволяет зафиксировать версию плагина, задать параметры и привязать цели к фазам сборки.

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-checkstyle-plugin</artifactId>
            <version>3.6.0</version>
        </plugin>
    </plugins>
</build>

Если groupId не указан, подставляется org.apache.maven.plugins, но для читаемости его лучше писать. Версию указывать обязательно: без неё Maven выдаёт предупреждение 'build.plugins.plugin.version' ... is missing, а сборка зависит от версии установленного Maven. Номера версий в примерах урока реальные, но актуальную версию всегда сверяйте на Maven Central или на странице Available Plugins. Что такое GAV и как устроен раздел <build>, описано в уроке Файл pom.xml в Maven.

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

Настройка плагина: configuration и свойства

Параметры плагина задают в элементе <configuration>: каждый вложенный тег — это имя параметра цели. Многие параметры можно задать и через свойство в <properties> или из командной строки ключом -D: такое свойство называется user property параметра (например, maven.compiler.release или checkstyle.skip).

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>3.6.0</version>
    <configuration>
        <configLocation>google_checks.xml</configLocation>
        <consoleOutput>true</consoleOutput>
    </configuration>
</plugin>

Если параметр задан явно в <configuration>, свойство с тем же смыслом его не переопределит; ключ -D работает только для параметров, которые в pom.xml не заданы явно. Список параметров и их user property выводит плагин maven-help-plugin:

mvn help:describe -Dplugin=compiler -Ddetail

Вывод (фрагмент):

Name: Apache Maven Compiler Plugin
...
Goal Prefix: compiler

This plugin has 3 goals:

compiler:compile
  Description: Compiles application sources.
  ...
    release
      User property: maven.compiler.release
      The -release argument for the Java compiler, supported since Java9
...
compiler:help
compiler:testCompile

Привязка к фазе: executions

Чтобы цель плагина выполнялась автоматически при сборке, её привязывают к фазе жизненного цикла в блоке <executions>. Каждое <execution> содержит уникальный <id>, фазу <phase> и список целей <goals>; при запуске этой фазы (или любой более поздней) Maven выполнит перечисленные цели.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>3.6.0</version>
    <configuration>
        <!-- plugin-level: used by all executions and by the command line -->
        <configLocation>google_checks.xml</configLocation>
        <violationSeverity>warning</violationSeverity>
    </configuration>
    <executions>
        <execution>
            <id>validate-style</id>
            <phase>validate</phase>
            <goals>
                <goal>check</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Теперь mvn package первым делом проверит стиль. Вывод для класса с отступами в 4 пробела (фрагмент; google_checks.xml требует 2 пробела):

[INFO] --- checkstyle:3.6.0:check (validate-style) @ shop ---
[WARN] /home/user/shop/src/main/java/com/examclouds/shop/App.java:5:5: 'method def modifier' has incorrect indentation level 4, expected level should be 2. [Indentation]
...
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-checkstyle-plugin:3.6.0:check (validate-style) on project shop: You have 3 Checkstyle violations.

Что важно знать про executions:

• Фаза по умолчанию. У многих целей фаза уже задана автором плагина: checkstyle:check, pmd:check и spotbugs:check по умолчанию привязаны к verify. Тогда <phase> можно не писать, достаточно <goals>. Если у цели нет фазы по умолчанию и <phase> не указана, цель в сборке не выполнится.
• Где писать configuration. Настройки на уровне <plugin> действуют на все executions и на вызов из командной строки. Настройки внутри <execution> — только на это execution. Команда mvn checkstyle:check выполняется с id default-cli и их не увидит.
• Несколько executions. Одну цель можно запустить дважды с разными настройками, дав executions разные id. Одинаковые id в одном плагине — ошибка чтения POM.
• Отключение унаследованного execution. Если execution пришло от родительского POM, в дочернем модуле его отключают, повторив тот же id с <phase>none</phase>.

Какие цели уже привязаны к фазам без всякого объявления (компиляция, тесты, упаковка) и в каком порядке выполняются цели одной фазы, показано в разделе Привязка целей плагинов к фазам.

Основные плагины Maven: обзорная таблица

Плагины Maven делятся на две группы. Первые подключены по умолчанию через жизненный цикл: clean, resources, compiler, surefire, jar, install, deploy, site. Вторые нужно объявить в pom.xml явно: failsafe, javadoc, checkstyle, shade, gpg и другие. Официальные плагины имеют groupId org.apache.maven.plugins, многие полезные плагины публикует сообщество MojoHaus (org.codehaus.mojo).

«Вызывается без объявления» означает, что цель можно запустить из командной строки (mvn dependency:tree), но в обычную сборку плагин не входит, пока его не привяжут к фазе. Плагины проверки кода Checkstyle, PMD и SpotBugs разобраны ниже.

maven-compiler-plugin: версия Java и параметры компиляции

maven-compiler-plugin компилирует исходники проекта: цель compile — код из src/main/java, цель testCompile — тесты. Плагин подключён по умолчанию, объявлять его нужно, чтобы зафиксировать версию и задать параметры. Главный параметр — release, версия Java, под которую компилируется код; без него действуют значения по умолчанию плагина.

Значения по умолчанию зависят от версии плагина: в старых версиях 3.x source/target по умолчанию были 1.5–1.7 (на JDK 20+ это сразу ошибка Source option 7 is no longer supported), начиная с 3.11.0 — 8. Поэтому проект с record из начала урока и не компилируется. Минимальное исправление — свойство, которое плагин читает сам:

<properties>
    <maven.compiler.release>25</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

Почему для Java 9+ используют release, а не пару source/target, разобрано на примере в уроке Что такое Maven. Если старый пример предлагает <source>1.9</source>, это вдвойне устарело: начиная с Java 9 версии пишутся без «1.» (9, 17, 25), и вместо пары source/target нужен release.

Полное объявление плагина нужно, когда кроме версии Java требуются другие параметры, например аргументы компилятора или процессор аннотаций Lombok:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.14.0</version>
    <configuration>
        <release>25</release>
        <compilerArgs>
            <arg>-parameters</arg>
            <arg>-Xlint:all</arg>
        </compilerArgs>
        <annotationProcessorPaths>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>1.18.40</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

Какую версию плагина Maven использует на самом деле, видно в выводе сборки: строка --- compiler:3.13.0:compile (default-compile) @ shop --- содержит и версию, и цель. Как Lombok подключается как зависимость со scope provided, описано в уроке Зависимости в Maven.

Исполняемый jar и Javadoc

Чтобы jar запускался командой java -jar, в его манифест нужно записать главный класс: это делает параметр archive/manifest/mainClass плагина maven-jar-plugin. Документацию по коду генерирует maven-javadoc-plugin на основе стандартной утилиты javadoc.

Main-Class в манифесте: maven-jar-plugin

По умолчанию maven-jar-plugin не прописывает главный класс, и java -jar завершается ошибкой no main manifest attribute. Исправление — настройка плагина:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <version>3.4.2</version>
    <configuration>
        <archive>
            <manifest>
                <mainClass>com.examclouds.App</mainClass>
            </manifest>
        </archive>
    </configuration>
</plugin>

mvn package
java -jar target/hello-maven-1.0-SNAPSHOT.jar

Вывод (для класса App из архетипа quickstart):

Hello World!

Такой jar содержит только классы проекта. Если код использует сторонние библиотеки, запуск упадёт с NoClassDefFoundError на первом обращении к ним: зависимости нужно либо передать в classpath, либо собрать «толстый» jar плагином maven-shade-plugin (или spring-boot-maven-plugin в Spring Boot-проекте).

maven-javadoc-plugin

Плагин генерирует HTML-документацию из комментариев /** ... */ утилитой javadoc:

mvn javadoc:javadoc

Куда попадёт результат, зависит от способа запуска: в составе сайта (mvn site) — в каталог target/site/apidocs, а при прямом вызове цели в версиях плагина 3.x — в target/reports/apidocs. Точный путь javadoc печатает в выводе. Цель javadoc:jar собирает -javadoc.jar, который вместе с -sources.jar и подписями maven-gpg-plugin требуется для публикации библиотеки в Maven Central. Начиная с JDK 8 javadoc строго проверяет комментарии (doclint) и останавливается на ошибках вроде неизвестного тега; временно ослабить проверку можно параметром <doclint>none</doclint>, но лучше исправить комментарии.

Проверка кода: Checkstyle, PMD, SpotBugs

Для автоматической проверки качества кода в Maven используют три плагина: maven-checkstyle-plugin проверяет стиль оформления исходников, maven-pmd-plugin ищет подозрительные конструкции и дубликаты кода, spotbugs-maven-plugin анализирует байткод на вероятные ошибки. У каждого есть цель-отчёт и цель check, которая останавливает сборку при нарушениях.

Цели check всех трёх плагинов по умолчанию привязаны к фазе verify: достаточно добавить их в <executions> без <phase>, и mvn verify на CI будет падать при нарушениях.

maven-checkstyle-plugin и suppressions

Без настройки плагин проверяет код по правилам Sun (sun_checks.xml); второй встроенный набор — google_checks.xml. Отчёт по нарушениям записывается в target/checkstyle-result.xml.

mvn checkstyle:check

Готовые наборы правил редко подходят проекту целиком, поэтому обычно используют свой файл правил или отключают отдельные проверки через файл подавлений (suppressions):

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>3.6.0</version>
    <configuration>
        <suppressionsLocation>checkstyle-suppressions.xml</suppressionsLocation>
    </configuration>
</plugin>

Файл checkstyle-suppressions.xml в корне проекта:

<?xml version="1.0"?>
<!DOCTYPE suppressions PUBLIC
        "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN"
        "https://checkstyle.org/dtds/suppressions_1_2.dtd">
<suppressions>
    <!-- everywhere -->
    <suppress checks="MagicNumber" files="."/>
    <suppress checks="FinalParameters|HiddenField" files="."/>
    <!-- only in tests -->
    <suppress checks="Javadoc.*" files="[\\/]src[\\/]test[\\/]"/>
    <!-- one generated class -->
    <suppress checks=".*" files="[\\/]generated[\\/].*\.java"/>
</suppressions>

Атрибуты checks и files — регулярные выражения: первый сопоставляется с именем проверки, второй — с путём к файлу. Выражение [\\/] совпадает и с /, и с \, поэтому правило работает в Linux и Windows.

Встроенная версия Checkstyle. Плагин 3.6.0 по умолчанию использует Checkstyle 9.3, который не знает синтаксиса последних версий Java и может не разобрать такой файл. Версию самого Checkstyle повышают зависимостью внутри плагина:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>3.6.0</version>
    <dependencies>
        <dependency>
            <groupId>com.puppycrawl.tools</groupId>
            <artifactId>checkstyle</artifactId>
            <!-- check the latest version on Maven Central -->
            <version>10.21.4</version>
        </dependency>
    </dependencies>
</plugin>

Это пример общего приёма: <dependencies> внутри <plugin> меняют classpath самого плагина и в classpath приложения не попадают.

maven-pmd-plugin

PMD ищет в исходниках «плохой код»: неиспользуемые переменные и импорты, пустые блоки catch, излишне сложные методы. Входящий в плагин Copy/Paste Detector (CPD) находит дубликаты кода. Плагин работает в двух режимах.

Отчёты. Полезно при первом подключении к существующему проекту, который раньше не использовал эти инструменты: можно оценить масштаб проблем, не ломая сборку.

mvn pmd:pmd
mvn pmd:cpd

Проверка. Если найдено нарушение, сборка останавливается. Цели check и cpd-check сами запускают анализ перед проверкой:

mvn pmd:check
mvn pmd:cpd-check

Объявление в pom.xml с проверкой при mvn verify:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-pmd-plugin</artifactId>
    <version>3.26.0</version>
    <configuration>
        <!-- CPD: minimum duplicate size in tokens -->
        <minimumTokens>100</minimumTokens>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>check</goal>
                <goal>cpd-check</goal>
            </goals>
        </execution>
    </executions>
</plugin>

spotbugs-maven-plugin вместо findbugs-maven-plugin

SpotBugs ищет в скомпилированных классах шаблоны типичных ошибок: возможное разыменование null, неправильное использование API, ошибки многопоточности. Это преемник FindBugs: последний релиз FindBugs (3.0.1) вышел в 2015 году и не понимает байткод новее Java 8, поэтому findbugs-maven-plugin из старых статей на современных JDK не используют.

<plugin>
    <groupId>com.github.spotbugs</groupId>
    <artifactId>spotbugs-maven-plugin</artifactId>
    <!-- first three numbers = SpotBugs version -->
    <version>4.9.3.0</version>
    <configuration>
        <effort>Max</effort>
        <threshold>Medium</threshold>
    </configuration>
</plugin>

mvn compile spotbugs:check
mvn spotbugs:gui

SpotBugs анализирует байткод, а не исходники, поэтому при вызове из командной строки перед целью нужна компиляция (mvn compile spotbugs:check); при привязке к verify классы уже скомпилированы. Цель spotbugs:gui открывает найденные проблемы в окне с привязкой к строкам кода. Список шаблонов ошибок — в документации SpotBugs.

Версии плагинов и pluginManagement

Версию плагина фиксируют в pom.xml: в <plugin> или централизованно в <build><pluginManagement>. Если версия не указана, для стандартных плагинов её подставляет установленный Maven, и одна и та же сборка на Maven 3.9.0 и 3.9.11 пойдёт с разными плагинами. Фактическую версию показывает лог сборки и mvn help:effective-pom.

Как узнать версию плагина

mvn versions:display-plugin-updates

Вывод (фрагмент; номера зависят от проекта и даты запуска):

[INFO] The following plugin updates are available:
[INFO]   maven-checkstyle-plugin ...................... 3.5.0 -> 3.6.0
[INFO]   maven-compiler-plugin ...................... 3.13.0 -> 3.14.0

pluginManagement

<pluginManagement> задаёт версии и настройки плагинов «на случай использования» и сам по себе плагины не запускает. Обычно его пишут в родительском POM, а модули объявляют плагин в <plugins> уже без версии:

<!-- parent pom.xml -->
<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-checkstyle-plugin</artifactId>
                <version>3.6.0</version>
                <configuration>
                    <configLocation>google_checks.xml</configLocation>
                </configuration>
            </plugin>
        </plugins>
    </pluginManagement>
</build>

<!-- module pom.xml: version and configuration come from the parent -->
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-checkstyle-plugin</artifactId>
        </plugin>
    </plugins>
</build>

Как устроены родительский POM и effective POM, описано в разделе parent, Super POM и effective POM.

Подводные камни при настройке плагинов

Большинство ошибок с плагинами Maven не приводят к падению сборки: плагин просто не запускается или работает с другими настройками. В таблице — что сделали, что получили и как исправить.