把 Maven 提交到專案？Maven Wrapper的使用與好處

程序猿阿朗發表於2024-04-18
MavenAPP

本文收錄於 Github.com/niumoo/JavaNotes，Java 系列文件，資料結構與演算法！
本文收錄於網站：https://www.wdbyte.com/，我的公眾號：程式猿阿朗

前言

不知道你有沒有發現，如果使用 https://start.spring.io/ 或者使用 IDEA 建立一個 Spring Boot 專案，生成的檔案列表中或有 mvnw 和 mvnw.cmd 兩個命令檔案。如果細心的同學檢視隱藏目錄，還會發現一個 .mvn 資料夾，那麼這幾個檔案是幹嘛的呢？這篇文章介紹它的相關知識。

├── .gitignore
├── .mvn -> 關注
│   └── wrapper
│       ├── maven-wrapper.jar -> 關注
│       └── maven-wrapper.properties -> 關注
├── HELP.md
├── mvnw    -> linux 命令檔案
├── mvnw.cmd	-> windows 命令檔案
├── pom.xml
└── src
    ├── main
    │   ├── java/com/wdbyte/com/springbootdemo/SpringbootdemoApplication.java
    │   └── resources
    │       ├── application.properties
    │       ├── static
    │       └── templates
    └── test/java/com/wdbyte/com/springbootdemo/SpringbootdemoApplicationTests.java

Maven Wrapper 是什麼

上面提到的 mvnw 命令，它的全稱是 Maven Wrapper，這是 Maven 提供的一個非常有用的工具，它會自動下載指定版本的 Maven 用於專案構建，而且開發者自由配置 Maven 版本，以此提供一致的構建體驗。

mvnw 的命令使用體驗和 mvn 完全一致，只需要把 mvn 命令換成 mvnw ，你可以在有 mvnw 檔案的 Spring Boot 專案中進行測試。

$ ./mvnw --version
Apache Maven 3.9.5 (57804ffe001d7215b5e7bcb531cf83df38f93546)
Maven home: /Users/darcy/.m2/wrapper/dists/apache-maven-3.9.5-bin/32db9c34/apache-maven-3.9.5
Java version: 21, vendor: Oracle Corporation, runtime: /Users/darcy/develop/jdk-21.jdk/Contents/Home
Default locale: zh_CN_#Hans, platform encoding: UTF-8
OS name: "mac os x", version: "14.0", arch: "x86_64", family: "mac"

注：windows 環境請使用 mvnw.cmd

Maven Wrapper 官網：https://maven.apache.org/wrapper/

Maven Wrapper 使用場景

設想一下，如果所在的團隊同時維護多個專案，不同的專案使用的 JDK 版本不相同，使用的 Maven 版本也不相同，那麼為了支援多專案開發，為了構建執行效果一致，你可能需要在本地管理多個 Maven 版本，這會非常繁瑣，而 Maven Wrapper 可以輕鬆的解決這個問題。

Maven Wrapper 的引入解決了下面幾個問題：

  • 版本一致性：透過在 mvnw 配置中指定 Maven 版本，確保所有開發人員和持續整合環境使用相同的 Maven 版本。
  • 簡化設定：新團隊成員或 CI 環境不需要預先安裝 Maven，直接執行 mvnw 命令就如安裝了 mvn 一樣，從而簡化了專案的初始設定和配置。
  • 跨平臺：Wrapper 是跨平臺的，無論是在 Windows 還是在 Unix-like 系統上，都可以以相同的方式執行。

使用 Maven Wrapper 的好處簡單的說，可以是 “如果想要使用不同的 Maven 版本進行專案構建，只需在專案中存放一個指令碼檔案，而不是在本地安裝不同的 Maven 版本”。

Maven Wrapper 使用方式

自動生成

如果本地機器已經安裝了 Maven ，那麼可以在指定專案中透過命令生成 mvnw 命令。

要在現有專案中引入 Maven Wrapper，需要執行如下命令：

mvn -N wrapper:wrapper

也可以指定 maven 版本。

mvn -N wrapper:wrapper -Dmaven=3.9.5

選項 -N 參數列示非遞迴，因此 Maven Wrapper 只會在專案的當前目錄生成，如果專案中有子模組，那麼則不會作用到子模組中。

下面我在一個空的 Spring Boot 專案中進行測試。

一個沒有 mvnw 的 Spring Boot 專案：

$ ls -l -a
total 16
-rw-r--r--@   1 darcy  staff   395  4 16 21:44 .gitignore
-rw-r--r--@   1 darcy  staff  1249  4 16 21:44 pom.xml
drwxr-xr-x@   4 darcy  staff   128  4 16 21:44 src
drwxr-xr-x   11 darcy  staff   352  4 16 21:50 target

使用 mvn -N wrapper:wrapper 生成 mvnw。

$ mvn wrapper:wrapper
[INFO] Scanning for projects...
... 省略日誌
[INFO] -------------------< com.wdbyte.com:springbootdemo >--------------------
[INFO] Building springbootdemo 0.0.1-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- maven-wrapper-plugin:3.2.0:wrapper (default-cli) @ springbootdemo ---
....省略日誌
[INFO] Unpacked bin type wrapper distribution org.apache.maven.wrapper:maven-wrapper-distribution:zip:bin:3.2.0
[INFO] Configuring .mvn/wrapper/maven-wrapper.properties to use Maven 3.6.3 and download from http://mvnrepo.alibaba-inc.com/mvn/repository
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  20.518 s
[INFO] Finished at: 2024-04-16T22:36:16+08:00
[INFO] ------------------------------------------------------------------------

檢視目錄已經生成。

$ ls -l -a
-rw-r--r--@   1 darcy  staff    395  4 16 21:44 .gitignore
drwxr-xr-x    3 darcy  staff     96  3  8  2023 .mvn
-rwxr-xr-x    1 darcy  staff  11289  3  8  2023 mvnw
-rw-r--r--    1 darcy  staff   7796  3  8  2023 mvnw.cmd
-rw-r--r--@   1 darcy  staff   1249  4 16 21:44 pom.xml
drwxr-xr-x@   4 darcy  staff    128  4 16 21:44 src
drwxr-xr-x   11 darcy  staff    352  4 16 21:50 target
# 檢視版本
$ ./mvnw --version
Apache Maven 3.6.3 (cecedd343002696d0abb50b32b541b8a6ba2883f)
Maven home: /Users/darcy/.m2/wrapper/dists/apache-maven-3.6.3-bin/c7849ca4/apache-maven-3.6.3
Java version: 21, vendor: Oracle Corporation, runtime: /Users/darcy/develop/jdk-21.jdk/Contents/Home
Default locale: zh_CN_#Hans, platform encoding: UTF-8
OS name: "mac os x", version: "14.0", arch: "x86_64", family: "mac"

生成的檔案說明：

  1. mvnw 和 mvnw.cmd 指令碼，分別用於 Unix/Linux 和 Windows 環境。

  2. .mvn/wrapper/mavenwrapper.jar 是 Maven Wrapper 執行時所需的 Jar 檔案。

    .mvn/wrapper/maven-wrapper.properties 是配置檔案，可以配置 Maven 版本。

然後就可以使用 mvnw 代替 mvn 構建或執行專案了。

./mvnw spring-boot:run

手動複製

透過將上面生成的檔案和資料夾複製到一個新專案中，就可以複製一份 Maven Wrapper 。

需要複製的檔案如下：

./
├── .mvn
│   └── wrapper
│       ├── maven-wrapper.jar
│       └── maven-wrapper.properties
├── mvnw
├── mvnw.cmd

手動配置

直接修改 maven-wrapper.properties 中的內容可以修改 Maven 版本，如修改 Maven 版本為 3.9.5，只需要修改 distributionUrl 的值為指定版本的下載地址。

$ cat .mvn/wrapper/maven-wrapper.properties
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.5/apache-maven-3.9.5-bin.zip
wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.2.0/maven-wrapper-3.2.0.jar

Maven Wrapper 總結

Maven Wrapper 是一個非常好用的工具，雖然它不是專案的一部分，但是如果把它放到專案中，不僅簡化了專案的構建環境配置過程，還為專案構建減少了潛在的問題。如果你還沒有在你的專案中使用 Maven Wrapper，不妨考慮嘗試一下。將 Maven Wrapper 整合到專案中是一個不錯的方式，這樣可以跟隨專案原始碼一起管理，可以讓所有使用該專案的同學都能得到相同的構建結果。

整合步驟通常如下：

  1. 在專案根目錄執行前面提到的命令新增 Maven Wrapper。
  2. 提交生成的 mvnw, mvnw.cmd 和 .mvn/ 目錄到版本控制系統。
  3. 更新專案文件，指導團隊成員使用 ./mvnw 替代 mvn。

參考

  1. https://maven.apache.org/wrapper/

本文收錄於 Github.com/niumoo/JavaNotes，Java 系列文件，資料結構與演算法！
本文收錄於網站：https://www.wdbyte.com/，我的公眾號：程式猿阿朗

相關文章