メッセージ管理方針⚓︎

Java アプリケーションのメッセージ管理方針については、以下を参照してください。

• Java アプリケーションの処理方式 - メッセージ管理方針

フロントエンドアプリケーションにおけるメッセージとは、画面や帳票等に表示する固定文言、またはユーザーの画面操作の結果に応じて表示する動的文言を指します。

メッセージパターン⚓︎

フロントエンドアプリケーションにおけるメッセージパターンとメッセージの表示内容を以下に示します。

メッセージの管理単位⚓︎

各メッセージの用途を明確にするため、前述したメッセージパターンごとにメッセージを管理します。 AlesInfiny Maia OSS Edition における、メッセージパターンごとのメッセージ管理方針は以下の通りです。

• 処理メッセージ

  処理メッセージ管理用のファイルを定義して一括で管理します。

  処理メッセージは変更や追加の要求が多く、一か所で管理することによりメンテナンスが容易になります。

• 入力値検証メッセージ

  入力値検証メッセージ管理用のファイルを定義して一括で管理します。

  入力値検証メッセージは複数の場所で使用する可能性が高く、ファイルに定義しておくことで再利用が簡単になります。 これにより、コードの重複を避けることにつながります。

• ラベル

  画面内に出力するラベルは各画面やソースコード内に個別に実装したものを使用します。

  ラベルに対してもアプリケーション全体で用語を統一する場合や後述する多言語を実施する場合には、ファイルによるメッセージの一元管理が必要です。 しかし、用語の統一は初期の実装やメッセージ管理ファイルの維持にかかるコストが高いです。 また、ラベルへの多言語対応は言語設定によって画面のレイアウトが崩れてしまう恐れがあります。 そのため、ラベルに対してファイルによるメッセージ管理を導入することは、慎重な検討が必要です。

メッセージのファイル管理⚓︎

フロントエンドアプリケーションでは、処理メッセージや入力値検証メッセージは JSON ファイルを利用して管理します。 JSON ファイルでは、以下のようにメッセージ文字列を識別するメッセージコードとメッセージ文字列本体を key-value で管理します。

1
2
3
4

{
  "errorOccurred": "エラーが発生しました。",
  ...
}

メッセージコードの定義⚓︎

前述した JSON ファイルのように、メッセージコードはそのメッセージの内容を簡潔に表す文字列とします。 このようにすることで、以下のような利点があります。

• 可読性の向上

  数字のメッセージコードよりも、意味を持つメッセージコードを定義することで直感的で理解しやすい利点があります。 開発者がメッセージコードを見たときに、すぐにそのメッセージの内容や目的を把握できます。

• エラー追跡の効率化

  ログやデバッグ時に、意味を持つコードは問題を迅速に特定することに役立ちます。

• ドキュメント化の簡便さ

  メッセージコードがそのメッセージ内容を簡潔に表していれば、メッセージコードの意味を説明するための追加のドキュメントが不要になることがあります。

エラーメッセージコードの統一⚓︎

エラー発生時のメッセージ整形の流れを以下に示します。

この画像の通り、エラー発生時はバックエンドアプリケーションのエラーログの出力とフロントエンドアプリケーションへのエラーの画面出力が順次実施されます。

そのため、同一の業務エラーやシステムエラーのメッセージコードは、バックエンド側とフロントエンド側で統一します。 これにより、以下のような利点があります。

• 一貫性の確保

  統一されたメッセージコードを使用することで、エラーの識別が容易になり、システム全体の一貫性が保たれます。

• デバッグの効率化

  開発者がエラーを特定しやすくなり、問題解決のスピードが向上します。 バックエンドとフロントエンドで同じコードを使用することで、エラーの原因を迅速に特定できます。

OpenAPI 仕様書などの各 JSON ファイルと命名規則を統一するため、メッセージコードをキャメルケースとします。 それに伴い、フロントエンド側に合わせてバックエンドのプロパティファイルのメッセージコードもキャメルケースで記載します。 バックエンドのプロパティファイルの設定例は、こちら を確認してください。

エラーメッセージ内のパラメータ⚓︎

以下のように、エラーメッセージの中にはパラメータを含むものがあります。

1
2
3

{
  "assetNotFound": "アセットコード: [0] のアセットが見つかりませんでした。",
}

パラメータに代入するべき値は、エラーレスポンスに含まれる ProblemDetails の拡張メンバーである exceptionValues から取得します。 ProblemDetails については、こちら を確認してください。

多言語対応⚓︎

メッセージを多言語対応する場合には、それぞれの言語の JSON ファイルを作成し、各言語のメッセージをフォルダーで分割して管理します。 以下に示すように、フォルダー名は ISO-639 言語コード に基づき、その言語を表す言語コードとします。

また、各ファイルの末尾には言語コードを付与します。

locales/ -------------------------------------- メッセージ管理を行うコードが配置されるフォルダー
 ├ en/ ---------------------------------------- 英語メッセージの管理を行うフォルダー
 │ ├ messageList_en.json ---------------------- 処理の成功や失敗などの結果メッセージを格納する JSON ファイル（英語）
 │ └ validationTextList_en.json --------------- 入力値検証用のメッセージを格納する JSON ファイル（英語）
 └ ja/ ---------------------------------------- 日本語メッセージの管理を行うフォルダー
   ├ messageList_ja.json ---------------------- 処理の成功や失敗などの結果メッセージを格納する JSON ファイル（日本語）
   └ validationTextList_ja.json --------------- 入力値検証用のメッセージを格納する JSON ファイル（日本語）

メッセージ管理方針に従った機能の実装方法などの詳細については、こちら を確認してください。