Maven/Gradle超入門：依存管理とビルドの基礎（Java）

この記事のゴールと前提

• Maven/Gradleの役割と違いが分かる
• 最小プロジェクトでビルド→テスト→実行できる
• 依存管理の基本と詰まりやすい点が分かる
• Eclipseにインポートして実行できる
• 小さなアプリを実行可能JARとして配布できる

前提：JDKとEclipseが導入済み（未導入なら こちら）。

初心者メモ：「ビルド」って難しそう…？ ソースコードを実行できる形に加工する作業のこと。依存の自動ダウンロードも含めて、ツールが面倒を見てくれます。

MavenとGradleの違い・選び方

指針：まずはMavenで“型”を覚え、必要に応じてGradleへ。学習曲線がなめらかです。

先輩のヒトコト：Mavenは「決まりがある＝迷いにくい」。 Gradleは「自由＝慣れると快適」。まずは迷わない環境から！

最短で「動かす」ハンズオン

ここでは、“最小で動かす”ことだけに集中。深い話は後でOK！

copymkdir hello-build && cd hello-build
mkdir -p src/main/java/com/example/app
mkdir -p src/test/java/com/example/app

copy<project xmlns="https://maven.apache.org/POM/4.0.0"
  xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://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>hello-mvn</artifactId>
  <version>1.0.0</version>
  <properties>
    <maven.compiler.source>21</maven.compiler.source>
    <maven.compiler.target>21</maven.compiler.target>
    <junit.jupiter.version>5.10.0</junit.jupiter.version>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>${junit.jupiter.version}</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.2.5</version>
        <configuration><useModulePath>false</useModulePath></configuration>
      </plugin>
    </plugins>
  </build>
</project>

copy// src/main/java/com/example/app/Main.java
package com.example.app;
public class Main {
  public static void main(String[] args) {
    System.out.println("Hello, Maven!");
  }
}

copy// 実行
mvn -q -v
mvn -q clean test
mvn -q package
java -cp target/hello-mvn-1.0.0.jar com.example.app.Main

copy// settings.gradle.kts
rootProject.name = "hello-gradle"

copy// build.gradle.kts
plugins { java; application }
java { toolchain { languageVersion.set(JavaLanguageVersion.of(21)) } }
repositories { mavenCentral() }
dependencies { testImplementation("org.junit.jupiter:junit-jupiter:5.10.0") }
tasks.test { useJUnitPlatform() }
application { mainClass.set("com.example.app.Main") }

copy// src/main/java/com/example/app/Main.java
package com.example.app;
public class Main {
  public static void main(String[] args) {
    System.out.println("Hello, Gradle!");
  }
}

copy// 実行
./gradlew -q -v
./gradlew -q clean test
./gradlew -q run
./gradlew -q build

つまずき対策：「コマンドが見つからない」は、ツール未インストール or PATH未設定が定番。 まず mvn -v / gradle -v が通るか確認しよう！

ビルドのライフサイクル（図解）

用語の感覚： Mavenは「駅を順に通過する列車」（compile→test→…）。 Gradleは「必要なバスにだけ乗る」（タスク選択）イメージ！

ラッパー（Wrapper）の役割と作り方

プロジェクトのビルドツールのバージョンを固定し、誰が実行しても同じ結果にする仕組み。mvnw/gradlewはリポジトリにコミットOK（超重要）。

copymvn -N io.takari:maven:wrapper

copygradle wrapper

CI/CDでも効く！ バージョン差で失敗しがちなビルドが安定。 「本番とローカルで挙動が違う」が減ります。

Maven/Gradle コピペサンプル（タブ切替）

copysrc/
 ├─ main/java/com/example/app/Main.java
 └─ test/java/com/example/app/MainTest.java
pom.xml

copy<project xmlns="https://maven.apache.org/POM/4.0.0"
  xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://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>hello-mvn</artifactId>
  <version>1.0.0</version>
  <properties>
    <maven.compiler.source>21</maven.compiler.source>
    <maven.compiler.target>21</maven.compiler.target>
    <junit.jupiter.version>5.10.0</junit.jupiter.version>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>${junit.jupiter.version}</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.2.5</version>
        <configuration><useModulePath>false</useModulePath></configuration>
      </plugin>
    </plugins>
  </build>
</project>

copypackage com.example.app;
public class Main { public static void main(String[] args){ System.out.println("Hello, Maven!"); } }

copypackage com.example.app;
import static org.junit.jupiter.api.Assertions.assertEquals;
import org.junit.jupiter.api.Test;
class MainTest { @Test void hello(){ assertEquals(2,1+1); } }

copy./mvnw -q -v
./mvnw -q clean test
./mvnw -q package
java -cp target/hello-mvn-1.0.0.jar com.example.app.Main

copysettings.gradle.kts
build.gradle.kts
src/
 ├─ main/java/com/example/app/Main.java
 └─ test/java/com/example/app/MainTest.java

copyrootProject.name = "hello-gradle"

copyplugins { java; application }
java { toolchain { languageVersion.set(JavaLanguageVersion.of(21)) } }
repositories { mavenCentral() }
dependencies { testImplementation("org.junit.jupiter:junit-jupiter:5.10.0") }
tasks.test { useJUnitPlatform() }
application { mainClass.set("com.example.app.Main") }

copypackage com.example.app;
public class Main { public static void main(String[] args){ System.out.println("Hello, Gradle!"); } }

copypackage com.example.app;
import static org.junit.jupiter.api.Assertions.assertTrue;
import org.junit.jupiter.api.Test;
class MainTest { @Test void ok(){ assertTrue(1+1==2); } }

copy./gradlew -q -v
./gradlew -q clean test
./gradlew -q run
./gradlew -q build

差が出やすいポイント： Gradleはapplicationプラグインのrunが便利。Mavenはjar作ってjava -cpで実行するのが基本です。

依存管理の基礎と落とし穴

1) スコープ/構成

• Maven：compile（標準）/provided（実行時不要）/runtime/test 等
• Gradle：implementation（推移は公開しない）/api（ライブラリ公開用）/runtimeOnly/testImplementation 等

2) 推移（transitive）依存

ライブラリが内部でさらに別のライブラリに依存すること。不要な推移は除外、競合はバージョン統一で解決。

copy<dependency>
  <groupId>com.example</groupId>
  <artifactId>foo</artifactId>
  <version>1.2.3</version>
  <exclusions>
    <exclusion><groupId>org.slf4j</groupId><artifactId>slf4j-log4j12</artifactId></exclusion>
  </exclusions>
</dependency>

copydependencies {
  implementation("com.example:foo:1.2.3") {
    exclude(group = "org.slf4j", module = "slf4j-log4j12")
  }
}

3) バージョンの決め方

• 集約管理：Mavenは<properties>、Gradleはlibs.versions.toml（バージョンカタログ）
• アップデート時の順番：バージョン固定→テスト→実行。無闇に上げて壊さない。

注意： ロギング周り（SLF4J/Logback/Log4J）は推移で二重に入ることが多い。 競合エラーは「除外 or ひとつに統一」でスッキリ！

Eclipse連携（インポート＆実行）

Mavenプロジェクトをインポート

1. File > Import… > Maven > Existing Maven Projects
2. ルートを選択 → pom.xml を認識 → Finish
3. 依存は自動解決。うまくいかない時は Project > Update Maven Project

Gradleプロジェクトをインポート

1. File > Import… > Gradle > Existing Gradle Project
2. ルートを選択 → Buildshipが依存同期
3. 不調なら右クリック → Gradle > Refresh Gradle Project

実行は Run As > Java Application（Gradleは application の Run も便利）。

文字化け対策： Eclipseのワークスペース・コンソールをUTF-8推奨。 Mavenは project.build.sourceEncoding を忘れずに！

実行可能JARの作り方（配布まで）

Maven：maven-jar-plugin でMain指定

copy<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-jar-plugin</artifactId>
      <version>3.3.0</version>
      <configuration>
        <archive>
          <manifest><mainClass>com.example.app.Main</mainClass></manifest>
        </archive>
      </configuration>
    </plugin>
  </plugins>
</build>

java -jar target/hello-mvn-1.0.0.jar で実行可能に。外部依存も同梱したいなら Shade（fat JAR） の導入を検討。

Gradle：application で配布物作成

copyplugins { java; application /* fatはShadowを追加可 */ }
// id("com.github.johnrengelman.shadow") version "8.1.1"
application { mainClass.set("com.example.app.Main") }
tasks.register<Copy>("dist") { dependsOn("installDist") }

./gradlew installDist で build/install/ 配下にOS別スクリプト付き配布物が生成（便利！）。

配布のコツ： CLIツールならinstallDistがラク。 JAR単体配布はJavaが入ってる前提になる点に注意！

よくあるエラー＆詰まり解消フロー

1. まずバージョン確認：java -version / mvn -v / gradle -v
2. ネットワーク：プロキシ・mavenCentral 到達性。時間を置くと直るケースも。
3. JDKミスマッチ：Mavenはsource/target、Gradleはtoolchainを21等に。
4. テストが走らない：JUnit5ならSurefire設定（Maven）/ useJUnitPlatform()（Gradle）。
5. 文字化け：UTF-8統一（IDE/コンソール/ビルド設定）。
6. CRLF問題：Git core.autocrlf をチームで決める。

• Could not resolve dependencies：レポジトリ未設定/一時不調。リトライ＆mavenCentral()確認。
• Class not found：クラスパス or メインクラス指定漏れ。
• 依存競合：除外して一本化。BOM/バージョンカタログ活用。

デバッグ心得：「設定を増やす前に、最小構成に戻して通す」。 小さく動かし直すのが一番はやい近道！

用語ミニ辞典（超ざっくり）

• 依存（dependency）：自分のコードが使う外部ライブラリ。
• 推移依存（transitive）：依存の依存。不要なら除外。
• スコープ / 構成：どのタイミング（compile/test/runtime）でライブラリを使うかの区分。
• ラッパー（wrapper）：プロジェクト固有のビルドツール実行スクリプト。
• フェーズ（Maven）/ タスク（Gradle）：ビルド処理の粒度。Mavenは駅、Gradleはバスのイメージ。

完了チェックリスト

• mvnw/gradlew を作ってコミットした
• 最小サンプルで build/test/run が成功した
• 依存バージョンをプロパティ/カタログに集約した
• Eclipseにインポートして実行できた
• 実行可能JAR or installDist で配布形を作れた

次の学習ステップ

• Eclipse × Git（EGit）入門：初回コミットとリモート連携
• 最初のJavaプロジェクト：パッケージ/クラス設計の基本

FAQ