自定义 Archetype

自定义 Archetype

项目地址 custom-maven-archetype
Archetype 可以看作是 maven 项目的模版，通过 archetype 可以快速生成一个项目骨架，例如常用的 maven-archetype-quickstart 和 maven-archetype-webapp 是 maven 官方提供的模版，使用 archetype 创建项目时，只需要提供一些基本的信息（比如 groupId、artifactId、version 等），它就能生成项目的基本结构和 pom 文件。

下面我们来介绍一下如何自定义创建一个 archetype。

编写 Archetype

一个典型的 archetype maven 项目主要包括以下几个部分：

• pom.xml: Archetype 自身的 pom

• src/main/resources/archetype-resources: 基于该 Archtype 生成的项目的 pom 原型

• src/main/resources/META-INF/maven/archetype-metadata.xml: Archetype 的描述符文件

• src/main/resources/archetype-resources/**: 其它需要包含在 archetype 中的内容

编写 Archetype 项目时，首先要定义好其要包含的目录和文件，比如下面是本 archetype 项目的目录结构。

src/main/resources/archetype-resources/pom.xml 是该 archetype 项目生成的 pom 原型，在这里定义好项目的基本配置，项目生成时，这些配置就是现成的了。注意 groupId、artifactId、version 和 name 等属性并没有直接声明，而是采用了属性声明的方式，如下所示

<groupId>${groupId}</groupId>  
<artifactId>${artifactId}</artifactId>  
<version>${version}</version>  
<name>${artifactId}</name>

使用 archetype 生成项目时，用户一般会提供这些信息，项目生成后，这些属性会被填充。

一个 archetype 项目的核心部分是 archetype-metadata.xml 描述符文件，它位于 archetype 项目的资源目录下的 META-INF/maven 目录下。它主要做两件事：

1. 声明哪些目录和文件应包含在 archetype 中

2. 这个 archetype 使用哪些属性参数

下面是本 archetype 项目的 archetype-metadata.xml 的内容

<?xml version="1.0" encoding="UTF-8"?>
<arche-type-descriptor name="myarchetype">
    <fileSets>
        <fileSet filtered="true" packaged="true">
            <directory>src/main/java</directory>
            <includes>
                <include>**/*.java</include>
            </includes>
        </fileSet>
        <fileSet filtered="true" packaged="true">
            <directory>src/test/java</directory>
            <includes>
                <include>**/*.java</include>
            </includes>
        </fileSet>
        <fileSet filtered="true" packaged="false">
            <directory>src/main/resources</directory>
            <includes>
                <include>**/*.properties</include>
            </includes>
        </fileSet>
    </fileSets>
    <requiredProperties>
        <requiredProperty key="port"/>
        <requiredProperty key="groupId">
            <defaultValue>wyn</defaultValue>
        </requiredProperty>
    </requiredProperties>
</arche-type-descriptor>

它主要包含 fileSets 和 requiredPropeties 两个部分，其中 fileSets 包含多个 fileSet 子元素，每个 fileSet 定义一个目录以及该目录的包含和排除规则。

上述代码片段中第一个 fileSet 指向的目录是 src/main/java，该目录对应于 archetype 项目的资源目录的 archetype-resources/src/main/java 子目录。fileSet 元素有两个属性，其中 filtered 表示是否对该文件集合应用属性替换。例如像 ${x}这样的值是否替换为命令输入的 x 参数的值；packaged 表示是否在该目录下创建包路径。

fileSet 包含了 includes 元素，其中声明了一个值为 **/*.java 的规则，表示包含 src/main/java 中任意路径下的 java 文件。处理 includes,你也可以使用 excludes 元素声明排除规则。

默认情况下，maven-archetype-plugin 插件要求用户在使用 archetype 生成项目时，必须提供 groupId、artifactId、version 和 package。除此之外，用户在编写自定义 archetype 时，可以要求提供额外的参数。例如上述代码片段中，使用 requiredProperties 配置要求提供 port 参数，并且为 groupId 提供了一个默认值 wyn。这样，archetype 中所有开启 filtered 的文件中就可以使用 ${port} 属性声明，然后项目生成时使用命令行输入的值填充。

假设使用该 archetype 项目生成项目，用户输入的 groupId、artifactId 和 version 分别为：cn.wxy、demo、1.0.0-SNAPSHOT，下表表示了该 archetype 中的文件与生成项目的文件对应关系

项目生成后，打开 App.java、Dao.java、Service.java，可以看到
{package}** 被替换为cn.wxy.demo, **{port} 被替换为用户输入的值。

最后，不要忘了将我们自定义的 archetype 项目安装到本地仓库中，执行 mvn clean install 将其安装到本地仓库。

如果你有自己的远程仓库，可以执行 mvn depoly 将自定义的 archetype 部署到远程仓库。

使用自定义的 archetype 创建项目

将自定义的 archetype 项目安装到本地仓库后，我们便可以使用该 archetype 创建项目了。

在命令行下执行下述命令，

mvn archetype:generate -DarchetypeGroupId=wyn -DarchetypeArtifactId=myarchetype -DarchetypeVersion=1.0

然后输入 artifactId、version、port，以交互的方式创建项目。

生成 Archetype Catalog

使用 archetype 创建项目时，一般不需要精确指定 archetype 的坐标信息，maven-archtype-plugin 会提供一个 archetype 列表供用户选择。该列表的信息来源一个叫 archetype-catalog.xml 的文件。

那么能否把我们自定义的 archetype 加入到这个列表中呢？答案是肯定的。

maven-archetype-plugin 提供了一个 crawl 的 goal，用户可以使用它来遍历本地 maven 仓库，生成一个 archetype-catalog.xml 文件（该文件位于本地仓库的根目录下，默认是~/.m2/repository 目录，其中~表示用户目录）。

进入当前 archetype 项目的根目录下，执行 mvn archetype:crawl 命令，在本地仓库的根目录下生成 archetype-catalog.xml 文件。

然后，我们在执行 mvn archetype:generator 命令生成的新项目时，就可以看到我们自定义的 archetype。