Java Maven 教學

Maven 是一個強大的 Java 專案管理與建置工具，由 Apache Software Foundation 開發。它主要用於專案建置、相依性管理 (Dependency Management) 以及專案資訊管理。

Maven 基於 Project Object Model (POM) 的概念，使用一個 XML 檔案 (pom.xml) 來描述專案的結構、依賴關係和建置過程。

為什麼需要 Maven?

在沒有 Maven 之前，開發 Java 專案會遇到以下問題：

JAR 檔地獄 (JAR Hell)：需要手動下載各種 JAR 檔放到專案中，版本衝突難以管理
建置過程不統一：每個專案的編譯、測試、打包方式可能都不同
專案結構混亂：原始碼、編譯檔、設定檔隨意放置

Maven 解決了這些問題：

自動化依賴管理：只需在 pom.xml 宣告需要的函式庫，Maven 會自動從中央倉庫下載，並處理依賴傳遞 (Transitive Dependencies)
標準化專案結構：規定了統一的目錄結構
標準化建置生命週期：統一了編譯、測試、打包、部署的流程

安裝 Maven

檢查是否已安裝

許多 IDE (如 IntelliJ IDEA) 已經內建 Maven。你可以在終端機輸入：

mvn -version

安裝步驟

如果未安裝，可以參考以下步驟：

下載：前往 Apache Maven 官網下載 Binary zip archive
解壓縮：解壓到你想放置的目錄
設定環境變數：
- 將 bin 目錄加入系統 PATH 變數
驗證：再次執行 mvn -version
驗證：再次執行 mvn -version

從零建立 Maven 專案

使用 Maven 的 archetype (原型) 機制，可以快速建立符合標準結構的專案。

開啟終端機，移動到你想建立專案的資料夾
執行建立指令：

mvn archetype:generate

選擇 Archetype：Maven 會列出數千個原型，直接按 Enter 選擇預設的 maven-archetype-quickstart (標準 Java SE 專案)。
設定版本：按 Enter 選擇預設版本。
設定 GroupId：輸入組織 ID (例如 com.example)。
設定 ArtifactId：輸入專案名稱 (例如 my-app)。
設定 Version：按 Enter 使用預設值 (1.0-SNAPSHOT)。
設定 Package：按 Enter 使用預設值。
確認：輸入 Y 確認。

完成後，你會看到 my-app 資料夾，裡面已包含 pom.xml 和基本的 App.java。

Maven 專案結構

Maven 採用 Convention over Configuration (約定優於配置) 的原則，標準目錄結構如下：

my-app/
├── pom.xml              (專案設定檔)
└── src/
    ├── main/
    │   ├── java/        (Java 原始碼)
    │   └── resources/   (資源檔，如設定檔)
    └── test/
        ├── java/        (測試程式碼)
        └── resources/   (測試用資源檔)

pom.xml 核心概念

pom.xml 是 Maven 專案的核心。一個最基本的 pom.xml 包含：

<project>
    <!-- Maven 模型版本 -->
    <modelVersion>4.0.0</modelVersion>
  
    <!-- 專案座標 (Coordinates) -->
    <groupId>com.example</groupId>       <!-- 組織 ID，通常是倒置的網域名稱 -->
    <artifactId>my-app</artifactId>      <!-- 專案名稱 -->
    <version>1.0.0-SNAPSHOT</version>    <!-- 版本號 -->
  
    <!-- 專案屬性 -->
    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <!-- 依賴管理 -->
    <dependencies>
        <!-- 例如引入 JUnit 測試框架 -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
            <version>5.10.0</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
</project>

常見 Scope

compile (預設)：編譯、測試、執行時都需要（如 Spring Core）
test：只在測試編譯和執行時需要（如 JUnit）
provided：編譯、測試時需要，但執行時由環境提供（如 Servlet API）
runtime：執行時需要，但編譯不需要（如 JDBC Driver）

常用 Maven 指令

Maven 的執行是基於 生命週期 (Lifecycle) 的。常用的指令包括：

mvn clean：清理專案，刪除 target/ 目錄
mvn compile：編譯 src/main/java 下的原始碼
mvn test：執行單元測試
mvn package：打包專案（產生 JAR 或 WAR 檔到 target/ 目錄）
mvn install：將打包好的 JAR 檔安裝到本地倉庫 (Local Repository)，供其他本地專案使用
mvn deploy：將 JAR 檔部署到遠端倉庫 (Remote Repository)

執行 Java 程式

Maven 本身主要用於建置，但也可以透過插件來執行 Java 程式。

使用 Exec Maven Plugin

如果您想直接在 Maven 中執行 main 方法：

確保 pom.xml 中沒有錯誤
執行以下指令 (需指定完整的類別名稱)：

mvn compile exec:java -Dexec.mainClass="com.example.App"

使用 java 指令

正規的做法是先打包成 JAR 檔，再使用 java 指令執行：

# 1. 打包
mvn package

# 2. 執行 (假設打包後的 jar 在 target 目錄下)
java -cp target/my-app-1.0-SNAPSHOT.jar com.example.App

通常會組合使用，例如：

# 清理並打包
mvn clean package

Maven Wrapper (mvnw)

為了確保團隊成員使用相同版本的 Maven，現代專案通常會包含 Maven Wrapper。

專案中會有 mvnw (Linux/Mac) 和 mvnw.cmd (Windows) 腳本。使用時，直接執行腳本代替 mvn 指令：

./mvnw clean package

這樣即使電腦沒有安裝 Maven，腳本也會自動下載指定版本的 Maven 來執行建置。

建議在專案中都使用 Maven Wrapper 來確保建置環境的一致性。

如何新增依賴 (Dependency)

要尋找第三方函式庫的 Maven 座標，最常用的網站是 MVN Repository。

例如要使用 Google Gson：

搜尋 "Gson"
選擇版本
複製 Maven XML 程式碼
貼到 pom.xml 的 <dependencies> 區塊中
執行 IDE 的 "Reload Maven Project" 或指令 mvn dependency:resolve

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.10.1</version>
</dependency>

總結

Maven 是 Java 生態系中標準的建置與依賴管理工具
透過 pom.xml 管理專案資訊與依賴
遵循標準的目錄結構與建置生命週期
善用 Maven Wrapper (mvnw) 確保環境一致性