创建Maven Archetype

介绍

我们使用的Java构建工具主要是Maven，而maven往往需要冗长的配置。尤其对于相似度较高的项目，我们往往会觉得一直在做重复的工作，很乏味。

为此，我们可以构建一套模版，每次需要创建一个新的项目，就从这个模版中"制造"出一个工程（create from template），而不是从头写（create from scratch）。

Maven archetype就是这样一种"模版"构建技术，它背后基于Velocity，来实现模版变量的处理和替换，从而达到生成目标工程的目的。

实现方案

构建一个Maven Archetype，可以从头创建，也可以基于现有的一个Maven项目创建。

从头创建

👉maven.apache.org/guides/mini...

对于简单的maven archetype，我们可以选择这种方式来创建，优点是简单方便无污染，只包含自己想要的。缺点则是需要一定的学习成本，需要对archetype的原理有较好的掌握。

创建的步骤如下：

1）生成初版archetype

mvn archetype:generate \
  -DgroupId=com.dadaer.archetype \
  -DartifactId=simple-archetype \
  -Dversion=1.0.0 \
  -DarchetypeGroupId=org.apache.maven.archetypes \
  -DarchetypeArtifactId=maven-archetype-archetype

使用上述命令，进入一个交互式的cmd界面，我们只需要提供一些必要的值，就可以生成一个叫做simple-archetype的archetype项目，它的groupId是com.dadaer.archetype，artifactId是simple-archetype，version是1.0.0。

同时也可以看到，上面的命令其实就是根据一个archetype生成了了另一个archetype

2）定制化archetype

接下来，我们就可以根据自己的需要来定制化Archeytyple（详见下文）。

从已有项目创建

👉maven.apache.org/archetype/m...

对于较为复杂的archetype项目，我们可以选择这种方式来创建。这种方式需要经历如下几个步骤。

为了准确生成多模块项目的archetype，已有项目必须符合一定的命名规则，即：子模块的名字一定要以父模块为前缀，比如下面这样：

msa-sample
   +-- msa-sample-service-provider
   +-- msa-sample-library-client
   +-- msa-sample-library-idl

1）基于已有项目生成初版archetype

• 新建一个archetype.properties文件，内容类似下面：

  archetype.groupId=com.dadaer.archetype
  archetype.artifactId=msa-sample-archetype
  archetype.version=1.0.0
  archetype.filteredExtensions=java,proto,yml,xml,properties,md
  capitalProjectName=Sample
  projectBaseName=sample

  其中，archetype.xxx是maven内置的属性，根据需要指定想要的值即可，这里的设置表明：

  • 新生成的archetype的GAV将会是：com.dadaer.archetype:msa-sample-archetype:1.0.0
  • 要过滤的文件包括java、proto、yml、xml和properties文件

• 进入已有Maven项目的根目录，执行下面的命令

  mvn archetype:create-from-project \
    -Darchetype.properties=/path/to/archetype.properties

  这个命令会分析已有项目的pom.xml文件以及所有的源代码文件，并生成一个可以工作的archetype。基于这个archetype，我们可以根据自己的需要做定制。

2）拷贝target/generated-sources/archetype目录到新的目录

cp -r target/generated-sources/archetype /path/to/msa-sample-archetype

上面的命令，假设我们要把整个目录target/generated-sources/archetype拷贝到/path/to/msa-sample-archetype目录。并且新的archetype名字就是msa-sample-archetype。

3）定制化archetype

在新的目录下，我们就可以根据自己的需要来定制化archetype了（详见下文）。

定制化archetype

无论以何种方式生成了初版的archetype，我们都有定制化的需求，这个章节主要介绍定制化的大致过程。

定制化的点

👉maven.apache.org/archetype/m...

1）调整archetype-metadata.xml文件

使用上述命令生成的archetype中，包含了一些项目之外的文件集（主要是IDE工具相关的文件集），需要把这些文件集删除

2）修改markdown等文本文件

• 文本文件中，使用变量（$rootArtifactId}）来替换模块引用的地方
• 修改SPI文件中的类名
• 处理Entity中的表名，不要被替换

3）后置脚本

编写groovy的后置脚本来处理一些archetype不能不能做到的事情，比如：

• .gitignore文件不会被写到archetype生成的项目中（可能archetype的一个bug？）
• archetype生成的顶级pom.xml文件中，内容的空行很大

使用maven archetype

环境准备

从Maven Archetype3.0版本以上，不再支持通过属性（-DarchetypeRepository）来指定archetype仓库，因此，必须在settings.xml文件中指定名字为archetype的repository。

详情请参考👉maven.apache.org/archetype/m...

修改本地的settings.xml文件，增加archetype的profile来指定你的私服作为archetype的catalog。

<profiles>
  <!-- 拷贝下面的3-11行到profiles标签里面 -->
  <profile>
    <id>archetype</id>
    <repositories>
      <repository>
        <id>archetype</id>
        <url>https://...</url>
      </repository>
    </repositories>
  </profile>
</profiles>
 
<activeProfiles>
  <!-- 拷贝下面的一行到activeProfiles标签里面 -->
  <activeProfile>archetype</activeProfile>
</activeProfiles>

通过命令行使用archetype

生成maven项目的命令

使用下面的命令生成一个项目：

mvn archetype:generate \
    -B \
    -DarchetypeGroupId=com.dadaer.archetype \
    -DarchetypeArtifactId=msa-sample-archetype \
    -DarchetypeVersion=1.0.0 \
    -DgroupId=com.dadaer.demo \
    -DartifactId=msa-sample-demo \
    -Dversion=0.0.1 \
    -Dpackage=com.dadaer.demo.sample \
    -DprojectBaseName=sample \
    -DcapitalProjectName=Sample \
    -DrestPort=8081

上述命令，根据archetype（com.dadaer.archetype:msa-sample-archetype:1.0.0）生成一个新的Maven工程，这个工程的GAV是：com.dadaer.demo:msa-sample-demo:0.0.1，生成的包名：com.dadaer.demo.sample。

结论

使用Maven Archetype，可以让您构建具有统一模版的工程，利于代码结构的规范化，并可以在工程中应用最佳实践。