1. Gradleプロジェクトの標準ディレクトリ構造とは？ルートとサブプロジェクトの基本
    1. ルートプロジェクトとサブプロジェクトの役割
    2. 標準的なディレクトリレイアウト
    3. Javaプラグインのデフォルトソースディレクトリ
    4. マルチプロジェクトでの論理パスの扱い
  2. Gradle Wrapperの仕組みとシステムインストール版との使い分け方
    1. Gradle Wrapperの基本構造
    2. システムインストール版との違い
    3. Wrapper利用時の確認ポイント
  3. Gradle Worker APIとは？並列処理の仕組みと3つの分離モードを解説
    1. Worker APIの目的と構成要素
    2. 3つの分離モードの比較
    3. Worker Daemonと非同期実行の仕組み
  4. GradleとJavaの互換性を確認する方法｜JDKバージョンとの対応表
    1. Gradleを実行するために必要なJDKバージョン
    2. GradleとJavaのバージョン対応表
    3. Java Toolchainsによる実行環境とビルド環境の分離
  5. Gradleのビルドを高速化するには？max-workers設定とWorker APIの活用法
    1. max-workersの役割とデフォルト値
    2. 並列実行を有効にする設定
    3. Worker APIによるタスク内の並列化と注意点
  6. まとめ
  7. よくある質問
    1. Q: Gradleプロジェクトの標準的なディレクトリ構造を教えてください
    2. Q: Gradle WrapperとシステムにインストールしたGradleの違いは何ですか？
    3. Q: GradleのWorker APIとは何ですか？
    4. Q: GradleのWorker APIの分離モードにはどのような種類がありますか？
    5. Q: GradleとJavaのバージョン互換性はどのように確認すればよいですか？

Gradleプロジェクトの標準ディレクトリ構造とは？ルートとサブプロジェクトの基本

ルートプロジェクトとサブプロジェクトの役割

Gradleプロジェクトの基本構造は「ルートプロジェクト + 1つ以上のサブプロジェクト」です。ルートプロジェクトにはsettings.gradle(.kts)を配置し、プロジェクト全体の名前とサブプロジェクトの構成を定義します。各サブプロジェクトには個別のbuild.gradle(.kts)を置き、それぞれのビルド設定を記述します。

重要なのは、ルートプロジェクト自体にbuild.gradle(.kts)を置くことは推奨されない点です。ルートはあくまで「プロジェクト全体を統括する場所」であり、実際のビルドロジックはサブプロジェクト側に持たせるのが公式の推奨構成です（出典：Gradle「Structuring and Organizing Gradle Projects」）。

標準的なディレクトリレイアウト

Gradleプロジェクトの標準レイアウトは次のとおりです。プロジェクトルートにはgradlew（Unix系）とgradlew.bat（Windows）が置かれ、これがGradleプロジェクトであることの明確な指標になります。gradle/wrapper/ディレクトリにはWrapper関連ファイル、gradle/直下にはバージョンカタログlibs.versions.tomlを配置します。

  • .gradle/：Gradleが自動生成するプロジェクト固有キャッシュ（git管理外）
  • gradle/wrapper/：gradle-wrapper.jarとgradle-wrapper.properties
  • settings.gradle(.kts)：ルートプロジェクト名とサブプロジェクトを定義
  • subproject-a/build.gradle(.kts)：サブプロジェクトのビルドスクリプト

ソースコードは各サブプロジェクトのsrc/配下に配置します（出典：Gradle「Gradle Project Structure」）。

Javaプラグインのデフォルトソースディレクトリ

Javaプラグインを適用した場合の標準的なソース配置は、src/main/java（本番Javaソース）、src/main/resources（本番リソース）、src/test/java（テストJavaソース）、src/test/resources（テスト用リソース）が基本です。

ビルド出力はbuild/ディレクトリに集約されます。JARはbuild/libs/、クラスファイルはbuild/classes/、レポートはbuild/reports/など、特に指定しない限りすべてbuild/配下に生成されます。build/は一時生成物のため、ソース管理にコミットするべきではありません（出典：Gradle「Building Java & JVM Projects」「Gradle Basics」）。

マルチプロジェクトでの論理パスの扱い

マルチプロジェクトでは、プロジェクトパスをコロン（:）区切りで表現します。ルートは:で表され、唯一「名前で指定されないプロジェクト」です。たとえばinclude("services:api")と記述すると、デフォルトで./services/apiディレクトリにマップされます。

タスク実行時はgradle :services:webservice:buildのように完全修飾名を指定できます。注意点として、Gradle 9.0以降はinclude()したサブプロジェクトのディレクトリが存在しない場合ビルドが失敗します。ディレクトリはproject(":x").projectDir.mkdirs()で事前に作成しておく必要があります（出典：Gradle「Structuring and Organizing Gradle Projects」）。

Gradle Wrapperの仕組みとシステムインストール版との使い分け方

Gradle Wrapperの基本構造

Gradle Wrapperは、プロジェクトが使用するGradleバージョンを固定し、必要に応じてそのバージョンを自動取得して実行する仕組みです。プロジェクトごとにGradleのバージョンを指定できるため、開発者全員が同じ環境でビルドできます。CI環境でも同じバージョンを使えるのが大きな利点です。

Wrapperの構成要素は、gradlew（Linux/macOS用起動スクリプト）、gradlew.bat（Windows用）、gradle/wrapper/gradle-wrapper.properties（使用するGradleバージョンの指定）、gradle/wrapper/gradle-wrapper.jar（Wrapper実行用JAR）の4つです（出典：Gradle「Gradle Wrapper Basics」）。

システムインストール版との違い

システムにGradleを手動インストールしてgradleコマンドを使う方法と、Wrapperを使う方法ではバージョン管理の確実性が大きく異なります。手動インストール版はマシンにインストールされたバージョンに依存するため、開発者ごとに異なるバージョンを使ってしまうリスクがあります。一方Wrapperはプロジェクト内にバージョンが明記されているため、誰が実行しても同じバージョンが使われます。

公式ドキュメントではJavaプロジェクトではGradle Wrapperの使用が推奨されています。既存プロジェクトでは、まずgradlewの有無とgradle-wrapper.propertiesに記載されたバージョンを確認するのが基本です（出典：Gradle「Gradle Wrapper Basics」）。

Wrapper利用時の確認ポイント

既存のGradleプロジェクトに参加した場合、以下の順で確認するとスムーズです。

  1. gradlew / gradlew.batの有無を確認する
  2. gradle-wrapper.propertiesに記載されたGradleバージョンを確認する
  3. 使用しているJDKバージョンがGradleの実行環境要件を満たしているか確認する
  4. build.gradleまたはbuild.gradle.ktsの内容を確認する

Wrapperが存在する場合、システムにインストールしたGradleではなくWrapperを使ってビルドするのが基本です。Wrapperは初回実行時に必要なGradleを自動取得するため、Gradleが未インストールでもビルドできます（出典：Gradle「Gradle Wrapper Basics」）。

要点：Gradle WrapperはプロジェクトごとにGradleバージョンを固定する公式推奨の仕組み。既存プロジェクトではまずWrapperの有無を確認し、存在する場合は必ずgradlew経由でビルドする。

Gradle Worker APIとは？並列処理の仕組みと3つの分離モードを解説

Worker APIの目的と構成要素

Worker APIは、タスク内の処理単位を並列・非同期で安全に実行するための公式APIです。1つのタスク内で複数の作業項目を並列実行したり、クラスローダや独立プロセスで分離して実行したりできます。複数タスクの安全な並列実行も可能です。

主要な構成要素は4つの型で構成されます。WorkerExecutor（作業を非同期実行のために送信するサービス）、WorkQueue（作業の送信先）、WorkAction（1つの作業単位の実装）、WorkParameters（作業単位のパラメータ定義）です。これらの組み合わせで作業を分割・並列化します（出典：Gradle「Developing Parallel Tasks」）。

3つの分離モードの比較

Worker APIでは、作業単位をどの程度分離して実行するかを3つのモードから選択できます。分離レベルが高いほど安全性は高まりますが、オーバーヘッドも増加します。

分離モード 実行環境 特徴
noIsolation() タスクと同じスレッド内 最速・最小オーバーヘッド。静的クラス状態を介した相互影響のリスクあり
classLoaderIsolation() 分離クラスローダを持つスレッド内 作業単位ごとに別バージョンのライブラリを指定可能
processIsolation() 独立したWorker Daemonプロセス 最大の分離。ヒープやシステムプロパティを個別設定可能

どのモードを選ぶかは、作業単位の独立性と必要なライブラリのバージョンによって判断します（出典：Gradle「Worker API」）。

Worker Daemonと非同期実行の仕組み

processIsolation()は長期稼働する「Worker Daemon」プロセスを起動します。作業を送信すると、互換性のあるアイドルdaemonがあれば再利用し、なければ新規起動します。デフォルトの最大ヒープは512MBで、ProcessWorkerSpec.forkOptions()で変更可能です。互換性判定は実行可能ファイル、クラスパス、ヒープ設定、JVM引数、システムプロパティなど複数の基準で行われます。

作業は非同期で並列実行され、タスクアクション終了時に作業が完了していなくても安全にタスクを抜けられます。ただしWorkQueue.await()を使うと送信した全作業の完了を待つため、同じプロジェクトの別タスクを並列実行できなくなります。エラー発生時はWorkerExecutionExceptionがスローされ、依存タスクの実行も妨げられます（出典：Gradle「Developing Parallel Tasks」）。

要点：Worker APIは「WorkerExecutor」「WorkQueue」「WorkAction」「WorkParameters」の4型で構成され、3つの分離モード（noIsolation / classLoaderIsolation / processIsolation）で安全性と速度のバランスを選択する。

GradleとJavaの互換性を確認する方法｜JDKバージョンとの対応表

Gradleを実行するために必要なJDKバージョン

Gradleを実行するにはJDK 17以上が必要です。これは「Javaプロジェクトのコンパイル対象として利用できるJavaバージョン」とは別の話で、あくまで「Gradle自体を動かすためのJDK」の要件です。古い記事にある「JDK 8があればGradleを実行できる」という説明は現行版には適用できません。

2026年8月時点では、Java 17〜26がGradleの実行環境としてサポートされています。Gradle本体とJavaのバージョンは別物であり、互換性の確認が重要です（出典：Gradle「Compatibility Matrix」）。

GradleとJavaのバージョン対応表

主要なJavaバージョンと、そのJava上でGradleを実行するために必要な最小Gradleバージョンの対応は次のとおりです。

Javaバージョン Gradleを実行するために必要な最小Gradleバージョン
Java 17 Gradle 7.3
Java 21 Gradle 8.5
Java 26 Gradle 9.4.0

たとえばJava 26でGradleを実行するにはGradle 9.4.0以降が必要ですが、9.6.1が必須というわけではありません。Java 21なら8.5以降で実行可能です。新規プロジェクトではGradle 9.x系の最新版を使うのが基本です（出典：Gradle「Compatibility Matrix」）。

Java Toolchainsによる実行環境とビルド環境の分離

GradleにはJava Toolchainsという仕組みがあり、Gradleを実行するJDKと、プロジェクトのコンパイル・テストなどに使用するJava環境を分離できます。これにより、たとえば「Gradle自体はJDK 17で実行し、プロジェクトのコンパイル対象はJava 21にする」といった構成が可能です。

「Java 26をコンパイル対象として使うこと」と「Java 26でGradle自体を実行すること」は別問題です。Toolchainsを利用すれば、ビルドに使用するJava環境をプロジェクトごとに明示的に指定できます。互換性に迷ったら、まず実行環境のJDKバージョンとGradleバージョンの対応を確認し、その上でコンパイル対象のJavaバージョンをToolchainsで指定するのが安全です（出典：Gradle「Compatibility Matrix」）。

要点：Gradleの実行にはJDK 17以上が必要。Java 17ならGradle 7.3以上、Java 21なら8.5以上、Java 26なら9.4.0以上で実行可能。実行環境とコンパイル対象はJava Toolchainsで分離できる。

Gradleのビルドを高速化するには？max-workers設定とWorker APIの活用法

max-workersの役割とデフォルト値

max-workersは、Gradleが並列実行時に使用する最大worker数を指定する設定です。workerにはスレッド、テストプロセス、フォークしたコンパイラ、Worker APIの作業項目などが含まれます。デフォルト値はJVMが利用可能なプロセッサ数です。CPUコア数ではなく「JVMが認識できるプロセッサ数」が基準になります。

値は必ず1以上である必要があり、1未満を設定するとIllegalArgumentExceptionが発生します。設定方法は、コマンドラインで--max-workers=Nを指定するか、gradle.propertiesにorg.gradle.workers.max=Nと記述する方法があります（出典：Gradle API「ParallelismConfiguration」）。

並列実行を有効にする設定

org.gradle.workers.maxはそれ単体で並列実行を有効化するものではありません。--parallelまたはorg.gradle.parallel=trueと組み合わせて使用する必要があります。--parallelはマルチプロジェクトビルドで独立したプロジェクトを並列ビルドするためのオプションです。

並列実行を有効にすると、複数のサブプロジェクトや独立したタスクが同時に実行され、ビルド時間の短縮が期待できます。ただし、タスク間に依存関係がある場合は並列実行されないため、プロジェクト構成によって効果は異なります。まずは--parallelを有効にし、ビルド時間の変化を確認するのが実践的です（出典：Gradle「Command-Line Interface」）。

Worker APIによるタスク内の並列化と注意点

Worker APIを使うと、1つのタスク内の作業項目を並列実行できます。作業は非同期で送信され、max-workers設定までの並列度で実行されます。ただし「Worker APIを使えば必ず高速になる」とは限りません。特にprocessIsolation()はプロセス起動にコストがかかるため、初回実行は遅くなることがあります。2回目以降はWorker Daemonが再利用され高速化します。

またWorkQueue.await()を使うと送信した全作業の完了を待つため、同じプロジェクトの別タスクを並列実行できなくなります。独立したタスクのみが並列化対象になる点に注意が必要です。キャンセル時は実行中スレッドが割り込みに応答する実装が推奨され、10秒間応答しない場合はWorker Daemonがシャットダウンされます（出典：Gradle「Developing Parallel Tasks」）。

要点：max-workersのデフォルトはJVMが利用可能なプロセッサ数。並列実行には--parallelとの併用が必要。Worker APIはタスク内の並列化に有効だが、プロセス起動コストやawait()による並列性の制限に注意する。