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

生徒

「QuarkusでREST APIを作っているんですが、エラーが起きたときの処理をどう書けばいいか迷っています…」

先生

「Quarkusでは例外ハンドリングを設計として整理しておくと、コードが読みやすくなり、保守もしやすくなります。」

生徒

「とりあえずtry-catchを書いているんですが、それだけではダメなんでしょうか？」

先生

「場当たり的に書くより、Quarkusのプロジェクト構成に合わせて例外ハンドリングを設計するのが大切です。順番に整理していきましょう。」

1. Quarkusアプリにおける例外ハンドリングの重要性

Quarkusアプリの例外ハンドリング設計は、Javaアプリケーションの品質を左右する重要な要素です。例外処理が適切でないと、原因不明のエラーや分かりにくいレスポンスが発生し、利用者にも開発者にも負担がかかります。特にREST APIを提供するQuarkusアプリでは、エラー内容を正しく伝える設計が欠かせません。

初心者のうちはtry-catchでエラーを握りつぶしてしまいがちですが、それでは問題の発見が遅れたり、ログに必要な情報が残らなかったりします。 Quarkusのプロジェクト構成に合わせて例外ハンドリングを整理することで、安定したJavaアプリを作れます。

2. Javaの例外とQuarkusでの考え方

QuarkusはJavaをベースとしたフレームワークなので、例外の基本はJavaの例外機構と同じです。 RuntimeExceptionやチェック例外といった仕組みを理解しておくことが前提になります。ただし、Quarkusではフレームワーク側で例外をまとめて扱える仕組みが用意されています。

そのため、すべての場所でtry-catchを書くのではなく、例外を投げて上位でまとめて処理する設計が推奨されます。この考え方を身につけることで、Quarkusアプリ全体の見通しが良くなります。

3. プロジェクト構成と例外クラスの分離

Quarkusアプリの例外ハンドリング設計では、例外クラスを専用パッケージにまとめるのが基本です。ビジネスロジックと例外定義を分離することで、コードの役割が明確になります。これはJava初心者が設計を学ぶうえでも大切なポイントです。


package com.example.exception;

public class BusinessException extends RuntimeException {

    public BusinessException(String message) {
        super(message);
    }
}

このように独自例外を定義しておくことで、業務エラーとシステムエラーを分けて扱えるようになります。 Quarkusのプロジェクト構成に自然に組み込める設計です。

4. サービス層での例外の投げ方

Quarkusアプリでは、サービス層で業務的なエラーを検出したら例外を投げます。その場でレスポンスを返そうとせず、責務を明確にすることがポイントです。 Javaの設計としても基本的な考え方です。


package com.example.service;

import com.example.exception.BusinessException;

public class UserService {

    public String findUser(String id) {
        if (id == null) {
            throw new BusinessException("ユーザーIDが指定されていません");
        }
        return "user-data";
    }
}

このように例外を投げるだけにすることで、サービス層の役割が明確になり、テストもしやすくなります。

5. REST層での例外ハンドリング設計

QuarkusのREST APIでは、例外をそのまま返すのではなく、利用者に分かりやすいレスポンスへ変換する設計が重要です。そのために例外ハンドラを用意します。


package com.example.resource;

import com.example.exception.BusinessException;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.ExceptionMapper;
import jakarta.ws.rs.ext.Provider;

@Provider
public class BusinessExceptionMapper implements ExceptionMapper<BusinessException> {

    @Override
    public Response toResponse(BusinessException exception) {
        return Response.status(Response.Status.BAD_REQUEST)
                .entity(exception.getMessage())
                .build();
    }
}

この仕組みにより、Quarkusアプリ全体で統一された例外レスポンスを返せます。プロジェクト構成の中で例外ハンドリングを集約できる点が大きなメリットです。