こんにちは、テックリードの皆さん。日々のビルド待ち時間や、環境依存のビルドエラー、CI/CDパイプラインの不可解な不具合に頭を悩ませていないだろうか。
「ローカルでは動いたのに、CIサーバーだとテストが落ちる」
「本番用プロパティがステージング環境に混入した」
これらは、Javaエコシステムにおける「暗黙的な環境依存」と「モノリシックなビルドプロセス」が引き起こす病の症状だ。Dockerの世界では「マルチステージ・ビルド」が常識となり、成果物をクリーンな環境で段階的に組み立てることでこの問題に終止符を打った。では、我々の心臓部である Gradle でも同じ思想を徹底できないだろうか？
今回は、Gradleの強力なタスク依存関係とプロジェクト構造をハックし、「テスト」「パッケージ」「デプロイ」の各ステージを完全に分離・カプセル化する堅牢なパイプライン設計をコードベースで実演する。単なるマニュアルの焼き直しではない、現場の生産性を極限まで引き上げるプロのアーキテクチャを共有しよう。
—
1. なぜGradleで「マルチステージ・ビルド」が必要なのか
Dockerのマルチステージビルドの本質は、「中間成果物を捨て、最終成果物に必要な最小限のバイナリだけを次のステージへ持ち越すこと」にある。これをGradleの単一プロジェクト内、あるいはマルチプロジェクト内でシミュレートする。
従来のGradleビルドは、`build` タスクを叩けばすべてが直列、あるいは曖昧な並列で実行されがちだ。これではキャッシュのヒット率が下がり、何より「どのフェーズでどの設定（プロファイル）が適用されたか」がブラックボックス化する。
フェーズを厳格に分離するメリットは以下の3点に集約される：
1. キャッシュの最適化（Fail-fast & Cache Hit）: テストが失敗した時点で即座に処理を止め、重いパッケージング処理を実行させない。
2. 環境汚染の防止: テスト用設定が本番用バイナリに混入するリスクを物理的に遮断する。
3. 環境変数・プロファイルの明示的インジェクション: 実行時ではなくビルド・パッケージングの段階で構成を焼き込む。
—
2. 現場のスピードを爆発させる環境構築・支援ツール
アーキテクチャの話に入る前に、このパイプラインを日々の開発でストレスなく回すための「武器」を共有しておこう。
隠れた神プラグイン: `com.avast.gradle.docker-compose` & `nebula.lint`
マルチステージなビルドを検証する際、ローカルでのコンテナ環境の立ち上げは不可欠だ。
- `nebula.lint` (Gradle Lint): ビルドスクリプトの「臭うコード」を検出し、依存関係の宣言漏れや非推奨な記述を自動修正する。マルチステージで複雑化した `build.gradle` の治安を守るために必須。
開発スピードを最大化するCLIショートカット
毎回 `gradle clean build` を叩いているエンジニアがいたら、今すぐその手を止めさせよう。
デーモンを常時起動し、変更されたファイルだけをインクリメンタルにテストする
./gradlew test –continuous
タスクの実行順序とボトルネックを視覚化する（出力されるHTMLをブラウザで確認）
./gradlew build –scan
特に `–scan`（Develocity）は、どのタスクがキャッシュをミスしているか、どこに時間がかかっているかを秒速で暴く。テックリードならチーム全員に導入を義務付けるべきだ。
—
3. 実践：フェーズ分離型 `build.gradle` のベストプラクティス
ここからが本題だ。テスト、パッケージ、デプロイの各ステージを明確に分離したマルチプロジェクト構成、あるいは単一プロジェクト内でのタスクグラフ制御の実装例を示す。
今回は、環境（`local`, `staging`, `production`）ごとにプロパティファイルを安全に切り替え、ステージごとにタスクを完全に分離する構成をとる。
プロジェクト構成
.
├── build.gradle
├── settings.gradle
└── src
├── main
│ ├── java
│ └── resources
│ ├── application.yml (デフォルト/フォールバック)
│ ├── application-local.yml
│ ├── application-staging.yml
│ └── application-production.yml
└── test
└── java
`build.gradle` の完全実装例
以下のスクリプトは、Gradleの `ext` プロパティとカスタムタスクを駆使し、明示的なステージングを実現している。
plugins {
id ‘java’
id ‘org.springframework.boot’ version ‘3.2.0’
id ‘io.spring.dependency-management’ version ‘1.1.4’
}
group = ‘com.enterprise.architecture’
version = ‘1.0.0-SNAPSHOT’
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
repositories {
mavenCentral()
}
dependencies {
implementation ‘org.springframework.boot:spring-boot-starter-web’
testImplementation ‘org.springframework.boot:spring-boot-starter-test’
}
// ==========================================
// ステージ制御のための環境変数マッピング
// ==========================================
// デフォルトは local。CI/CDパイプラインから -Penv=staging のように上書きする
ext.targetEnv = project.hasProperty(‘env’) ? project.getProperty(‘env’) : ‘local’
logger.lifecycle(“==========================================”)
logger.lifecycle(” [Pipeline Stage] Target Environment: ${targetEnv}”)
logger.lifecycle(“==========================================”)
// ==========================================
// Stage 1: テストステージ (Test Stage)
// ==========================================
tasks.named(‘test’) {
useJUnitPlatform()
// テスト実行時は必ずテスト専用のプロパティを強制する
systemProperty ‘spring.profiles.active’, ‘test’
// テストの出力詳細化（CIでのデバッグを容易にする）
testLogging {
events “passed”, “skipped”, “failed”
showStandardStreams = true
}
}
// ==========================================
// Stage 2: パッケージステージ (Package Stage)
// ==========================================
// 標準の bootJar を拡張し、指定された環境のプロファイルのみをjarに封印する
tasks.named(‘bootJar’) {
// テストステージが成功していることを強制的に依存関係で保証
dependsOn tasks.named(‘test’)
archiveClassifier = targetEnv
// 指定された環境以外の不要な設定ファイルをリソースから除外する（セキュリティとサイズ削減）
filesMatching(‘application.yml’) { file ->
if (!file.name.equals(“application.yml”) && !file.name.equals(“application-${targetEnv}.yml”)) {
file.exclude()
logger.info(“Excluded environment file from jar: ${file.name}”)
}
}
}
// ==========================================
// Stage 3: デプロイ準備ステージ (Deploy Prep Stage)
// ==========================================
// パッケージされた成果物を検証・モックデプロイする仮想ステージ
task prepareDeployment {
dependsOn tasks.named(‘bootJar’)
doLast {
def jarFile = tasks.named(‘bootJar’).get().archiveFile.get().asFile
logger.lifecycle(“>>> [Deployment Prep] Artifact ready for deployment: ${jarFile.absolutePath}”)
logger.lifecycle(“>>> [Deployment Prep] Size: ${jarFile.length() / (1024 1024)} MB”)
// ここにデプロイ先マニフェストの生成や、レジストリへのプッシュ前処理を記述
}
}
// パイプライン全体のオーケストレーション
task runPipeline {
dependsOn tasks.named(‘prepareDeployment’)
doLast {
logger.lifecycle(“>>> [Pipeline Success] All stages (Test -> Package -> DeployPrep) completed successfully for [${targetEnv}]!”)
}
}
—
4. この設計がもたらす実務上の圧倒的なメリット
上記の `build.gradle` を導入することで、チーム開発におけるリスクと無駄が劇的に排除される。
1. 意図しない環境変数の混入を防ぐ（セキュリティの担保）
`bootJar` タスク内の `filesMatching` 処理に注目してほしい。例えば `env=production` でビルドを走らせた場合、`application-staging.yml` や `application-local.yml` は最終的なJARから完全に削除される。これにより、デベロッパーのうっかりミスによる設定リークや、ローカル用の脆弱な接続情報が本番に持ち込まれるインシデントをビルドレベルで根絶する。
2. CI/CDパイプラインのスマート化
GitHub ActionsやGitLab CIなどのパイプライン定義が極めてシンプルになる。開発者は環境ごとに複雑なスクリプトを書く必要がなく、単に Gradle のパラメータを渡すだけでよ Administração できる。
GitHub Actions のワークフロー例
jobs:
build-and-pack:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up JDK 21
uses: actions/setup-java@v4
with:
java-version: ’21’
distribution: ‘temurin’
cache: ‘gradle’
# ステージを明示的に指定してパイプラインを実行
- name: Run Robust Pipeline
run: ./gradlew runPipeline -Penv=${{ inputs.environment }}
3. キャッシュの恩恵を最大限に受ける
テストが失敗した場合、Gradleは `test` タスクで処理を中断する（`dependsOn` の連鎖による）。重いSpring BootのレイヤードJARパッケージング（`bootJar`）の処理時間や、デプロイ先へのアップロード準備が無駄に実行されることがないため、CIのランニングコスト（クラウドのビルド時間課金）を直結して削減できる。
—
5. チーフエンジニアからのメッセージ
ツールに仕事をさせるな。ツールに「正しい制約」を与え、ヒューマンエラーが入り込む隙間をアーキテクチャで塞ぐことこそが、シニアエンジニア、そしてテックリードの仕事だ。
今回紹介したGradleによるマルチステージ・シミュレーションは、小さな工夫の積み重ねだが、チームのスケールに伴って確実に効いてくる。明日からのビルドスクリプトを見直し、誰が・どの環境で叩いても一貫した結果が得られる「堅牢なパイプライン」を構築してほしい。
君たちのコードベースが、より美しく、よりスケーラブルになることを期待している。