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

Плагин Maven - артефакт с набором действий, которые Maven выполняет при сборке: компиляция, запуск тестов, упаковка jar, проверка стиля, генерация документации. Каждое действие плагина называется целью (goal): у maven-compiler-plugin это compile и testCompile, у maven-pmd-plugin - pmd, cpd, check, cpd-check. Сам Maven почти ничего не умеет: всю работу делают цели, привязанные к фазам или вызванные из командной строки.

Три формы вызова:

• mvn checkstyle:check - префикс и цель; версия берётся из pom.xml или pluginManagement, иначе версия по умолчанию из Maven или последняя из репозитория;
• mvn org.apache.maven.plugins:maven-checkstyle-plugin:check - полные координаты, версия выбирается так же;
• mvn org.apache.maven.plugins:maven-checkstyle-plugin:3.6.0:check - ровно указанная версия независимо от pom.xml.

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

Плагин отличается от зависимости: зависимость - библиотека для кода приложения и попадает в его classpath, плагин - инструмент самой сборки, работает внутри Maven и в приложение не попадает.

Плагин объявляют в <build><plugins> элементом <plugin> с координатами groupId, artifactId, version - как зависимость. Без groupId подразумевается org.apache.maven.plugins. Версию указывают всегда: без неё Maven выводит предупреждение 'build.plugins.plugin.version' ... is missing, и сборка зависит от установленной версии Maven.

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

Параметры задают в <configuration>: каждый вложенный тег - имя параметра цели, например <configLocation>google_checks.xml</configLocation>. У многих параметров есть user property - свойство, которое можно задать в <properties> или через -D (maven.compiler.release, checkstyle.skip). Если параметр явно задан в <configuration>, свойство его не переопределяет: -D действует только для параметров, не заданных явно.

Список параметров и их user property выводит mvn help:describe -Dplugin=compiler -Ddetail. Если плагину нужна дополнительная библиотека, её указывают в <dependencies> внутри <plugin> - это меняет classpath самого плагина, а не приложения.

В блоке <executions> каждый <execution> содержит уникальный <id>, <phase> и список <goals>. Когда выполняется эта фаза (или любая следующая), Maven запускает перечисленные цели; в логе видно --- checkstyle:3.6.0:check (validate-style) @ shop ---.

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

Временно пропустить плагин при сборке можно его параметром skip: mvn verify -Dcheckstyle.skip -Dpmd.skip -Dspotbugs.skip; имя свойства показывает mvn help:describe -Dplugin=... -Ddetail.

Подключены по умолчанию через жизненный цикл: clean, resources, compiler, surefire, jar (war, ear - по packaging), install, deploy, site. Нужно объявить: failsafe, javadoc, source, gpg, shade, enforcer, checkstyle, pmd, spotbugs. Официальные плагины имеют groupId org.apache.maven.plugins, многие полезные публикует сообщество MojoHaus (org.codehaus.mojo, например versions-maven-plugin). Плагины dependency, help, versions, archetype вызываются без объявления (mvn dependency:tree), но в обычную сборку не входят, пока цель не привязана к фазе.

Исполняемый jar. По умолчанию maven-jar-plugin не прописывает главный класс; его задают параметром <archive><manifest><mainClass>, после чего работает java -jar. Такой jar содержит только классы проекта: для сторонних библиотек нужен classpath или «толстый» jar через maven-shade-plugin.

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

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

• release (maven.compiler.release) - версия Java: уровень языка, байткод и доступный API JDK. Без него действуют значения плагина по умолчанию: в старых 3.x source/target 1.5-1.7 (на JDK 20+ ошибка Source option 7 is no longer supported), с 3.11.0 - 8, поэтому record не компилируется даже на JDK 25. Минимальное исправление - свойство <maven.compiler.release>25</maven.compiler.release>. Версии с Java 9 пишут без «1.»: <source>1.9</source> из старых примеров устарел.
• encoding - по умолчанию из project.build.sourceEncoding; без него в Maven 3.9.x берётся кодировка платформы с предупреждением.
• compilerArgs - дополнительные опции javac: -parameters (имена параметров методов в байткоде, нужны Spring и Jackson), -Xlint:all.
• annotationProcessorPaths - процессоры аннотаций (Lombok, MapStruct); начиная с JDK 23 процессоры из classpath по умолчанию не запускаются, поэтому их указывают здесь.

Какая версия плагина реально работает, видно в выводе сборки: --- compiler:3.13.0:compile (default-compile) @ shop ---.

• maven-checkstyle-plugin проверяет стиль оформления исходников (отступы, длина строк, Javadoc, «магические числа»). Отчёт - checkstyle:checkstyle, остановка сборки - checkstyle:check. Без настройки действуют правила Sun (sun_checks.xml), второй встроенный набор - google_checks.xml. Отдельные проверки отключают файлом подавлений (suppressionsLocation), где checks и files - регулярные выражения. Плагин 3.6.0 по умолчанию использует Checkstyle 9.3, который не разбирает новый синтаксис Java; его обновляют зависимостью com.puppycrawl.tools:checkstyle внутри плагина.
• maven-pmd-plugin ищет в исходниках подозрительные конструкции (пустой catch, неиспользуемые переменные), а CPD - дубликаты кода. Отчёты pmd:pmd, pmd:cpd подходят для первой оценки проекта, pmd:check и pmd:cpd-check ломают сборку.
• spotbugs-maven-plugin анализирует байткод на шаблоны ошибок (возможный NullPointerException, equals без hashCode). Из командной строки нужна компиляция: mvn compile spotbugs:check. Это преемник FindBugs, который не понимает байткод новее Java 8.

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

Версии этих и других плагинов фиксируют в <plugin> или централизованно в pluginManagement; фактическую версию показывают лог сборки и mvn help:effective-pom, доступные обновления - mvn versions:display-plugin-updates.