Создание Maven-проекта: archetype, структура каталогов и IntelliJ IDEA

Команда из старой инструкции mvn archetype:generate -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 ... отрабатывает без ошибок, но первая же сборка на JDK 21 падает: [ERROR] Source option 7 is no longer supported. Use 8 or later. Шаблон версии 1.4 записал в pom.xml свойства maven.compiler.source и maven.compiler.target со значением 1.7, а современный javac такую версию уже не поддерживает. Сгенерированный проект — это заготовка, которую нужно проверить, и в этом уроке разберём, что именно в ней проверять.

Создать Maven-проект — значит получить каталог с файлом pom.xml (описание проекта и его координат groupId, artifactId, version) и стандартной структурой папок src/main/java, src/test/java и других. Сделать это можно тремя способами: командой mvn archetype:generate по готовому шаблону (archetype), мастером нового проекта в IntelliJ IDEA или вручную — создав pom.xml и каталоги самостоятельно. Результат во всех случаях одинаковый: проект, который собирается командой mvn package.

Способы создать Maven-проект

Maven-проект создают командой mvn archetype:generate (нужен установленный Maven), через мастер New Project в IntelliJ IDEA (Maven встроен в IDE) или вручную: написать pom.xml и создать каталоги. Для учебного консольного приложения все три способа дают почти одинаковый результат; различаются скоростью и тем, сколько лишнего попадает в проект.

Как установить Maven и проверить установку, описано в уроке Как установить Maven на Windows, Linux и macOS. Для способов через IDE отдельная установка не обязательна.

Что такое Maven archetype

Архетип (archetype) в Maven — это шаблон проекта, опубликованный в репозитории как обычный артефакт: он содержит заготовку pom.xml, каталоги и примеры классов. Команда mvn archetype:generate скачивает архетип и создаёт по нему новый проект, подставляя ваши groupId, artifactId, version и имя пакета.

Архетипы бывают официальные (группа org.apache.maven.archetypes) и сторонние — их публикуют авторы фреймворков. Свой архетип можно создать для типовых проектов компании. Самые известные официальные архетипы:

Spring Boot-проекты обычно создают не архетипом, а генератором start.spring.io (Spring Initializr): он тоже выдаёт обычный Maven-проект с pom.xml и той же структурой каталогов.

Команда mvn archetype:generate

Команда mvn archetype:generate запускает цель generate плагина maven-archetype-plugin и создаёт проект в подкаталоге текущей папки (имя подкаталога = artifactId). Она работает в двух режимах: интерактивном — задаёт вопросы в консоли, и пакетном — все параметры передаются через -D одной командой. Запускать её нужно в папке, где ещё нет pom.xml.

Пакетный режим (рекомендуется)

В пакетном режиме (-DinteractiveMode=false) Maven ничего не спрашивает — команду удобно копировать и повторять. Пример для Linux, macOS и Git Bash:

mvn archetype:generate \
  -DarchetypeGroupId=org.apache.maven.archetypes \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DarchetypeVersion=1.5 \
  -DgroupId=com.examclouds \
  -DartifactId=hello-maven \
  -Dversion=1.0-SNAPSHOT \
  -DinteractiveMode=false

В Windows обратная косая черта как перенос строки не работает (в cmd перенос — ^, в PowerShell — обратная кавычка `), поэтому проще записать команду в одну строку. В PowerShell каждый аргумент с -D заключайте в кавычки:

mvn archetype:generate "-DarchetypeGroupId=org.apache.maven.archetypes" "-DarchetypeArtifactId=maven-archetype-quickstart" "-DarchetypeVersion=1.5" "-DgroupId=com.examclouds" "-DartifactId=hello-maven" "-Dversion=1.0-SNAPSHOT" "-DinteractiveMode=false"

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

[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.5
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.examclouds
[INFO] Parameter: artifactId, Value: hello-maven
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.examclouds
...
[INFO] Project created from Archetype in dir: /home/user/hello-maven
[INFO] BUILD SUCCESS

Параметры команды:

Интерактивный режим

Если запустить mvn archetype:generate без параметров, Maven загрузит каталог архетипов и выведет длинный пронумерованный список с приглашением Choose a number or apply filter. Номер по умолчанию указывает на maven-archetype-quickstart, но сами номера меняются при обновлении каталога, поэтому удобнее ввести фильтр, например quickstart. Затем Maven по очереди спросит версию архетипа, groupId, artifactId, version, package и попросит подтвердить параметры (Y). Интерактивный режим удобен, чтобы посмотреть, какие архетипы существуют; для повторяемого результата используйте пакетный.

Что генерирует quickstart и что поправить в pom.xml

Архетип maven-archetype-quickstart создаёт pom.xml, класс App с методом main, который печатает Hello World!, и тест-заглушку AppTest:

hello-maven/
├── pom.xml
└── src/
    ├── main/java/com/examclouds/App.java
    └── test/java/com/examclouds/AppTest.java

Содержимое pom.xml заметно зависит от версии архетипа. Версии до 1.4 включительно используют JUnit 4 (самые старые — даже JUnit 3.8.1) и задают версию Java парой maven.compiler.source/maven.compiler.target со значением 1.7 — с этим JDK 20 и новее уже не компилирует. В версии 1.5 шаблон переведён на JUnit 5 (Jupiter) и свойство maven.compiler.release. После генерации откройте pom.xml и проверьте три вещи:

1. Версия Java. Должно быть одно свойство maven.compiler.release с версией вашего JDK или ниже (например, 17 или 21). Пару source/target замените на release — почему, объяснено в уроке Что такое Maven.
2. Версия JUnit. Если в зависимостях junit:junit 3.x или 4.x, а вы пишете тесты на JUnit 5, замените зависимость на org.junit.jupiter:junit-jupiter со scope = test и поправьте импорты в AppTest.
3. Кодировка. Свойство project.build.sourceEncoding = UTF-8 — без него Maven предупреждает о платформенной кодировке, а сборка на разных ОС может по-разному читать строки с кириллицей.

Блок pluginManagement с фиксированными версиями плагинов, который есть в шаблоне, можно оставить: он делает сборку воспроизводимой. Что означает каждый тег, разобрано в уроке Файл pom.xml в Maven.

Как выбрать groupId, artifactId и version

groupId — это «организация или группа проектов» в формате перевёрнутого доменного имени (com.examclouds), artifactId — имя самого проекта строчными буквами через дефис (hello-maven), version — номер версии; на время разработки к нему добавляют суффикс -SNAPSHOT (1.0-SNAPSHOT). Вместе они образуют координаты проекта, по которым его находят в репозитории.

Архетип по умолчанию берёт имя Java-пакета из groupId, поэтому классы попадут в com/examclouds/. Если в groupId есть дефис или цифра в начале сегмента, сгенерированный пакет не скомпилируется — задайте корректный -Dpackage явно. Из artifactId и version складывается имя готового файла: hello-maven-1.0-SNAPSHOT.jar. Чем SNAPSHOT-версии отличаются от релизных при работе с репозиторием, описано в уроке Файл pom.xml в Maven.

Структура Maven-проекта

Структура Maven-проекта стандартна (Standard Directory Layout): основной код лежит в src/main/java, ресурсы — в src/main/resources, тесты — в src/test/java и src/test/resources, а результат сборки появляется в target. Maven знает эти пути по умолчанию, поэтому указывать их в pom.xml не нужно — достаточно положить файлы в правильное место.

hello-maven/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/examclouds/App.java
│   │   └── resources/
│   │       └── app.properties
│   └── test/
│       ├── java/
│       │   └── com/examclouds/AppTest.java
│       └── resources/
│           └── test-data.json
└── target/                 # created by Maven, do not commit
    ├── classes/
    ├── test-classes/
    └── hello-maven-1.0-SNAPSHOT.jar

Папки внутри src/main/java повторяют пакеты: класс com.examclouds.App лежит в src/main/java/com/examclouds/App.java. Тест для него принято класть в тот же пакет в src/test/java — тогда тесту доступны и package-private члены класса.

Что будет, если положить файл не туда

Maven не ищет файлы по всему проекту: компилятор берёт только .java из каталогов java, а копирование ресурсов — только из resources. Ошибка размещения часто не ломает сборку, а проявляется позже — при запуске или в тестах.

Стандартные пути можно переопределить в pom.xml, но делать это стоит только при переводе на Maven старого проекта, который нельзя реорганизовать. Как это настраивается, показано в уроке Файл pom.xml в Maven.

Maven-проект в IntelliJ IDEA

Чтобы создать Maven-проект в IntelliJ IDEA, откройте мастер нового проекта (File → New → Project), выберите генератор Java с системой сборки Maven или генератор Maven Archetype, укажите имя, расположение, JDK и координаты GroupId/ArtifactId. IDE создаст pom.xml и стандартные каталоги и сразу импортирует проект. Отдельно устанавливать Maven не нужно — он встроен в IDE.

Названия пунктов ниже соответствуют актуальным версиям IntelliJ IDEA (Community и Ultimate); в старых версиях мастер выглядит иначе, но поля те же.

Новый проект: поля мастера

Генератор Java с Build system = Maven обычно создаёт более аккуратный pom.xml, чем старые архетипы: версия Java в нём берётся из выбранного JDK. Сгенерированный файл всё равно стоит просмотреть по списку из раздела про quickstart.

Окно Maven и синхронизация после правки pom.xml

Окно инструментов Maven (обычно на правой боковой панели) показывает проект в виде дерева: Lifecycle — фазы сборки, которые запускаются двойным щелчком (clean, compile, test, package…), Plugins — подключённые плагины и их цели, Dependencies — дерево зависимостей.

IntelliJ IDEA не перечитывает pom.xml на каждое нажатие клавиши. После правки файла в редакторе появляется плавающая кнопка Load Maven Changes (сочетание по умолчанию — Ctrl+Shift+O в Windows и Linux, Cmd+Shift+I в macOS). В окне Maven есть кнопка Reload All Maven Projects с тем же действием. Пока изменения не загружены, новая зависимость подсвечивается красным в коде, хотя в pom.xml она уже есть.

Импорт существующего проекта

Готовый Maven-проект (например, клонированный из Git) открывают через File → Open: выберите файл pom.xml и в диалоге нажмите Open as Project (можно выбрать и папку, в которой лежит pom.xml). IDE сама настроит каталоги исходников, JDK и зависимости. Если pom.xml лежит в подпапке и IDE его не распознала, щёлкните по файлу правой кнопкой и выберите Add as Maven Project.

Встроенный Maven или свой: настройки

Настройки Maven находятся в Settings (в macOS — Preferences) → Build, Execution, Deployment → Build Tools → Maven:

• Maven home path — Bundled (встроенный в IDE) или путь к вашей установке. Укажите свою установку, если нужна та же версия Maven, что в терминале и на CI.
• User settings file и Local repository — путь к settings.xml и к локальному репозиторию (по умолчанию ~/.m2), подробнее — в уроке Виды репозиториев в Maven.
• Подраздел Runner — JDK, на котором запускается Maven, и опция Delegate IDE build/run actions to Maven: при ней кнопки Build и Run выполняются через Maven, а не через собственный сборщик IDE.

Если в проекте есть Maven Wrapper, IDE может использовать его версию Maven — что такое mvnw, описано в уроке Что такое Maven.

Создание Maven-проекта вручную

Вручную Maven-проект создаётся за две минуты: каталог проекта, внутри — pom.xml с координатами и версией Java, и папки src/main/java и src/test/java с подкаталогами пакета. Этим же способом переводят на Maven уже существующий код: исходники переносят в src/main/java, а библиотеки из папки lib заменяют зависимостями в pom.xml.

# Linux, macOS, Git Bash
mkdir -p hello-maven/src/main/java/com/examclouds hello-maven/src/main/resources hello-maven/src/test/java/com/examclouds

# Windows (PowerShell)
New-Item -ItemType Directory -Force hello-maven/src/main/java/com/examclouds, hello-maven/src/main/resources, hello-maven/src/test/java/com/examclouds

В корень hello-maven положите pom.xml — минимальный рабочий вариант из 12 строк приведён в уроке Что такое Maven, а класс с методом main — в src/main/java/com/examclouds:

package com.examclouds;

public class App {
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}

Первая сборка и запуск

Первую сборку проверяют тремя командами в корне проекта (там, где pom.xml): mvn compile компилирует код в target/classes, mvn test дополнительно запускает тесты, mvn package собирает jar в target. Каждая следующая команда выполняет и предыдущие шаги. Первый запуск дольше обычного: Maven скачивает плагины в локальный репозиторий.

cd hello-maven
mvn test

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

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.examclouds.AppTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
...
[INFO] BUILD SUCCESS

mvn package
java -cp target/hello-maven-1.0-SNAPSHOT.jar com.examclouds.App

Вывод:

[INFO] Building jar: /home/user/hello-maven/target/hello-maven-1.0-SNAPSHOT.jar
[INFO] BUILD SUCCESS
Hello World!

Обратите внимание: запуск через java -jar target/hello-maven-1.0-SNAPSHOT.jar завершится ошибкой no main manifest attribute, in target/hello-maven-1.0-SNAPSHOT.jar — архетип не прописывает главный класс в манифест jar. Поэтому класс указывают явно через -cp; как добавить Main-Class в манифест, показано в уроке Использование плагинов в Maven. Если проект использует сторонние библиотеки, их тоже нужно добавить в -cp — обычный jar их не содержит.

Почему mvn package сам выполняет компиляцию и тесты и чем фазы отличаются друг от друга, разобрано в уроке Maven — жизненный цикл сборки. Как запускать Java-программы без Maven, через javac и java, — в уроке Создание и запуск Java-приложения.

На чём чаще всего ошибаются

Большинство проблем при создании первого Maven-проекта связано с тем, где запускается команда, какой JDK использует Maven и в какой каталог положен файл. Ниже — сообщения об ошибках и их исправление.