ORMにはうんざり！第4回：ログ出力と例外処理の共通化でJava開発効率を上げる

エンジニアであれば一度は経験するのが「どこでエラーが起きたかわからない」「ログが出ていないから原因が追えない」といった苦痛なデバッグ作業。

第4回では、そんな悩みを解消するための共通ログ出力クラスと例外処理の統一実装について詳しく解説します。

この共通DBアクセスクラス群では、あらゆるSELECT・INSERT・UPDATE・DELETE処理に対して、ログ出力と例外制御が自動で組み込まれているのが大きな特徴です。その中心を担うのが Logger、LogWriter、そして SystemException の3つのクラスです。

これらは単なる便利クラスではなく、全体設計を支える基盤インフラです。今回の記事では、なぜこのような構成にしたのか、どう使えばエラーを確実にログとして残せるのか、system.xmlとの連携をどう実現しているのかを、コードと一緒に掘り下げていきます。

「ログ忘れ」「例外握り潰し」とはもうサヨナラ。開発効率を大幅に上げるための“設計の背骨”、ここで一緒に理解していきましょう。

本シリーズで使用する共通DBアクセスクラスの検証には、PostgreSQLを利用しています。テストデータには、日本郵便が提供している全国一括の郵便番号CSV（15列構成）を使用し、住所情報を登録・検索・更新する処理を通じて、各クラスの動作を確認しています。ソースコード一式はGitHubに保管しており、テーブル構成やクラス構造を含めてすべて確認可能です。再現性のある実装環境を前提として設計されています。

👉 GitHubリポジトリ： https://github.com/bepro-engineer/db-access-core

共通ログ出力クラスの構成と役割

共通データアクセスクラス群において、ログ出力処理は設計の根幹を支える要素です。

開発の現場では、ログの出力忘れや例外発生時の情報欠損により、障害調査が難航することが多くあります。

この課題を解消するため、本システムではLoggerとLogWriterという二つのクラスを明確に役割分担させることで、ログ出力の一元管理と制御を実現しています。

ログ出力は開発者が意識せずとも自動的に出力され、例外時には即座にログとして記録されます。さらにログレベルに応じた出力制御が可能な設計とすることで、不要な冗長出力を防ぎ、保守性と視認性の高い運用を実現します。

LoggerとLogWriterの機能分担

LoggerとLogWriterは、それぞれ異なる責務を持ちつつ密接に連携しています。Loggerクラスはアプリケーションが直接呼び出すログインターフェースを提供し、LogWriterクラスは実際のログファイル書き込み処理を担当します。

このように責務を分離することで、Loggerでは出力形式や制御ロジックに集中でき、LogWriterでは書き込み先やファイル出力処理に特化することができます。

下記にLoggerとLogWriterの役割の違いをまとめた表を示します。

この構成により、Loggerはどの処理からも統一的に呼び出される中心的なインターフェースとして機能し、LogWriterはその下層でシステムの出力処理を担う安定的な基盤となります。

共通DBアクセスクラスのログ出力処理は、プロジェクト全体の保守性や運用効率に直結します。まだLoggerクラスの実装に不安がある方は、まずこちらの記事でシンプルな共通ログ出力クラスの考え方を確認しておくと理解が深まります。
▶︎ 【Javaの基礎知識】設定地獄はもう嫌！シンプルな共通ログ出力クラスを作ってみた

Beエンジニア

【Javaの基礎知識】設定地獄はもう嫌！シンプルな共通ログ出力クラスを作ってみた

https://www.pmi-sfbac.org/java-practical-12-simple-logger

もう細かい設定や複雑なライブラリに振り回されたくないと思いませんか？　Javaでログ出力を行うとき、多機能なOSSの導入や膨大な設定ファイル作成に時間を取られがちです。そこで今回は、最小限の機能で即使える、自作のシンプルなログ出力クラスを紹介します。初心者から実務者まで使いやすく、開発効率を大幅に改善する実践的な内容です。共通ログ出力クラスの概要と役割Javaで開発を行う際にログ出力は必須の仕組みです。しかしプロジェクトによってログの実装方法は統一されておらず、ログ管理が煩雑になることがあります。特に小...

ログ出力の呼び出し方法と構造

ログ出力は、全ての共通データアクセスクラスにおいて自動で組み込まれるよう設計されています。基本的にはLoggerクラスのoutメソッドを呼び出すだけで、必要なログが出力されます。

呼び出し形式は以下のようになります。

Logger.out(Logger.INFO, "DbAccessSelect#execute()", "user0001", "SQL実行開始");

このように、ログ出力には以下の4つの情報を明示的に渡します。

この4項目により、ログは誰が、どのクラスのどの処理で、何を行ったかを一貫して記録することができます。また、ログ出力の場所を意識しなくても、doSelectやdoExecなどの共通関数の中でログが自動的に挿入されるよう設計されており、出力忘れを防ぐ仕組みになっています。

ログレベルと出力制御の仕組み

ログ出力の制御は、system.xmlに設定されたログレベル情報をもとに、Loggerクラスがフィルタリングを行う設計になっています。ログレベルは以下のような段階で分類されています。

例えば、system.xmlにてログレベルが「INFO」に設定されている場合、DEBUG2やDEBUG3のログは出力されません。これにより、本番環境ではINFO以上、開発・検証環境ではDEBUG3まで出力するという切り分けが可能となっています。

この仕組みはLogger.init()メソッドの初期化時に自動的に読み込まれます。実装上は以下のように初期化されます。

Logger.init(logFilePath, logFileName, logLevel);

また、LogWriterはログレベルごとに別ファイル出力を行うように設計することも可能で、将来的なログ分割運用にも柔軟に対応できます。

ログ出力設定とsystem.xmlの連携構成

共通DBアクセスクラス群では、ログ出力に関する設定を外部ファイルであるsystem.xmlに集約することで、実行環境ごとのログレベル切り替えや出力先の変更を容易にしています。

この仕組みにより、ソースコードを一切修正せずにログ運用方針を変更できる柔軟性が生まれ、保守性の高い設計となっています。

本章では、system.xmlの構造からLoggerクラスとの連携、実際のログ出力レベルに応じた制御方法までを具体的に解説します。

system.xmlのlogセクション構造

system.xmlファイルは、アプリケーション全体の動作パラメータを一元管理する設定ファイルです。この中でもlogセクションはログ出力に関する重要な設定を保持しており、主に以下のような構成で記述されています。

<database>
    <password>postgres</password>
    <url>P@ssW0rd</url>
    <connect>20</connect>
    <driver>jdbc:postgresql://localhost:5432/postgres</driver>
    <object_id>OID</object_id>
</database>
<log>
  <filepath>/Users/bepro/Work/Java/logs</filepath>
  <logfile>application.log</logfile>
  <level>INFO</level>
</log>

各タグが持つ意味は以下の通りです。

このように、ログ出力に関わる項目は全てsystem.xmlに記述され、コード側では読み取り処理のみを行う設計となっています。これにより、本番環境と開発環境で出力内容を簡単に切り替えることが可能になります。

Loggerの初期化とSystemInfoの関係

Loggerクラスは、アプリケーション開始時にsystem.xmlの設定値をもとに初期化処理を行います。その役割を担うのが、SystemInfoクラスを通じた設定取得処理です。

SystemInfoクラスは、system.xmlを読み込んでHashMap（旧構成ではHashtable）に変換し、設定値の取得インターフェースを提供する構成になっています。

以下のようなコードでログ設定値を取得します。

Map logConfig = SystemInfo.getKeyValueHash("log");
String logLevel = logConfig.get("level").toUpperCase();
String logPath = logConfig.get("filepath");
String logFile = logConfig.get("logfile");

これにより、Loggerは下記のように初期化されます。

Logger.init(logPath, logFile, logLevel);

この初期化を行うことで、Loggerは以降の全てのログ出力に対して、適切なファイルとレベル設定を維持しながら書き込みを行うことが可能となります。これらの処理はアプリケーションの起動直後に一度だけ行われるため、ログ出力の安定性が確保されます。

ログレベルに応じた出力分岐と運用パターン

ログレベルは、system.xmlの設定によって制御されるフィルターのような役割を果たします。Loggerクラスは、ログ出力時に設定されたログレベルと出力リクエストのログレベルを比較し、出力対象とするかどうかを判断します。

たとえば、system.xmlでログレベルが「INFO」に設定されている場合、DEBUG2やDEBUG3のログは出力されません。これにより、本番環境では重要なログだけを記録し、開発環境では詳細なトレースが取得できるといった使い分けが実現できます。

ログ出力の制御処理は以下のように記述されています。

if (isTargetLevel(level)) {
  LogWriter.write(logPath, logFile, level, message);
}

ここで、isTargetLevelはログレベルの優先度を判定する関数であり、ログ出力の対象かどうかを論理的に判定します。

この仕組みにより、アプリケーション全体で一貫したログ制御が可能となり、コード上での細かな出力分岐を意識する必要がなくなります。 また、system.xmlを再読み込みすれば、アプリケーションを停止せずにログレベルを変更する仕組みも実装可能です。

これにより、障害発生時のみ一時的にログレベルを下げて詳細出力を取得するなど、柔軟な運用が可能になります。 運用例を以下に示します。

このような運用パターンを事前に整理しておくことで、ログ出力の目的を明確にし、不要なファイル肥大化や情報漏洩のリスクを回避できます。

共通例外クラスSystemExceptionの設計思想

Javaでの開発において、例外処理は実装の一貫性と保守性に大きく影響する重要なポイントです。

独自の共通例外クラスを定義せず、個別にtry-catchを記述したり、例外のログ出力を忘れてしまうと、障害時に原因を特定できない事態に陥りやすくなります。

この問題を解消するため、本システムではSystemExceptionという共通例外クラスを設計し、全てのデータアクセス処理に例外制御を自動組み込みしています。

この設計により、エラー発生時には自動的にログ出力が行われ、エンジニアが手動でログ記述を行う必要がなくなります。

SystemExceptionの基本構造と使い方

SystemExceptionはJavaのExceptionクラスを継承した独自例外クラスであり、コンストラクタで渡されたエラーメッセージや発生箇所をそのまま保持しながら、ログ出力までを一括して行う仕組みを内包しています。

通常の使用方法は非常にシンプルで、エラーを検知した箇所で以下のようにSystemExceptionをthrowするだけです。

if (conn == null) {
  throw new SystemException("DbConnectionPool#getConnection", "接続が取得できませんでした");
}

このように、第一引数でエラー発生元（クラス名#メソッド名）、第二引数でエラーメッセージを渡すことで、SystemExceptionクラスの内部でログ出力処理が実行されます。 SystemExceptionの主な内部構成は以下のようになっています。

このように、SystemExceptionは「例外の発生」と「ログの記録」を完全に一体化して処理するため、開発者側のミスや漏れが起きにくい設計となっています。

ログ出力と例外通知の自動連携

SystemExceptionを用いる最大のメリットは、例外発生と同時にログ出力が自動的に実行されることです。これにより、すべての異常終了ポイントにおいて、確実にログが残る運用が実現できます。 ログ出力の形式は以下のように統一されています。

[ERROR] DbAccessInsert#execute() user0001 登録処理で例外発生（テーブル名: USERS）

このログは、SystemExceptionのコンストラクタ内でLogger.outメソッドが呼び出されることで出力されます。ログレベルは強制的にERRORが適用されるため、system.xmlでINFOやDEBUGが指定されていても例外ログは必ず出力されます。 実装イメージは以下の通りです。

Logger.out(Logger.ERROR, classMethod, "", message);

この処理により、発生した例外が記録漏れすることなくログとして保存され、運用チームが即時に障害を把握できる環境が整います。 また、通知用のメールやSlack連携などと組み合わせることで、SystemExceptionによる通知トリガーの外部展開も可能となります。

例外ラップによる運用の簡素化

SystemExceptionは、既存のSQLExceptionやIOExceptionなどの標準例外をラップして再スローする運用にも対応しています。

これはJavaにおける例外ハンドリングのベストプラクティスであり、アプリケーション全体の例外処理を共通インターフェースに集約するために重要な考え方です。

例えば、SQLExceptionを受け取った場合、以下のようにSystemExceptionに変換して上位へthrowします。

} catch (SQLException e) {
  throw new SystemException("DbAccessSelect#execute", "SQL実行に失敗しました：" + e.getMessage());
}

このように変換することで、呼び出し側はすべての例外をSystemExceptionとして扱うことが可能になり、処理系の統一、ログ形式の統一、エラーメッセージの整合性が確保されます。

また、SystemExceptionを受け取った上位層では、以下のようにユーザー向けのエラーメッセージや画面遷移などを行うことができます。

catch (SystemException se) {
  // ログはすでに出力済みなので、画面にだけ通知
  request.setAttribute("error", "データベース処理中に問題が発生しました");
}

このような構造を全体に適用することで、例外発生時の処理が非常にシンプルかつ明瞭になり、バグの混入リスクを大幅に低減できます。

さらに、SystemExceptionのコンストラクタをオーバーロードし、元例外（Throwable）を受け取るパターンも追加することで、StackTraceを保持したままのラップ例外が可能になり、デバッグ時の情報欠損も防げます。

DBアクセス処理へのログと例外処理の組み込み

共通DBアクセスクラス群では、Loggerによるログ出力とSystemExceptionによる例外制御が、すべてのアクセス処理に自動で組み込まれています。

開発者は個別にログ記述や例外スローのコードを書く必要がなく、アクセスクラス内での統一的なtry-catch構造と共通ロジックにより、安全で保守性の高い処理フローが実現されています。

このセクションでは、実際の構成クラスに基づき、Logger.outとSystemExceptionがどのように活用されているのか、各アクセスクラスにどう組み込まれているのかを具体的に解説します。

Logger.outとSystemExceptionの自動適用の構造

Loggerクラスは、ログ出力の中心を担う共通部品です。system.xmlの設定により出力パスやログレベルが制御され、任意の処理から共通形式でログを残すことができます。 出力形式は以下のように、4つのパラメータで構成されます。

Logger.out(Logger.INFO, "DbAccessSelect#execute", "user0001", "SELECT処理を開始します");

この呼び出しは以下のような意味を持ちます。

また、SystemExceptionは、例外発生時にLoggerを自動的に呼び出してログを出力する構造を持っています。例外クラスでありながら、Loggerとの統合処理を内部に備えているため、明示的なログ出力処理を記述しなくても、例外が発生した時点でログが残ります。

throw new SystemException("DbAccessInsert#execute", "登録時にSQL例外が発生しました");

このようなラップ構造によって、例外の検出・ログ出力・上位通知までを一括で行えるようになります。

各アクセスクラスに組み込まれたtry-catchの共通設計

共通DBアクセスクラスでは、DbAccessSelect、DbAccessInsert、DbAccessUpdate、DbAccessDeleteといった個別のクラスに対して、同一の設計思想が適用されています。

各クラス内では、以下のような形でtry-catch構造が定義されており、Logger.outやSystemExceptionの呼び出しが組み込まれています。

public boolean execute() throws SystemException {
  try {
    Logger.out(Logger.INFO, "DbAccessUpdate#execute", "user0001", "更新処理開始");
    // SQL実行ロジック
    Logger.out(Logger.INFO, "DbAccessUpdate#execute", "user0001", "更新完了");
    return true;
  } catch (SQLException e) {
    throw new SystemException("DbAccessUpdate#execute", "SQL実行失敗：" + e.getMessage());
  } }

このように、例外の発生に応じてSystemExceptionが自動的にログ出力を行い、かつエラー状態を上位に通知します。

どのクラスにおいてもこのtry-catch構成はほぼ同一であり、開発者は個別にエラー処理のロジックを毎回実装する必要がありません。

この統一構成は、開発効率の向上だけでなく、ログ出力の一貫性、例外設計の標準化、保守性の向上にもつながっています。

ログ記録と例外ラップの一体化による保守性向上

ログ出力と例外処理を明確に分けず、「例外をスローすれば自動でログが出力される」という構成を採用することで、運用面にも多くのメリットが生まれています。 たとえば、以下のような開発上の課題が改善されました。

また、Loggerのログレベル制御により、INFOレベル以上で運用ログ、DEBUG2/DEBUG3レベルでSQLパラメータやレコード内容といった詳細ログを分けて記録することが可能です。

これにより、検証環境と本番環境で出力内容を変える運用も容易に実現できます。 SystemExceptionには元例外（Throwable）を受け取るオーバーロードコンストラクタも用意されており、StackTrace付きのラップが可能なため、調査時にも詳細な原因解析が行えます。

throw new SystemException("DbAccessSelect#execute", "検索に失敗", e);

このように、例外の内容を隠さず、正確なエラー位置と内容をそのまま記録・通知できる構造は、運用中の障害調査の負担を大きく軽減します。

運用上の注意点と設計メリット

共通DBアクセスクラス群においては、LoggerやSystemExceptionによってログ出力や例外通知が統一され、日常的な運用や障害対応の効率が飛躍的に向上します。

しかし、システムの動作は設定ファイルに大きく依存しているため、ログ出力が正しく機能しない場合や、例外の取り扱い方を誤ることで、意図しない動作になることもあります。

このセクションでは、運用面で注意すべきポイントと、共通設計によって得られるメリットについて具体的に解説します。

設定ミスによるログ出力不可の対処方法

Loggerクラスは、system.xmlファイルのlogセクションに定義されたパスとファイル名を元に、ログ出力先を初期化します。

このとき、設定値が不正だったり、出力先ディレクトリに書き込み権限がない場合、ログファイルが生成されない、あるいはアプリケーション自体が例外で終了する可能性があります。

設定項目は以下の3つが最低限必要です。

例えば以下のような設定がされているとします。

<log>
  <filepath>/Users/bepro/Work/Java/logs</filepath>
  <logfile>application.log</logfile>
  <level>INFO</level>
</log>

この場合、/Users/bepro/Work/Java/logs ディレクトリが存在しないか、Java実行ユーザーに書き込み権限がないと、ログは出力されません。

そのため、初期化処理でパスの存在確認と、IOExceptionのキャッチ処理をLogger側で適切に記述しておく必要があります。

また、Logger.init()に失敗した場合でも、標準出力にメッセージを出すか、異常終了せずにSystem.errへ退避出力するなどの対応が求められます。

SystemExceptionの投げ方と例外設計の原則

SystemExceptionクラスは、アプリケーション共通のラップ例外として設計されています。 例外の内容と発生箇所を明確に記録し、ログと連動して自動的に出力処理を行うため、個別にログを出力するコードを記述する必要がありません。 基本的な使い方は以下のとおりです。

throw new SystemException("DbAccessSelect#execute", "SQL実行に失敗しました");

この書き方を統一することで、ログファイルには次のような情報が記録されます。

[ERROR] DbAccessSelect#execute SQL実行に失敗しました

また、元例外（Throwable）を保持するためのオーバーロードコンストラクタも用意されています。

throw new SystemException("DbAccessSelect#execute", "SQLエラー発生", e);

これにより、catchブロックで例外内容を握りつぶすことなく、StackTrace付きで再スローできます。

例外処理の原則としては、以下の3点を守ることが重要です。

SystemExceptionはこれらの要件を満たすために存在しており、DBアクセス層だけでなく、他のバッチ処理やWebAPI層にも転用可能です。

共通化による保守性とミス防止の効果

ログ出力や例外処理が個別実装になっていると、次のような問題が発生しやすくなります。

この共通化により、コードレビューの際には処理の本質だけに集中でき、記述ミスのチェックにかかる時間を大幅に削減できます。

また、誰がどのクラスを書いても同じように例外が記録されるため、障害調査の負荷も軽減されます。特に障害対応においては、ログ出力の統一が極めて大きな効果をもたらします。

本番環境で障害が発生した際も、ログファイルの中から瞬時に異常を検出できるため、初動対応が格段に早くなります。また、ログレベルによるフィルタリング運用を組み合わせることで、環境ごとに出力内容を制御できるのも大きな利点です。

この柔軟性と安全性が、LoggerとSystemExceptionの導入効果を支えています。

次回予告：共通クラス群の実運用とユースケース展開

これまで第1回から第4回にかけて、共通DBアクセスクラス群の構成、SQL生成、ログ出力、例外処理まで一貫した設計と実装について解説してきました。

各処理クラスがどう設計されているか、どのように共通化されているかを把握することで、このクラス群が単なる部品ではなく、業務アプリケーション全体の基盤としてどれほど重要な役割を果たしているかが明確になったと思います。

次回からは、この共通クラス群が実際のシステムにおいてどのように活用されているのか、具体的なユースケースと組み込み方について紹介していきます。

想定するユースケースとシステム構成の全体像

共通DBアクセスクラス群は、一般的な業務アプリケーション全般で利用可能ですが、とくに以下のような構成で強力に機能します。

これらのユースケースでは、SQLを外部に切り出さずコード側で完結させる設計が非常に有効に働きます。SQLの構文も定数クラスで一元管理されているため、変更箇所を追いやすく、障害調査も容易です。

共通クラス群を導入するタイミングと設計指針

共通クラス群の導入は、プロジェクトの初期段階で行うのが最も効果的です。

テーブル設計が固まった後、業務処理の流れに沿ってクラスとメソッドを分割・整理し、アクセス制御やエラーハンドリングも同時に共通化することで、設計と実装の分離が自然に行えます。

もし既存システムに後から導入する場合は、以下のような優先順位での置き換えが効果的です。

これにより、段階的にクラスの差し替えを行いながら、既存ロジックとの整合性を保ちつつ導入を進めることが可能です。

ユースケースごとのクラス構成例と設計ポイント

次回から紹介するユースケース別の実装例では、以下のようなクラス設計構成が登場する予定です。

DbAccessUserSelect：ユーザー情報を取得するSELECT処理の実装クラス DbAccessStockUpdate：在庫情報を一括更新するUPDATE処理の実装クラス DbAccessCsvInsert：CSVデータを解析して複数テーブルに登録するINSERT処理クラス これらのクラスは、いずれも共通のインターフェース（IDbAccessBean）を実装し、 DbAccessControllerから呼び出されることで、処理の実行とログ出力が一体化されています。

DbAccessController controller = new DbAccessController();
controller.doExec(new DbAccessUserSelect(), dataBean);

このように、呼び出し元はどのクラスであっても統一的な操作が可能となり、 メンテナンス性の高いシステム運用が実現できます。 また、各ユースケースの解説では、テストケースやSQL出力例、ログ結果のサンプルなども掲載予定です。

これにより、読者が自分の環境に合わせて導入できるよう、実践的な参考になる内容に仕上げていきます。

次の第5回では、例外処理とログ設計に焦点を当て、障害対応に強いシステムを支えるエラーハンドリングの仕組みを解説します。SystemExceptionとLoggerを連携させることで、トラブルの早期発見・迅速な原因特定を可能にし、開発現場の実用性を高める設計思想を掘り下げます。ログや例外処理に不安を抱える方はぜひご覧ください。
▶︎ORMにはうんざり！第5回：例外の闇を断つ、堅牢なJavaエラーハンドリングとログ設計

Beエンジニア

ORMにはうんざり！第5回：例外の闇を断つ、堅牢なJavaエラーハンドリングとログ設計

https://www.pmi-sfbac.org/java-dbaccess-05-error-logging

業務システムの開発において、例外処理とログ出力は「後回しにされがち」な存在です。しかし、実際の運用現場ではエラーが起きたときにその原因を特定できるかどうかが、システムの信頼性と復旧速度を大きく左右します。特にJavaで開発された中〜大規模な業務システムでは、ログの粒度や例外の扱い方ひとつで、障害対応の工数やトラブルの再発率が激変します。今回の第5回では、共通データアクセスクラス群のなかでも「例外処理」と「ログ出力」にフォーカスし、どのように堅牢なエラー制御と可視化を設計すべきかを具体的に解説してい...