Maven Archetype 打造專屬項目模板：從創建原型到 Nexus 發布與 IDE 整合全流程

為什麼需要自定義 Archetype？

團隊統一技術棧、規範目錄結構、內置公共依賴與配置，新項目「一鍵生成」即可進入業務開發，避免重複複製粘貼、版本不一致、配置遺漏等低級錯誤。

完整構建流程

第 1 步：創建種子項目

• mvn archetype:generate -DarchetypeArtifactId=maven-archetype-webapp 或 IDE 新建 Maven Web 項目
• 關鍵命名：artifactId 用複雜唯一名（如 shiro-auth-template），防止後續替換誤傷依賴坐標
• 編碼強制 UTF-8：pom.xml 首行聲明 <properties><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding></properties>

第 2 步：植入業務基因

在種子項目中完成：

• 公共依賴鎖定版本
• 統一配置文件
• 基礎工具類、異常體系、攔截器
• CI/CD 腳本、Dockerfile 模板

第 3 步：生成原型元數據

mvn archetype:create-from-project
# 產物在 target/generated-sources/archetype/

第 4 步：完善原型 POM

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.team</groupId>
  <artifactId>project-archetype</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>maven-archetype</packaging>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <distributionManagement>
    <snapshotRepository>
      <id>nexus-snapshots</id>
      <url>https://nexus:8081/repository/maven-snapshots/</url>
    </snapshotRepository>
    <repository>
      <id>nexus-releases</id>
      <url>https://nexus:8081/repository/maven-releases/</url>
    </repository>
  </distributionManagement>
</project>

第 5 步：發布到 Nexus

cd target/generated-sources/archetype
mvn clean deploy
# 或 mvn deploy -DskipTests

第 6 步：IDE 整合遠程目錄

1. Eclipse/IDEA: Preferences → Maven → Archetypes → Add Remote Catalog
2. Catalog URL: https://nexus:8081/repository/maven-public/archetype-catalog.xml
3. 勾選 Include snapshot archetypes

第 7 步：基於原型創建新項目

File → New → Maven Project → 選擇剛添加的 Catalog → 選擇 archetype → 填寫新項目 GAV

兩大避坑指南（血淚總結）

進階：動態參數與文件過濾

在 src/main/resources/META-INF/maven/archetype-metadata.xml 中配置：

<archetype-descriptor>
  <requiredProperties>
    <requiredProperty key="database">
      <defaultValue>mysql</defaultValue>
    </requiredProperty>
  </requiredProperties>
  <fileSets>
    <fileSet filtered="true" packaged="true">
      <directory>src/main/java</directory>
      <includes><include>**/*.java</include></includes>
      <excludes><exclude>**/Test*.java</exclude></excludes>
    </fileSet>
    <fileSet filtered="false" packaged="false">
      <directory>src/main/resources</directory>
    </fileSet>
  </fileSets>
</archetype-descriptor>

• filtered="true"：啟用 Velocity 模板變量替換
• packaged="true"：根據新項目 groupId 自動調整包路徑
• requiredProperties：交互式提示用戶輸入，支持下拉選項

最佳實踐檢查清單

1. 種子項目可獨立構建運行（mvn clean package 通過）
2. 原型發布前本地測試：mvn archetype:generate -DarchetypeCatalog=local
3. 版本號遵循語義化：1.0.0-RELEASE / 1.1.0-SNAPSHOT
4. 文檔化：README.md 說明原型包含內容、適用場景、升級指引
5. 定期同步技術棧升級：Spring Boot、依賴版本、安全基線

投入半天構建優質 Archetype，節省每個新項目半天啟動時間，長期收益極高。核心心法：種子項目要乾淨、命名要獨特、編碼要統一、發布要自動化。