Quarkusプロジェクト構成の基本を完全解説！初心者でも迷わない「どこに何を書くか」ガイド

1. Quarkusプロジェクト構成を理解する意味

1. Quarkusプロジェクト構成を理解する意味

Quarkusのプロジェクト構成を理解することは、料理を始める前に「どこに包丁があり、どこに調味料があるか」を確認するのと似ています。Java開発に慣れていない初心者の方でもスムーズに開発を進められるよう、Quarkus（クオーカス）では役割ごとにフォルダが厳密に整理されています。

もし「どこに何を書くのか」という基本ルールを知らないままコードを書き始めると、後から「あのプログラムはどこに置いたっけ？」と迷子になり、修正や機能追加が非常に困難になってしまいます。特にクラウドネイティブな開発を支えるQuarkusでは、標準的な構成に従うことで、自動ビルドやテストの恩恵を最大限に受けることができます。

例えば、画面に「こんにちは！」と表示させるだけの簡単なプログラムを書く場合でも、以下のような「Javaのルール」に基づいた配置が必要になります。

package org.example;

// これは「挨拶」を返すだけのシンプルなプログラム（クラス）です
public class Greeting {
    public String sayHello() {
        return "こんにちは！Quarkusの世界へようこそ！";
    }
}

このようなJavaファイル一つとっても、適切なフォルダ（src/main/java）に配置しなければ、Quarkusはそれをプログラムとして認識してくれません。プロジェクト構成の全体像を掴むことは、エラーに悩まされない開発への第一歩であり、開発環境構築の次にマスターすべき最重要の基礎知識といえます。

2. src/main/java の役割：アプリの「心臓部」を作る場所

2. src/main/java の役割：アプリの「心臓部」を作る場所

Quarkusプロジェクトにおいて、最も頻繁に触れることになるのが src/main/java ディレクトリです。ここには、アプリケーションのメインとなるJavaのソースコードを配置します。

プログラミング未経験の方にとって、「どこに何を書けばいいか」は迷いやすいポイントですが、まずは「ユーザーに見せたい画面の裏側の処理」や「計算の仕組み」など、動く仕組みそのものはすべてこの中に入れる、と覚えておきましょう。ここに作成したプログラムが、Quarkusによって自動的に読み込まれ、Webアプリとして機能するようになります。

package org.example;

/**
 * 挨拶メッセージを返すだけのシンプルなプログラム（クラス）です。
 * 初心者の方は、まずこのような「部品」をここに追加していくことから始めます。
 */
public class GreetingService {

    public String sayHello() {
        // 画面に表示したいメッセージを返します
        return "こんにちは！Quarkusの世界へようこそ。";
    }
}

上記のサンプルコードのように、ビジネスロジック（特定の目的を果たすための処理）を記述したクラスを src/main/java 配下に配置することで、Quarkusの強力な機能である「ホットリロード（コードを書き換えると即座に反映される機能）」の恩恵を最大限に受けることができます。特別な設定ファイルを編集しなくても、Javaファイルを保存した瞬間にあなたの作ったプログラムが有効になります。

3. src/main/resources の役割

3. src/main/resources の役割

src/main/resourcesは、Javaコード以外の設定ファイルを置く場所です。Quarkusでは、このフォルダが非常に重要な役割を持ちます。

代表的なのが、application.propertiesやapplication.yamlです。ポート番号やアプリケーション名など、動作に関わる設定はここにまとめて書きます。

quarkus.application.name=sample-app
quarkus.http.port=8080

初心者がよく躓くのは、設定ファイルをsrc/main/javaに置いてしまうことです。設定ファイルは必ずsrc/main/resourcesに置く、と覚えておくとミスを防げます。

4. src/test/java と src/test/resources

4. src/test/java と src/test/resources

Quarkusプロジェクトには、テスト用のフォルダも用意されています。それがsrc/test/javaとsrc/test/resourcesです。

src/test/javaには、テスト用のJavaクラスを置きます。アプリケーション本体とは別に管理されるため、本番コードと混ざりません。

src/test/resourcesは、テスト専用の設定ファイルやデータを置く場所です。初心者のうちは、存在を知っておくだけでも十分です。

5. pom.xml または build.gradle の役割

5. pom.xml または build.gradle の役割

Quarkusプロジェクトのルートには、pom.xmlやbuild.gradleといったファイルがあります。これは、依存関係やビルド設定を管理するための重要なファイルです。

Quarkusで使う拡張機能やライブラリは、ここに追加します。Javaクラスとは違い、処理を書く場所ではありませんが、プロジェクト構成の中心となる存在です。

初心者は、まず「依存関係を管理する設定ファイル」として認識しておくと理解しやすくなります。

6. パッケージ構成はどう考える？

6. パッケージ構成はどう考える？

src/main/javaの中では、パッケージを使ってクラスを整理します。Quarkusでは、厳密なルールはありませんが、役割ごとに分けるのが一般的です。

たとえば、API用、サービス用といった形で分けることで、どこに何があるか分かりやすくなります。最初は小さな構成でも問題ありません。

「増えてきたら分ける」くらいの感覚で始めると、初心者でも無理なく進められます。

7. Quarkusプロジェクト構成で迷わないコツ

7. Quarkusプロジェクト構成で迷わないコツ

Quarkusのプロジェクト構成で迷わないための一番のコツは、「役割で場所を覚える」ことです。Javaコードはsrc/main/java、設定はsrc/main/resources、と役割で覚えるだけでも混乱が減ります。

すべてを最初から理解しようとせず、必要になった場所から少しずつ覚えていくのがおすすめです。Quarkusはシンプルな構成でも十分に動くため、初心者でも安心して学習を進められます。

まとめ

まとめ

Quarkusプロジェクト構成を振り返って理解を深めよう

ここまで、Quarkusプロジェクト構成の基本について、src/main/java、src/main/resources、src/test/java、src/test/resources、そして設定ファイルであるpom.xmlやbuild.gradleの役割を順番に確認してきました。 Quarkusは高速起動や軽量実行といった特徴が注目されがちですが、実際の開発では「プロジェクト構成を正しく理解しているかどうか」が、学習効率や保守性に大きく影響します。 特に初心者のうちは、どこにJavaクラスを書くのか、設定ファイルはどこに置くのかが曖昧なまま進めてしまい、動かない原因が分からずに悩むことが少なくありません。

Quarkusでは、Javaコードはsrc/main/java、設定やプロパティはsrc/main/resourcesというように、役割ごとに配置場所が明確に分かれています。 この構成は、Java開発の基本的な考え方とも共通しており、一度理解すればSpring Bootなど他のフレームワークを学ぶ際にも役立ちます。 プロジェクト構成を理解することは、単なるフォルダの暗記ではなく、「このファイルは何のために存在するのか」を意識することが重要です。

また、テスト用のsrc/test/javaやsrc/test/resourcesは、最初のうちは触る機会が少ないかもしれませんが、本番コードとテストコードを分離するという考え方を早い段階で知っておくことで、 将来的に品質の高いアプリケーションを作る土台になります。 Quarkusのプロジェクト構成は、初心者が成長していく過程でも無理なく拡張できるように設計されているため、焦らず段階的に理解していきましょう。

まとめとしてのサンプルプログラム確認

最後に、今回学んだ内容を踏まえたシンプルなサンプル構成をもう一度確認してみます。 Javaクラスはsrc/main/java配下、設定はsrc/main/resources配下という基本を意識するだけでも、プロジェクト全体の見通しが良くなります。

package org.example.summary;

public class SummaryService {

    public String summaryMessage() {
        return "Quarkus プロジェクト構成の理解が深まりました";
    }
}

このようなクラスを正しい場所に配置することで、Quarkusは自動的にクラスを認識し、特別な設定を追加しなくても動作します。 プロジェクト構成を意識してコードを書く習慣を身につけることで、後から機能追加や修正を行う際にも迷いにくくなります。