【Java】Mavenでプロジェクトを管理する基本

Java
2024.10.31

こんにちは、かつコーチです。

前回まではファイル1〜2個の小さなプログラムをjavac・javaコマンドで動かしてきました。

しかし実際の開発では、外部ライブラリを何十個も使い、ファイルも数百に及びます。

そこで使われるのが、Javaの代表的なビルドツールの一つMavenです。

私は最初、pom.xmlのインデントを崩して保存しただけで大量のエラーが出て、原因がXMLの構文ミスだと気づくまで無駄に時間を使いました。

Mavenとは何か

ビルドツールが解決する課題

前回説明したように、Javaはコンパイル（javac）と実行（java）という2工程を経て動きます。

これに加えて、外部ライブラリのダウンロードやバージョン管理、テストの実行、パッケージ化まで手作業で行うのは非現実的です。

ビルドツールとは、こうした一連の作業を設定ファイル1つで自動化してくれる仕組みのことです。

Mavenはその代表格で、多くのJavaプロジェクト・特にSpring Boot案件で標準的に採用されています。

MavenとGradleの違い（先取り）

Javaのビルドツールには、Mavenのほかに次回解説するGradleがあります。

項目MavenGradle
設定ファイル形式XML（pom.xml）Groovy／Kotlin DSL（build.gradle）
記述の柔軟性規約に沿ってシンプル自由度が高い分、複雑になりやすい
学習コスト低めやや高め

初心者はまず、規約に沿って書けばよいシンプルなMavenから学ぶのがおすすめです。

基本の書き方：Mavenプロジェクトの作成

手順1：pom.xmlの役割を理解する

MavenプロジェクトはXML形式のpom.xml（Project Object Model）というファイルで管理されます。

<project xmlns="http://maven.apache.org/POM/4.0.0">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.katsucoach</groupId>
    <artifactId>hello-maven</artifactId>
    <version>1.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>
</project>

groupIdとartifactIdはプロジェクトを識別するID、propertiesではJavaのバージョンや文字コードを指定します。

手順2：IntelliJでMavenプロジェクトを作る

前回同様「New Project」でBuild systemに「Maven」を選ぶと、pom.xmlとsrc/main/javaフォルダが自動生成されます。

src/main/java配下にクラスを作成すれば、あとはこれまでと同じ書き方でコードを書けます。

手順3：依存関係を追加する

外部ライブラリは<dependencies>タグの中に追記します。

<dependencies>
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-lang3</artifactId>
        <version>3.14.0</version>
    </dependency>
</dependencies>

保存すると、IntelliJが自動的にライブラリをダウンロードし、コード内で使えるようになります。

つまずきやすい設定・注意点

groupId・artifactId・versionの3つは合わせて座標（GAV）と呼ばれ、ライブラリを特定するための必須情報です。

このうちどれか1つでも間違えると、ライブラリが見つからずビルドが失敗します。

よくあるつまずきポイント・エラー対処

pom.xmlのタグの閉じ忘れ・ネストミス

❌ Before：XMLの構文を意識せず編集する

依存関係を追加しようとした際、私はコピペしたタグを<properties>の中に誤って入れ子にしてしまいました。

<properties>
    <dependency>
        ...
    </dependency>
</properties>

保存した瞬間、IntelliJの左側に大量の赤い波線が表示され、次のようなエラーが出ました。

Non-parseable POM ... unexpected markup

エラーメッセージだけを見てもどこが悪いのか分からず、pom.xml全体を見直す羽目になりました。

✅ After：依存関係は必ずdependenciesタグの直下に置く

原因は単純なタグのネストミスで、<dependency>は<dependencies>の直下、<properties>とは独立したタグとして書く必要がありました。

<properties>
    <maven.compiler.source>21</maven.compiler.source>
</properties>

<dependencies>
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-lang3</artifactId>
        <version>3.14.0</version>
    </dependency>
</dependencies>

この経験以降、pom.xmlを編集するときはIntelliJの自動補完を活用し、手打ちでのタグ入力を極力減らすようにしています。

依存関係が反映されない

タグを正しく書いても反映されない場合は、IntelliJの「Maven」パネルにある更新アイコン（Reload All Maven Projects）を押すと、多くの場合解決します。

応用・一歩先の使い方

Mavenにはビルドの各段階を表す「ライフサイクル」という概念があり、mvn compile（コンパイル）、mvn test（テスト実行）、mvn package（jar化）などをコマンドで実行できます。

mvn package

このコマンド1つで、コンパイルからテスト、jarファイルの生成までを一気に行える点が、javac・javaを都度手打ちしていた頃との大きな違いです。

まとめ

この記事のポイント

  • Mavenはpom.xmlで依存関係やビルド設定を管理するビルドツール
  • ライブラリはgroupId・artifactId・versionのGAVで指定する
  • XMLのタグのネストミスはビルド失敗の典型的な原因
  • mvn packageのようなコマンドでビルドの一連の流れを自動化できる

次に読むべき記事

Mavenの基本を押さえたら、もう一つの主要ビルドツールであるGradleとの違いも見ておきましょう。

→ 次の記事：Gradleでプロジェクトを管理する基本

タグ: Java, 初心者向け, 環境構築

タイトルとURLをコピーしました