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

Руководство по архетипу Maven

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

1. Обзор​

Архетип Maven — это абстракция своего рода проекта, который может быть воплощен в конкретный индивидуальный проект Maven. Короче говоря, это шаблонный шаблон проекта, из которого создаются другие проекты .

Основным преимуществом использования архетипов является стандартизация разработки проектов и предоставление разработчикам возможности легко следовать передовым методам при более быстрой загрузке своих проектов.

В этом руководстве мы рассмотрим, как создать собственный архетип, а затем как использовать его для создания проекта Maven с помощью плагина maven-archetype-plugin.

2. Дескриптор архетипа Maven​

Дескриптор архетипа Maven является сердцем проекта архетипа . Это XML-файл с именем archetype-metadata.xml, расположенный в каталоге META-INF/maven jar-файла.

Он используется для описания метаданных архетипов:

<archetype-descriptor
  ...
  name="custom-archetype">

    <requiredProperties>
        <requiredProperty key="foo">
            <defaultValue>bar</defaultValue>
        </requiredProperty>
    </requiredProperties>

    <fileSets>
        <fileSet filtered="true" packaged="true">
            <directory>src/main/java</directory>
            <includes>
                <include>**/*.java</include>
            </includes>
        </fileSet>
    </fileSets>

    <modules>
        <module name="sub-module"></module>
    </modules>

</archetype-descriptor>

Тег requiredProperties используется для предоставления свойств во время создания проекта. Таким образом, нам будет предложено указать для них значения с возможностью принять значение по умолчанию.

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

И, используя packaged ="true" в наборе файлов , мы говорим, что выбранные файлы будут добавлены в иерархию папок, указанную свойством пакета .

Если мы хотим сгенерировать многомодульный проект, то теговые модули могут помочь настроить все модули сгенерированного проекта.

Обратите внимание, что этот файл относится к архетипу 2 и выше. В версии 1.0.x файл назывался просто archetype.xml и имел другую структуру.

Для получения дополнительной информации обязательно ознакомьтесь с официальной документацией Apache .

3. Как создать архетип​

Архетип — это обычный проект Maven со следующим дополнительным содержимым :

  • src/main/resources/archetype-resources — это шаблон, из которого ресурсы копируются во вновь созданный проект.
  • src/main/resources/META-INF/maven/archetype-metadata.xml : это дескриптор, используемый для описания метаданных архетипов.

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

Или мы можем сгенерировать его с помощью плагина archetype-maven-plugin, а затем настроить содержимое каталога archetype-resources и файла archetype-metadata.xml .

Для создания архетипа мы можем использовать:

mvn archetype:generate -B -DarchetypeArtifactId=maven-archetype-archetype \
  -DarchetypeGroupId=maven-archetype \
  -DgroupId=com.foreach \
  -DartifactId=test-archetype

Мы также можем создать архетип из существующего проекта Maven:

mvn archetype:create-from-project

Он сгенерирован в target/generated-sources/archetype и готов к использованию.

Независимо от того, как мы создали архетип, в итоге мы получим следующую структуру:

archetype-root/
├── pom.xml
└── src
    └── main
        ├── java
        └── resources
            ├── archetype-resources
            │   ├── pom.xml
            │   └── src
            └── META-INF
                └── maven
                    └── archetype-metadata.xml

Теперь мы можем приступить к созданию нашего архетипа, поместив ресурсы в каталог archetype-resources и настроив их в файле archetype-metadata.xml .

4. Создание архетипа​

Теперь мы готовы настроить наш архетип. В качестве изюминки этого процесса мы продемонстрируем создание простого архетипа Maven для создания приложения RESTful на основе JAX-RS 2.1.

Назовем его просто maven-archetype .

4.1. Упаковка архетипа​

Начнем с изменения pom.xml проекта архетипа, расположенного в каталоге maven-archetype :

<packaging>maven-archetype</packaging>

Этот тип упаковки доступен благодаря расширению archetype-packaging : 

<build>
    <extensions>
        <extension>
            <groupId>org.apache.maven.archetype</groupId>
            <artifactId>archetype-packaging</artifactId>
            <version>3.0.1</version>
        </extension>
    </extensions>
    <!--....-->
</build>

4.2. Добавление pom.xml​

Давайте теперь создадим файл pom.xml , расположенный в каталоге ресурсов-архетипов :

<project ...>

    <groupId>${groupId}</groupId>
    <artifactId>${artifactId}</artifactId>
    <version>${version}</version>
    <packaging>war</packaging>

    <dependencies>
        <dependency>
            <groupId>javax.ws.rs</groupId>
            <artifactId>javax.ws.rs-api</artifactId>
            <version>2.1</version>
            <scope>provided</scope>
        </dependency>        
    </dependencies>

</project>

Как мы видим, groupId, ArtiftId и версия параметризованы. Они будут заменены при создании нового проекта из этого архетипа.

Мы можем поместить все необходимое для сгенерированного проекта, например, зависимости и плагины, в pom.xml . Здесь мы добавили зависимость JAX RS, поскольку архетип будет использоваться для создания приложения на основе RESTful.

4.3. Добавление необходимых ресурсов​

Затем мы можем добавить код Java для нашего приложения в archetype-resources/src/main/java .

Класс для настройки приложения JAX-RS:

package ${package};
// import
@ApplicationPath("${app-path}")
public class AppConfig extends Application {
}

И класс для пинг-ресурса:

@Path("ping")
public class PingResource{
    //...
}

Наконец, поместите файл конфигурации сервера, server.xml , в archetype-resources/src/main/config/liberty .

4.4. Настройка метаданных​

После добавления всех необходимых ресурсов теперь мы можем настроить, какие из них будут скопированы во время генерации через файл archetype-metadata.xml .

Мы можем указать нашему архетипу, что мы хотим, чтобы все исходные файлы Java были скопированы:

<archetype-descriptor
  name="maven-archetype">
    
    <!--...-->
    <fileSets>
        <fileSet filtered="true" packaged="true">
            <directory>src/main/java</directory>
            <includes>
                <include>**/*.java</include>
            </includes>
        </fileSet>
        <fileSet>
            <directory>src/main/config/liberty</directory>
            <includes>
                <include>server.xml</include>
            </includes>
        </fileSet>
    </fileSets>

</archetype-descriptor>

Здесь мы хотим, чтобы все файлы Java из каталога src/main/java и файл server.xml из каталога src/main/config/liberty были скопированы.

4.5. Установка архетипа​

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

mvn install

На данный момент архетип регистрируется в файле archetype-catalog.xml, расположенном в локальном репозитории Maven, и поэтому готов к использованию.

5. Использование установленного архетипа​

Плагин maven-archetype-plugin позволяет пользователю создать проект Maven с помощью цели generate и существующего архетипа . Для получения дополнительной информации об этом плагине вы можете посетить домашнюю страницу .

Эта команда использует этот плагин для создания проекта Maven из нашего архетипа:

mvn archetype:generate -DarchetypeGroupId=com.foreach.archetypes
                       -DarchetypeArtifactId=maven-archetype
                       -DarchetypeVersion=1.0-SNAPSHOT
                       -DgroupId=com.foreach.restful
                       -DartifactId=cool-jaxrs-sample
                       -Dversion=1.0-SNAPSHOT

Затем мы должны передать GAV нашего архетипа в качестве аргументов цели maven-archetype-plugin:generate . Мы также можем передать GAV конкретного проекта, который мы хотим сгенерировать, в противном случае мы можем предоставить их в интерактивном режиме.

Таким образом, конкретный сгенерированный проект cool-jaxrs-sample готов к запуску без каких-либо изменений. Итак, мы можем запустить его, просто вызвав эту команду:

mvn package liberty:run

Затем мы можем получить доступ к этому URL:

http://localhost:9080/cool-jaxrs-sample/<app-path>/ping

6. Заключение​

В этой статье мы показали, как создать и использовать архетип Maven.

Мы продемонстрировали, как создать архетип, а затем настроить ресурсы шаблона с помощью файла archetype-metadata.xml .

Код, как обычно, можно найти на Github .