Guide to Maven Archetype – Maven Archetype指南

最后修改: 2018年 6月 27日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

A Maven archetype is an abstraction of a kind of a project that can be instantiated into a concrete customized Maven project. In short, it’s a template project template from which other projects are created.

Maven原型是一种项目的抽象，可以被实例化为具体的定制Maven项目。简而言之，它是一个项目模板，其他项目就是根据它创建的。

The main benefit of using archetypes is to standardize project development and to enable developers to easily follow best practices while bootstrapping their projects faster.

使用原型的主要好处是使项目开发标准化，使开发人员能够轻松地遵循最佳实践，同时更快地启动他们的项目。

In this tutorial, we’ll look at how to create a custom archetype and then how to use it to generate a Maven project through the maven-archetype-plugin.

在本教程中，我们将了解如何创建一个自定义原型，然后通过maven-archetype-plugin使用它来生成一个Maven项目。

2. Maven Archetype Descriptor

2.Maven Archetype描述符

The Maven archetype descriptor is the heart of the archetype project. It’s an XML file named archetype-metadata.xml and located in the META-INF/maven directory of the jar.

Maven原型描述符是原型项目的核心。它是一个名为archetype-metadata.xml的XML文件，位于jar的META-INF/maven目录下。

It’s used to describe archetypes’ metadata:

它是用来描述原型的元数据的。

<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>

The requiredProperties tag is used for providing properties during project generation. Thus, we’ll be prompted to provide values for them, with the choice to accept the default value.

requiredProperties标签用于在项目生成期间提供属性。因此，我们将被提示为它们提供值，并可选择接受默认值。

fileSets, on the other hand, are used to configure which resources will be copied into the concrete generated project. A filtered file means that placeholders will be substituted with provided values during the generation process.

另一方面，fileSets,被用来配置哪些资源将被复制到具体生成的项目中。一个过滤的文件意味着在生成过程中，占位符将被替换为所提供的值。

And, by using packaged=”true” in the fileSet, we’re saying that selected files will be added to the folder hierarchy specified by the package property.

而且，通过在fileSet中使用packaged=”true”，我们表示所选文件将被添加到package属性所指定的文件夹层次中。

If we want to generate a multi-module project, then the tag modules can help to configure all modules of the generated project.

如果我们想生成一个多模块的项目，那么标签modules可以帮助配置生成项目的所有模块。

Note that this file is about Archetype 2 and above. In the version 1.0.x, the file was just called archetype.xml and it had a different structure.

请注意，这个文件是关于Archetype 2及以上版本的。在1.0.x版本中，该文件只是被称为archetype.xml，它有一个不同的结构。

For more information, definitely have a look at the official Apache docs.

欲了解更多信息，一定要看一看Apache官方文档。

3. How to Create an Archetype

3.如何创建一个原型

An archetype is a normal Maven project with the following extra content:

原型是一个普通的Maven项目，有以下额外内容。

  • src/main/resources/archetype-resources is the template from which resources are copied to the newly created project
  • src/main/resources/META-INF/maven/archetype-metadata.xml: is the descriptor used to describe archetypes’ metadata

To create an archetype manually, we can start with a newly created Maven project and then we can add the resources mentioned above.

要手动创建一个原型，我们可以从一个新创建的Maven项目开始，然后再添加上述资源。

Or, we can generate it by using the archetype-maven-plugin, and then customize the content of the archetype-resources directory and archetype-metadata.xml file.

或者，我们可以通过使用archetype-maven-plugin生成它，然后自定义archetype-resources目录和archetype-metadata.xml文件的内容。

To generate the archetype, we can use:

为了生成原型，我们可以使用。

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

We can also create the archetype from an existing Maven project:

我们也可以从一个现有的Maven项目中创建原型。

mvn archetype:create-from-project

It’s generated in target/generated-sources/archetype, ready to be used.

它在target/generated-sources/archetype中生成，准备好被使用。

No matter how we’ve created the archetype, we’ll end up with the following structure:

无论我们如何创建原型，我们最终都会有以下结构。

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

We can now start building our archetype by putting resources in the archetype-resources directory and configuring them in the archetype-metadata.xml file.

现在我们可以开始构建我们的原型，把资源放在archetype-resources目录下，并在archetype-metadata.xml文件中配置它们。

4. Building the Archetype

4.建立原型

Now we’re ready to customize our archetype. For the highlight of this process, we’re going to showcase the creation of a simple Maven archetype for generating a RESTful application based on JAX-RS 2.1.

现在我们准备定制我们的原型了。为了突出这一过程，我们将展示创建一个简单的Maven原型，用于生成一个基于JAX-RS 2.1的RESTful应用程序。

Let’s just call it maven-archetype.

我们就叫它maven-archetype吧。

4.1. Archetype Packaging

4.1.Archetype包装

Let’s start by modifying the pom.xml of the archetype project located under the maven-archetype directory:

我们先修改位于maven-archetype目录下的原型项目的pom.xml。

<packaging>maven-archetype</packaging>

This type of packaging is available thanks to the archetype-packaging extension:

由于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. Adding the pom.xml

4.2.添加pom.xml

Let’s now create a pom.xml file located under the archetype-resources directory:

现在让我们创建一个pom.xml文件，位于archetype-resources目录下。

<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>

As we can see, groupId, artifactId and version are parameterized. They will be replaced during the creation of a new project from this archetype.

我们可以看到，groupId、artifactId和version是参数化的。它们将在创建这个原型的新项目时被替换。

We can put everything needed by the generated project, like dependencies and plugins, in the pom.xml. Here, we’ve added the JAX RS dependency as the archetype will be used for generating RESTful based application.

我们可以在pom.xml中放入生成项目所需的一切，如依赖和插件。在这里，我们添加了JAX RS依赖项，因为原型将用于生成基于RESTful的应用程序。

4.3. Adding Required Resources

4.3.添加所需资源

Next, we can add some Java code for our application in archetype-resources/src/main/java.

接下来，我们可以在archetype-resources/src/main/java中为我们的应用程序添加一些Java代码。

A class for configuring JAX-RS application:

一个用于配置JAX-RS应用程序的类。

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

And a class for a ping resource:

还有一个PING资源的类。

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

Finally, put the server configuration file, server.xml, in archetype-resources/src/main/config/liberty.

最后，将服务器配置文件server.xml放入archetype-resources/src/main/config/liberty。

4.4. Configuring Metadata

4.4.配置元数据

After adding all needed resources, we can now configure which ones will be copied during generation through the archetype-metadata.xml file.

在添加了所有需要的资源后，我们现在可以通过archetype-metadata.xml文件配置哪些资源将在生成过程中被复制。

We can tell our archetype that we want all Java source files to be copied:

我们可以告诉我们的原型，我们希望所有的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>

Here, we want all Java files from src/main/java directory, and the server.xml file from src/main/config/liberty, to be copied.

这里，我们希望复制src/main/java目录中的所有Java文件，以及src/main/config/liberty,中的server.xml文件。

4.5. Installing the Archetype

4.5.安装Archetype

Now that we’ve finished putting it all together, we can install the archetype by invoking this command:

现在我们已经完成了所有的组装，我们可以通过调用这个命令来安装原型。

mvn install

At this point, the archetype is registered in the file archetype-catalog.xml, located in Maven local repository, and therefore ready for use.

此时，原型已在位于Maven本地资源库的archetype-catalog.xml文件中注册，因此可以使用了。

5. Using the Installed Archetype

5.使用已安装的原型

The maven-archetype-plugin allows the user to create a Maven project through the generate goal and existing archetype. For more information on this plugin, you can visit the homepage.

maven-archetype-plugin允许用户通过generate目标和现有原型创建一个Maven项目。关于这个插件的更多信息，您可以访问主页。

This command uses this plugin to generate a Maven project from our archetype:

该命令使用该插件，从我们的原型生成一个Maven项目。

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

We should then pass the GAV of our archetype as arguments to the maven-archetype-plugin:generate goal. We can also pass the GAV of the concrete project that we want to generate, otherwise, we can provide them in interactive mode.

然后我们应该把原型的GAV作为参数传递给maven-archetype-plugin:generate目标。我们也可以传递我们想要生成的具体项目的GAV，否则，我们可以在交互模式下提供它们。

The concrete cool-jaxrs-sample generated project is therefore ready to run without any changes. So, we can run it by just invoking this command:

因此，具体的cool-jaxrs-sample生成的项目无需任何修改就可以运行。所以，我们可以通过调用这个命令来运行它。

mvn package liberty:run

We can then access this URL:

然后我们可以访问这个URL。

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

6. Conclusion

6.结论

In this article, we’ve showcased how to build and use a Maven archetype.

在这篇文章中，我们展示了如何构建和使用Maven原型。

We’ve demonstrated how to create the archetype and then how to configure the template resources through the archetype-metadata.xml file.

我们已经演示了如何创建原型，然后如何通过archetype-metadata.xml文件配置模板资源。

The code, as usual, can be found over on Github.

像往常一样，代码可以在Github上找到over。