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

生徒

「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 ディレクトリです。この中に、REST APIを実装するリソースクラスや、サービスロジック、依存性注入（CDI）を使ったクラスなどが配置されます。Java初心者でも迷わないシンプルな構造になっているため、クリーンに開発を進められます。


import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@Path("/hello")
public class HelloResource {

    @GET
    public String hello() {
        return "Hello Quarkus!";
    }
}

このようなシンプルなRESTエンドポイントを追加すると、QuarkusのDev Modeで即座にホットリロードされ、すぐにブラウザで動作確認ができます。

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を分けて考える理由が分かりました。設定ファイルを触るときも迷わなくなりそうです。」

先生

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

生徒

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