QuarkusでConfig・DI・Routesを整理した構成設計を完全解説！初心者でも迷わないプロジェクト構成

1. Quarkusで構成設計を意識する理由

1. Quarkusで構成設計を意識する理由

QuarkusはJava向けの軽量フレームワークで、最小限の設定ですぐに動く点が大きな魅力です。そのため、最初は「とりあえず動くコード」を書きやすく、初心者でも開発を始めやすい特徴があります。

しかし、その自由度の高さゆえに、Config（設定値）、DI（依存性注入）、Routes（リクエストの入口）を意識せずに書き進めると、どこに何が書いてあるのか分からない状態になりやすくなります。特に小さなサンプルから少しずつ機能を足していくと、この問題が表面化しがちです。

たとえば、設定値・処理・画面（API）の入口をすべて1つのクラスに書いてしまうと、後から修正する際に影響範囲が分からず、ミスにつながりやすくなります。これはプログラミング未経験者ほど陥りやすいポイントです。

構成設計を意識するとは、「役割ごとに置き場所を決める」ことです。設定はConfig、処理はService、入口はRoutesというように最初から考えておくことで、コードの見通しが一気に良くなります。

package org.example.simple;

public class HelloExample {

    public static void main(String[] args) {
        String message = "Hello Quarkus";
        System.out.println(message);
    }
}

上のサンプルは、すべてを1つのクラスに書いたシンプルな例です。学習初期では問題ありませんが、設定値や処理が増えると管理が難しくなります。Quarkusでは、このようなコードを役割ごとに分けていく考え方がとても重要になります。

最初の段階で構成設計を意識しておくことで、コードの読みやすさだけでなく、将来の修正や機能追加もスムーズに行えるようになります。

2. Configを整理する考え方

2. Configを整理する考え方

QuarkusのConfigは、アプリケーションの設定値を管理する重要な要素です。ポート番号、外部サービスのURL、環境ごとの設定など、変更されやすい情報をまとめて管理します。

設定値をコード内に直接書くのではなく、設定として切り出すことで、環境差分にも柔軟に対応できます。Configは「変更されやすいもの」と考えると分かりやすくなります。

Configを整理することで、ServiceやRoutesのコードがシンプルになり、可読性も向上します。

3. Configを扱うJavaクラスの例

3. Configを扱うJavaクラスの例

Quarkusでは、設定値をJavaクラスとしてまとめることで、型安全に扱えます。Configを専用のクラスにまとめることで、構成が分かりやすくなります。

package org.example.config;

import io.smallrye.config.ConfigMapping;

@ConfigMapping(prefix = "app")
public interface AppConfig {

    String name();
    String message();
}

このようにConfig専用のパッケージを用意すると、設定に関する責務が明確になり、他のコードと混ざらずに済みます。

4. DIを整理する設計の基本

4. DIを整理する設計の基本

DIは、Quarkusの中核となる仕組みです。ServiceやRepositoryなどのクラスを自動的に管理し、必要な場所に注入します。

DIを整理するポイントは、「処理の中心となるクラス」と「補助的なクラス」を分けて考えることです。Service層を中心にDIを構成すると、全体の流れが把握しやすくなります。

DIを意識して設計することで、クラス同士の依存関係が整理され、テストや修正も行いやすくなります。

5. ServiceでDIを活用する例

5. ServiceでDIを活用する例

Serviceは、Quarkusアプリケーションの処理をまとめる中心的な存在です。ConfigやRepositoryをDIで受け取り、ビジネスロジックを実装します。

package org.example.service;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import org.example.config.AppConfig;

@ApplicationScoped
public class MessageService {

    @Inject
    AppConfig appConfig;

    public String getMessage() {
        return appConfig.message();
    }
}

Serviceに処理を集約することで、Routes側のコードをシンプルに保てます。

6. Routesを整理する考え方

6. Routesを整理する考え方

Routesは、外部からのリクエストを受け取る入口です。Quarkusでは、REST APIやReactive Routesとして実装されます。

Routesでは、リクエストの受信とレスポンスの返却に専念し、処理の中身はServiceに任せるのが基本です。Routesが肥大化すると、可読性が一気に下がります。

「Routesは薄く、Serviceは厚く」を意識すると、構成が整理しやすくなります。

7. RoutesとServiceを分離した例

7. RoutesとServiceを分離した例

RoutesからServiceを呼び出す構成は、Quarkusで非常によく使われるパターンです。

package org.example.api;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import org.example.service.MessageService;

@Path("/message")
public class MessageResource {

    @Inject
    MessageService messageService;

    @GET
    public String message() {
        return messageService.getMessage();
    }
}

この構成により、Routesはルーティング、Serviceは処理という役割分担が明確になります。

8. Config・DI・Routesを整理するメリット

8. Config・DI・Routesを整理するメリット

Config、DI、Routesを整理した構成設計を行うことで、Quarkusプロジェクト全体の見通しが良くなります。どこに何を書くべきか迷いにくくなり、初心者でも安心して開発を進められます。

また、機能追加や修正時の影響範囲が限定されるため、保守性も大きく向上します。この考え方は、将来的に大規模なアプリケーションを作る際にも役立ちます。

Quarkusの柔軟さを活かすためにも、構成設計を意識した開発を心がけることが大切です。

まとめ

まとめ

ここまでQuarkusにおける構成設計の重要性と、Config、DI、Routesの役割分担について詳しく解説してきました。モダンなJava開発、特にクラウドネイティブなアプリケーション開発において、Quarkusが提供する強力な機能を最大限に引き出すためには、単にコードを書くだけではなく、「どこに何を配置すべきか」という設計思想を理解することが不可欠です。

Quarkus構成設計の三本柱を再確認

改めて、今回紹介した3つの要素を整理しましょう。まずConfig（設定管理）は、アプリケーションの振る舞いをコードの外から制御するための仕組みです。これを型安全なJavaインターフェースにマッピングすることで、環境変数やプロパティファイルの管理が格段に楽になります。次にDI（依存性の注入）は、各コンポーネントを疎結合に保ち、テストのしやすさと再利用性を高めるための心臓部です。最後にRoutes（エンドポイント）は、外部世界との窓口であり、ここはビジネスロジックを持たせずに「交通整理」に徹することが、保守性の高いコードへの近道となります。

これらの要素をバラバラに考えるのではなく、一つの流れとして捉えることが大切です。例えば、Configから取得した設定値をService層で加工し、それをRoutes層でレスポンスとして返すという一連の処理が、DIによって美しく繋がっていく様子をイメージしてみてください。

実践的なサンプルプログラム：ユーザー通知設定の管理

より具体的なイメージを掴むために、ユーザーへの通知機能を想定した少し高度なサンプルを見てみましょう。設定値によって通知の有効・無効を切り替え、DIを使ってサービスを組み立てる構成です。

1. Configクラスの定義

通知機能に関する設定をまとめます。application.propertiesに記述された設定値を安全に読み込みます。

package org.example.config;

import io.smallrye.config.ConfigMapping;
import io.smallrye.config.WithDefault;

@ConfigMapping(prefix = "notification")
public interface NotificationConfig {
    
    @WithDefault("true")
    boolean enabled();

    String defaultMessage();

    int maxRetry();
}

2. Serviceクラスでのロジック実装

設定値を注入し、実際の判定ロジックを記述します。ここでは@ApplicationScopedを使用して、アプリケーション全体で単一のインスタンスを管理します。

package org.example.service;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import org.example.config.NotificationConfig;

@ApplicationScoped
public class NotificationService {

    @Inject
    NotificationConfig config;

    public String processNotification(String userMessage) {
        if (!config.enabled()) {
            return "通知機能は現在無効化されています。";
        }
        
        String finalMessage = (userMessage == null || userMessage.isEmpty()) 
                                ? config.defaultMessage() 
                                : userMessage;
                                
        return "送信メッセージ: " + finalMessage + " (リトライ上限: " + config.maxRetry() + ")";
    }
}

3. Routes（Resource）での公開

APIの入り口です。ロジックはServiceに任せ、自分はパスの設定とリクエストの受け取りに集中します。

package org.example.api;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.MediaType;
import org.example.service.NotificationService;

@Path("/v1/notify")
public class NotificationResource {

    @Inject
    NotificationService notificationService;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String send(@QueryParam("msg") String msg) {
        return notificationService.processNotification(msg);
    }
}

開発効率を最大化するヒント

Quarkusの強みは、これらの構成を保ったままDev Modeによる高速なフィードバックサイクルを回せることです。コードを書き換えた瞬間に設定変更やDIの注入結果が反映されるため、設計の試行錯誤が非常にスムーズに行えます。

また、テストコードを書く際も、この構成であればService層だけを切り出してモック化したり、Configの値をテスト用に差し替えたりすることが容易になります。プロジェクトが成長し、チームメンバーが増えたとき、こうした「整理された構成」は最大の武器となるでしょう。

これからQuarkusで新しいプロジェクトを始める際は、まずパッケージ構成を考え、Config・DI・Routesの棲み分けをチーム内で合意することから始めてみてください。それが、モダンなJavaエンジニアとしての第一歩となります。