Eclipse Maven 多模組教學：建立 Parent、Module 與 POM

在 Eclipse 建立一般 Maven Project 不難，但當專案要拆成 Web、共用工具或其他功能模組時，父 POM、Module 與模組相依關係就容易混在一起。這篇沿用 Eclipse 的 Maven Project／Maven Module 操作流程，從父專案開始，建立一個 Web 模組與一個共用 JAR 模組，最後確認整個多模組專案能一起建置。

demo-parent/
├─ pom.xml                 # packaging=pom，聚合全部模組
├─ demo-web/
│  └─ pom.xml              # jar 或 war，依部署方式決定
└─ demo-common/
   └─ pom.xml              # jar，共用工具或領域程式碼

開始前先確認 Eclipse 與 Maven 環境

Eclipse 需要安裝 Maven Integration for Eclipse（m2e）。Eclipse m2e 官方說明指出，它會在 IDE 中提供 Maven 建置、依據 pom.xml 管理 classpath、解析工作區模組依賴，以及建立 Maven 專案的精靈。

• 電腦已安裝可用的 JDK，而不只是 JRE。
• Eclipse 可在 File → New → Other… → Maven 看到 Maven Project 等精靈。
• 可在 Window → Preferences → Maven → Installations 檢查 Eclipse 使用的 Maven。
• 可在 Window → Preferences → Maven → User Settings 確認 settings.xml 與本機儲存庫位置。

如果 Maven 選單不存在，先確認目前 Eclipse 套件是否包含 m2e，再依 Eclipse m2e 官方頁面的安裝方式補上整合套件。

步驟一：建立父 Maven Project

1. 開啟 Maven Project 精靈

依序選擇 File → New → Other… → Maven → Maven Project。不同 Eclipse 版本的選單文字可能略有差異，但核心仍是 Maven Project 精靈。

2. 建立簡單的 Maven 專案

勾選 Create a simple project (skip archetype selection)，讓精靈直接建立基本 pom.xml。這個教學不依賴特定 archetype，因此跳過 archetype 比較容易看清楚父子 POM 關係。

3. 填寫 Maven 座標並選擇 pom packaging

• Group Id：通常採反向網域命名，例如 com.example。com、org 或 idv 是命名慣例，不是 Maven 強制的組織類型限制。
• Artifact Id：父專案名稱，例如 demo-parent。
• Version：可先使用 1.0.0-SNAPSHOT。
• Packaging：父專案選擇 pom，因為它的工作是聚合模組與提供共用設定，不產生 JAR 或 WAR。

按下 Finish 後，父專案的核心是 pom.xml。若精靈產生空的 src 資料夾，可在確認沒有程式碼後移除；不要對已有內容的專案直接刪除來源目錄。

4. 檢查父 POM

Apache Maven 官方文件把「聚合」與「繼承」分開說明：父 POM 以 <modules> 知道要建置哪些子目錄；子模組以 <parent> 繼承 groupId、version、dependencyManagement 或 pluginManagement。實務上常讓同一份父 POM 同時負責兩者。

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>demo-parent</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>pom</packaging>

  <modules>
    <module>demo-web</module>
    <module>demo-common</module>
  </modules>
</project>

可參考 Apache Maven：Introduction to the POM 的 Project Aggregation 與 Project Inheritance 章節。

步驟二：建立第一個 Maven Module

1. 從父專案新增 Maven Module

在剛建立的父專案上按右鍵，選擇 New → Other… → Maven → Maven Module。若右鍵選單沒有顯示，也可以從 File 選單開啟相同精靈。

在精靈中指定 Module Name，例如 demo-web，並確認 Parent Project 指向剛才的 demo-parent。同樣可勾選 Create a simple project，避免 archetype 帶入額外設定。

2. 依部署方式選擇 jar 或 war

原流程把網站模組設為 war，這在傳統 Servlet／JSP 專案、需要部署到外部 Tomcat 等 Servlet 容器時仍適用。但多數 Spring Boot 應用使用可執行 jar；共用函式庫也應使用 jar。不要只因為模組提供 HTTP API 就一律選 war。

建立完成後，Eclipse 會在父專案底下顯示模組。父 POM 通常會自動加入 <module>demo-web</module>，子模組 POM 也會包含父專案座標；仍建議手動檢查兩邊是否一致。

3. 檢查子模組的 parent

<parent>
  <groupId>com.example</groupId>
  <artifactId>demo-parent</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <relativePath>../pom.xml</relativePath>
</parent>

<artifactId>demo-web</artifactId>
<packaging>jar</packaging>

relativePath 是從子模組 POM 指向父 POM 的相對路徑。採用標準目錄結構時，預設的 ../pom.xml 通常即可。

步驟三：建立共用 JAR Module

若還需要放共用工具、DTO 或領域程式碼，可再次在父專案新增 Maven Module，例如 demo-common。操作方式與前一個模組相同，但 Packaging 選擇 jar。

讓 Web 模組使用共用模組

「放在同一個父專案底下」不代表程式碼可以自動互相引用。若 demo-web 要使用 demo-common，還要在 demo-web/pom.xml 加入依賴：

<dependency>
  <groupId>com.example</groupId>
  <artifactId>demo-common</artifactId>
  <version>${project.version}</version>
</dependency>

Apache Maven 的 reactor 會收集所有模組、依模組間的依賴排序，再按順序建置。因此即使父 POM 的 <modules> 順序不同，只要依賴關係正確，Maven 仍會先建置被依賴的模組。

在 Eclipse 更新並建置多模組專案

1. 在父專案上按右鍵，選擇 Maven → Update Project…；常見快捷鍵為 Alt+F5。
2. 勾選父專案與所有模組，必要時勾選 Force Update，再按 OK。
3. 在父專案上選擇 Run As → Maven build…，Goals 輸入 clean verify。
4. 也可在父專案目錄使用終端機執行 mvn clean verify。

只想建置某個模組並自動帶上它依賴的工作區模組，可使用：

mvn -pl demo-web -am verify

-pl 選擇專案，-am（also-make）會一併建置它需要的 reactor 模組。更多行為可參考 Apache Maven：Guide to Working with Multiple Modules。

常見問題與排查

父專案出現 src 資料夾，需要刪除嗎？

packaging=pom 的父專案通常不放 Java 原始碼。若 src 是精靈產生且確定為空，可以移除；若專案已有內容，先確認用途，不要直接刪除。

建立 Module 後，父 POM 沒有 modules

檢查父 POM 是否為 pom packaging，並加入與資料夾名稱一致的 <module>。路徑是相對於父 POM，不是 Java package 名稱。

子模組顯示 Missing artifact 或紅色錯誤

先檢查父座標、版本與 relativePath，再執行 Maven → Update Project。若模組彼此依賴，也要確認 dependency 的 groupId、artifactId、version 和實際模組一致。

網站模組一定要用 war 嗎？

不一定。傳統 Servlet／JSP 且部署到外部 Servlet 容器時常用 WAR；Spring Boot 等自帶伺服器的應用通常使用可執行 JAR。Packaging 應由部署方式決定。

aggregation 和 inheritance 有什麼不同？

Aggregation 是父 POM 的 <modules> 決定一起建置哪些專案；inheritance 是子 POM 的 <parent> 決定繼承哪些設定。兩者常放在同一份父 POM，但概念不同。

延伸閱讀

• 多模組專案需要統一日誌時，可參考使用 SLF4J 統一應用程式日誌。
• 若部署 WAR 到舊版 Tomcat 遇到 JAR 掃描問題，可參考Tomcat 與 module-info.class 的 Invalid byte tag 19 解法。

結論

Eclipse 建立 Maven 多模組專案的重點不是精靈本身，而是三個關係要一致：父專案使用 pom packaging、父 POM 的 <modules> 指向正確子目錄、子 POM 的 <parent> 與 dependency 使用正確座標。完成後從父專案執行 mvn clean verify，就能讓 Maven reactor 依依賴順序建置全部模組。