Quarkusプロジェクトのディレクトリ構成を完全ガイド！初心者でもわかる構成理解

Quarkusプロジェクトのディレクトリ構成を解説

先生と生徒の会話形式で理解しよう

生徒

「Quarkusのプロジェクト構成ってフォルダが多くて、どこに何を置けばいいのか迷ってしまいます…。」

先生

「Quarkusでは、Javaの開発者がすぐに理解できるように標準的な構成になっています。ひとつひとつのディレクトリがどんな役割なのかを覚えると、開発の効率がとても上がりますよ。」

生徒

「まずはどのフォルダが一番重要なんですか？」

先生

「それでは、実際のQuarkusプロジェクトのディレクトリ構成を見ながら、重要な場所を順番に解説していきましょう。」

1. Quarkusプロジェクトの基本ディレクトリ構成とは？

Quarkusのプロジェクトは、Javaの標準的なビルドツールであるMavenやGradleのルール（ソースコードはここ、設定ファイルはあそこ、という約束事）に従っています。そのため、他のJavaフレームワークを触ったことがある人には馴染み深く、プログラミング未経験の方にとっても「整理整頓のルール」が明確で学びやすいのが特徴です。

プロジェクトを作成すると、自動的に以下のような階層構造（ディレクトリツリー）が作られます。まずは、どこに何が入っているかの全体像を眺めてみましょう。


project-root/
 ├── src/                 # すべてのソースコードの親ディレクトリ
 │   ├── main/            # アプリの本番用コードや設定
 │   │   ├── java/        # Javaのプログラム本体（.javaファイル）
 │   │   ├── resources/   # 設定ファイルや画像、HTMLなど
 │   │   └── docker/      # コンテナ化（公開準備）のための設定
 │   └── test/            # プログラムが正しく動くか確認するテスト用
 ├── target/              # ビルド（実行できる形に変換）された成果物
 └── pom.xml (or build.gradle) # プロジェクトの設計図・依存ライブラリ管理

例えば、あなたが「画面に挨拶を表示する機能」を作りたい場合、プログラムの指示書は src/main/java に書き、その機能で使う設定（サーバーのポート番号など）は src/main/resources に書き込みます。このように、役割ごとに「部屋」が分かれているイメージです。

未経験の方が特に注目すべきは src/main/java です。ここには、以下のような実際の動作を決めるJavaコードを配置していきます。


package org.acme;

/**
 * 初めてのQuarkusプログラム例
 * このファイルは src/main/java/org/acme/GreetingResource.java として保存されます
 */
public class Greeting {
    public String sayHello() {
        // 画面に表示するメッセージを返すだけのシンプルな処理
        return "こんにちは！Quarkusの世界へようこそ。";
    }
}

この構成は、Quarkusの公式ツール（code.quarkus.ioなど）を使えば一瞬で自動生成されます。手動でフォルダを作る必要はありません。まずは「決められた場所に置けば、Quarkusが魔法のように動かしてくれる」という感覚を掴むことが、脱・初心者への近道です。

2. アプリケーションの心臓部：src/main/java の役割と実装

Quarkusでの開発において、最も頻繁に編集するのが src/main/java ディレクトリです。ここには、Webサイトの「受付窓口」となるリソースクラスや、複雑な計算を行う「業務ロジック」など、アプリケーションの核となるJavaプログラムを配置します。

プログラミング未経験の方でも安心してください。Quarkusの構造は非常にシンプルです。例えば、ブラウザに「Hello Quarkus!」という文字を表示させるだけの簡単なプログラム（REST API）は、以下のような短いコードで作成できます。


import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/hello") // ブラウザでアクセスするURLを指定します（例：/hello）
public class HelloResource {

    @GET // データを取得する「GET」リクエストを受け取るための指示です
    @Produces(MediaType.TEXT_PLAIN) // 返すデータの種類（今回は普通のテキスト）を指定します
    public String hello() {
        // この中身が実行され、戻り値がブラウザに表示されます
        return "Hello Quarkus! 初めてのJava開発へようこそ。";
    }
}

このコードを src/main/java 内に保存するだけで、Quarkusの強力な機能である「ライブコーディング（ホットリロード）」が作動します。通常、Javaではコードを変更するたびに再起動が必要ですが、Quarkusなら保存した瞬間に変更が反映されるため、ブラウザを更新するだけで結果をすぐに確認できます。この「待ち時間のなさ」が、モダンなJava開発における最大のメリットです。

3. src/main/resources に設定ファイル・静的ファイルをまとめる

src/main/resources は、Quarkusの設定ファイルやテンプレート、その他のリソースファイルを格納する場所です。特に重要なのが application.properties で、Quarkusの動作を細かく制御できます。


src/main/resources/
 ├── application.properties
 ├── META-INF/
 │   └── resources/ (静的ファイル)

META-INF/resources ディレクトリは、静的なHTMLやCSSを配置する特別な場所で、Quarkusではここに置いたファイルをルートパスから直接アクセスできます。


<!DOCTYPE html>
<html>
<head>
    <title>Quarkus App</title>
</head>
<body>
    <h1>Hello from Quarkus Static Resource!</h1>
</body>
</html>

4. test ディレクトリでユニットテストを管理する

Quarkusはテストにも強く、JUnitと自然に連携できるよう設計されています。REST APIの動作確認もテストで自動化できるため、テストコードを src/test/java に配置して品質を保つことが重要です。


import io.quarkus.test.junit.QuarkusTest;
import org.junit.jupiter.api.Test;

import static io.restassured.RestAssured.given;

@QuarkusTest
public class HelloResourceTest {

    @Test
    void testHelloEndpoint() {
        given()
          .when().get("/hello")
          .then()
             .statusCode(200);
    }
}

5. Maven または Gradle のビルドファイルがプロジェクト全体を管理する

Quarkusプロジェクトでは、依存関係やビルド設定をまとめるために pom.xml もしくは build.gradle を使用します。これらはプロジェクトの中心となる大事なファイルで、後からライブラリを追加するときにも編集することになります。


quarkus-resteasy
quarkus-smallrye-openapi
quarkus-jdbc-h2

依存関係を追加すると、Quarkusが自動的に必要な設定を検知してくれるため、開発効率が大幅に向上します。

6. target ディレクトリはビルド成果物の置き場

target は、Quarkusアプリケーションをビルドした結果を保存するためのディレクトリです。ここに生成される jar ファイルや native-image 用ファイルは、手動で編集する必要はありません。

ただし、実行ファイルを確認したいとき や Docker にコピーしたいとき に参照することがよくあります。

7. Quarkusプロジェクト構成を理解すると開発効率が劇的に上がる

ディレクトリ構成を理解すると、コードの置き場所に迷わなくなるだけでなく、Quarkusがどのようにアプリケーションを構築しているのかが自然と見えてきます。特に API 開発ではファイルが増えていくため、プロジェクト構成を正しく使うことが品質向上にもつながります。

Quarkusはシンプルな構造でありながら柔軟性が高いため、初心者でも短期間で理解でき、慣れると大規模開発でも十分活用できます。

まとめ

Quarkusプロジェクトのディレクトリ構成を理解する重要性

この記事では、Quarkusプロジェクトのディレクトリ構成について、初心者の方でも迷わず理解できるように順を追って解説してきました。 QuarkusはJavaベースのフレームワークでありながら、非常に整理されたプロジェクト構成を持っているため、各ディレクトリの役割を一度理解してしまえば、日々の開発が驚くほどスムーズになります。特に、src配下の構成を正しく把握することは、REST API開発や設定変更、テスト作成を行う上で欠かせません。

src/main/java にアプリケーションの中心となるJavaコードを配置し、 src/main/resources に設定ファイルや静的リソースをまとめるという考え方は、 Quarkusに限らず多くのJavaプロジェクトに共通しています。そのため、Quarkusで身につけたディレクトリ構成の理解は、将来的に他のJavaフレームワークへ取り組む際にも大いに役立ちます。プロジェクト全体の見通しが良くなることで、コードの保守性や可読性も自然と高まっていきます。

開発・設定・テストを分けて考える構成のメリット

Quarkusのディレクトリ構成は、「役割ごとに場所を分ける」という考え方に基づいています。アプリケーションのロジックは src/main/java、設定や静的ファイルは src/main/resources、テストコードは src/test/java と分離されているため、どこを編集すればよいのかが一目で分かります。この構成を意識することで、開発中にファイルの置き場所で迷うことがなくなり、作業効率が大きく向上します。

また、targetディレクトリの役割を理解しておくことで、ビルド成果物と開発用コードを明確に区別できるようになります。自動生成されるファイルを無闇に編集せず、必要なときだけ参照するという習慣が身につく点も重要です。 MavenやGradleのビルドファイルがプロジェクト全体を管理していることを意識すると、依存関係の追加やビルド設定の変更も安心して行えるようになります。

まとめ用サンプルプログラム

以下は、src/main/java に配置することを想定したシンプルなRESTリソースの例です。ディレクトリ構成を意識しながらコードを書くことで、 Quarkusプロジェクト全体の流れをより深く理解できます。


import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/structure")
public class StructureSummaryResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String summary() {
        return "Quarkusのディレクトリ構成を理解しました。";
    }
}

このようなクラスを src/main/java に配置し、 Dev Modeで起動すれば即座に動作確認ができます。ディレクトリ構成とコードの関係を意識しながら開発を進めることで、 Quarkusの仕組みがより立体的に見えてくるはずです。

先生と生徒の振り返り会話

生徒

「Quarkusのディレクトリ構成を一つずつ見ていったことで、どこに何を書くべきなのかがはっきり分かるようになりました。前よりもプロジェクト全体が見渡せる気がします。」

先生

「それはとても良い理解ですね。ディレクトリ構成を把握できるようになると、コードを書くスピードだけでなく、修正や調査も楽になります。」

生徒

「特にresourcesとjavaを分けて考える理由が分かりました。設定ファイルを触るときも迷わなくなりそうです。」

先生

「その感覚はとても大切です。構成を理解している人ほど、トラブル対応や機能追加がスムーズにできます。」

生徒

「これからは新しいクラスを作るときも、どのディレクトリに置くべきかを意識して開発していきます。」

先生

「ぜひ続けてください。 Quarkusのプロジェクト構成を理解することは、安定したJava開発への大きな一歩になりますよ。」

Java Gold保持者×現役PLによる直接指導【Quarkus・ネイティブJava実践】

【Quarkus実践】60分でネイティブJavaを完全攻略｜Java Gold保持者による実務直結ロードマップ

「Java Gold保持者」の視点で学ぶ。試験の罠と実務の境界線を60分で完全攻略。

「Quarkus」で次世代Java開発を極める。Java Gold保持者が教える、GraalVMネイティブイメージの衝撃。

KubernetesネイティブJavaの決定版、Quarkus。本講座では、コンテナ環境で圧倒的なパフォーマンスを誇る「爆速起動・超低メモリ」の仕組みをわずか60分で凝縮して学びます。単なる文法解説ではなく、Java Gold保持者の視点で、GraalVMによるネイティブコンパイルや、開発効率を劇的に高める「Live Coding」の本質を理解し、現場で即戦力として通用する実戦ルートを体験します。

具体的なワークショップ内容と実務スキル

【重点攻略テーマ】
モダンなクラウド基盤で必須となるQuarkusの拡張機能（Extensions）とエコシステムを徹底攻略。従来のSpring Bootとのアーキテクチャの違いや、ビルド時メタデータ処理による最適化を、現役PLの設計視点でロジカルに整理。リソース消費を最小化しつつ、開発生産性を最大化する「プロの設計解」を提示します。

【開発環境・ノウハウ】
Java Gold保持者だからこそ教えられる、ネイティブ化を想定した堅牢なコーディング制約を公開。ハローワーク職業訓練講師として培った「難解な分散システム理論を直感的に伝える」手法で、リアクティブプログラミングの基礎までを網羅的に伝授するカリキュラムです。