Skip to content

Commit

Permalink
ログ出力設定に関する修正とドキュメントの追加 (#1697)
Browse files Browse the repository at this point in the history 
* メッセージプロパティを各サブプロジェクトで管理するよう変更する

* 使用していないimportの削除

* メッセージコードをフロントエンドに合わせて頭文字を小文字にする

* フロントエンド側のメッセージ管理機能実装

* バックエンド側のエラーメッセージ出力を実装

* フロントエンド側のメッセージ管理機能の実装

* 起動方法の修正

* テスト時の警告解除

* type-checkの警告対応

* typecheckの警告回避と日英対応のメッセージ作成

* エラーハンドリング機能の修正

* if文の修正

* ドキュメントの追加

* ドキュメントの追加

* エラーメッセージに関する記載の修正

* 入力値検証のドキュメント修正

* ブラウザーの言語設定の取得方法修正

* ドキュメント指摘事項の修正

* クリップボード機能の修正

* textlintエラーへの対応

* 入力値検証に関するドキュメントの修正

* ドキュメント指摘事項の修正

* ドキュメントのimport文の削除

* 起動方法の修正

* ドキュメントのアプリ起動方法を記載

* 冗長な文章を修正

* ハイライトを修正

* 指摘事項と軽微なドキュメントの修正

* 変数名の修正

* log4jの設定をエントリーポイントプロジェクトに移動

* log4j.xmlに関するドキュメントを追記する

* ログドキュメントの修正

* batchアプリケーションの設定

* メッセージ管理の部分を削除

* ロギングライブラリの除外設定に関するドキュメントを修正

* 除外設定のドキュメントにおけるライブラリの記載を修正

* gradle の最終作成結果にlog4j用のライブラリを追加する。

* バージョン定義一元化のドキュメントにlog4j 2のライブラリの記載を追加

* ルートプロジェクトの除外設定を削除

* auth-backendのlog4j 2の設定をエントリーポイントとなるサブプロジェクトに移動
  • Loading branch information
@rnakagawa16
rnakagawa16 authored Dec 26, 2024
1 parent 478469a commit 0698633
Show file tree
Hide file tree
Showing 99 changed files with 2,156 additions and 546 deletions.
2 changes: 1 addition & 1 deletion .github/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Issue や Discussions に対して追加の説明や質問がある場合は、

これらでは解決できない場合、 Discussions の [Q&A](https://github.com/AlesInfiny/maia/discussions/categories/05-q-a) より質問をお寄せください。
質問を投稿する場合、直面していることについてできる限り多くの情報を提供してください。
可能な限りスピーディーに対応いたします。
可能な限り迅速に対応いたします。
ただし、質問に対する回答が常に得られることを期待しないでください。

## 本プロジェクトに対するコントリビュート
Expand Down
2 changes: 1 addition & 1 deletion .textlintrc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -358,6 +358,7 @@
"状態",
"ジョッキー",
"ジレンマ",
"迅速",
"スキャナー",
"スキーマ",
"スクエア",
Expand All @@ -377,7 +378,6 @@
"ストーブ",
"ストーリー",
"スパイウェア",
"スピーディー",
"スピード",
"スペイン",
"スポーツ",
Expand Down
3 changes: 3 additions & 0 deletions cspell.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@
"words": [
"Adoptium",
"AlesInfiny",
"Appender",
"Appenders",
"BIPROGY",
"Checkstyle",
"Corretto",
Expand All @@ -44,6 +46,7 @@
"JaCoCo",
"JDBC",
"linenums",
"Logback",
"markdownlint",
"mkdocs",
"Mockito",
Expand Down
229 changes: 229 additions & 0 deletions ...aterials/images/app-architecture/client-side-rendering/error-message-delivery-dark.drawio
View file

Large diffs are not rendered by default.

229 changes: 229 additions & 0 deletions ...terials/images/app-architecture/client-side-rendering/error-message-delivery-light.drawio
View file

Large diffs are not rendered by default.

4 changes: 4 additions & 0 deletions ...s/contents/app-architecture/client-side-rendering/frontend-application/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,13 +155,17 @@ Vue.js プロジェクトのフォルダー構成は、ブランクプロジェ
├─ cypress/ ------------------ cypress による E2E テストに関するファイルを格納します。
├─ public/ ------------------- メディアファイルや favicon など静的な資産を格納します。
├─ src/
│ ├─ api-client/ ------------ API クライアントの設定ファイルを格納します。
│ ├─ assets/ ---------------- コードや動的ファイルが必要とするCSSや画像などのアセットを格納します。
│ ├─ components/ ------------ 単体で自己完結している再利用性の高い vue コンポーネントなどを格納します。
│ ├─ config/ ---------------- 設定ファイルを格納します。
│ ├─ generated/ ------------- 自動生成されたファイルを格納します。
│ ├─ locales/ --------------- メッセージ管理に関するファイルを格納します。
│ ├─ router/ ---------------- ルーティング定義を格納します。
│ ├─ services/ -------------- サービスに関するファイルを格納します。
│ ├─ shared/ ---------------- アプリケーション全体で再利用する共通機能のファイルを格納します。
│ ├─ stores/ ---------------- store に関するファイルを格納します。
│ ├─ validation/ ------------ 一元化するバリデーション定義ファイルを格納します。
│ ├─ views/ ----------------- ルーティングで指定される vue ファイルを格納します。またページ固有の挙動などもここに含めます。
│ ├─ App.vue
│ └─ main.ts
Expand Down
60 changes: 60 additions & 0 deletions ...ts/app-architecture/client-side-rendering/global-function/exception-handling.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ title: CSR 編
description: クライアントサイドレンダリングを行う Web アプリケーションの アーキテクチャについて解説します。
---

<!-- cspell:ignore applicationcore rgba -->

# 例外処理方針 {#top}

バックエンドアプリケーションで発生するシステム例外や業務例外は、例外フィルターによって捕捉します。
Expand Down Expand Up @@ -103,3 +105,61 @@ HTTP 通信で発生する例外について、レスポンスやステータス
C->>B: エラー通知
deactivate C
```

### API 通信のエラーレスポンス {#error-response}

API 通信で発生した例外において、バックエンドから返却されるエラーレスポンスには、 [ProblemDetails :material-open-in-new:](https://www.rfc-editor.org/rfc/rfc9457.html){ target=_blank } に基づくレスポンスボディーを含みます。

ProblemDetails は、 HTTP API のエラーレスポンスを標準化するための構造体であり、以下のプロパティで定義されています。

| 項目 | プロパティ名 | 推奨レベル | 内容 |
| ---------------------------- | ------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 簡易メッセージ | title | 必須 | 人間が読める形式で提供されます。 |
| 詳細メッセージ | detail | 本番環境は非推奨 | スタックトレースなどを含めます。開発環境では生産性向上を目的に含めることを推奨しますが、本番環境では使用しません。開発環境と本番環境で構成を変更することが難しい場合には detail を使用しないよう統一することも検討してください。 |
| ステータスコード | status | 任意 | HTTP エラーのステータスコードです。 |
| 詳細 URL | type | 推奨 | エラーを説明する詳細 Web ドキュメントがある場合、ユーザーが参照する URL を追加します。 |
| 問題が発生したリソースの URI | instance | 任意 | 問題の発生場所を示す URI です。リクエスト先と異なるリソースが問題の発生したリソースである場合、実装の詳細やデータなどの内部情報が漏洩する可能性があるため、追加には注意が必要です。 |
| 任意のパラメータ | | 任意 | 拡張メンバーです。必要に応じて ProblemDetails のプロパティを拡張する場合に利用します。 |

AlesInfiny Maia OSS Edition では、上記のプロパティに加えて拡張メンバーとして以下を定義しています。

- exceptionId

例外 ID 。メッセージファイルからエラーメッセージを取得するためのメッセージコードとして利用します。

- exceptionValues

例外値。例外 ID から取得したエラーメッセージ内のパラメーターに代入する値として利用します。

クライアントサイドでポップアップやトースト通知などを用いてエラー通知を実装する場合には、 ProblemDetails の各プロパティの内容を表示します。

#### エラーレスポンスの例 {#example-of-error-response}

説明したエラーレスポンスの例を以下に示します。

```json title="開発環境の場合のエラーレスポンス"
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
"type": "https://hoge.com/error/catalogItemIdDoesNotExistInBasket",
"title": "業務エラーが発生しました。",
"status": 400,
"detail": "dressca.applicationcore.baskets.CatalogItemInBasketNotFoundException: 業務エラーが発生しました。 ###以下スタックトレースは省略###",
"exceptionId": "catalogItemIdDoesNotExistInBasket",
"exceptionValues": ["1 ###買い物かごID###", "10 ###商品ID###"]
}
```

```json title="本番環境の場合のエラーレスポンス"
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
"type": "https://hoge.com/error/catalogItemIdDoesNotExistInBasket",
"title": "業務エラーが発生しました。",
"status": 400,
"exceptionId": "catalogItemIdDoesNotExistInBasket",
"exceptionValues": ["1 ###買い物かごID###", "10 ###商品ID###"]
}
```
135 changes: 133 additions & 2 deletions ...architecture/client-side-rendering/global-function/message-management-policy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,5 +9,136 @@ Java アプリケーションのメッセージ管理方針については、以

- [Java アプリケーションの処理方式 - メッセージ管理方針](../../../app-architecture/overview/java-application-processing-system/message-management-policy.md#message-management-policy)

フロントエンドアプリケーションでは、特別なメッセージ管理しません。
画面内に出力するメッセージやラベルは、各画面やソースコード内に個別に実装したものを使用します。
フロントエンドアプリケーションにおけるメッセージとは、画面や帳票等に表示する固定文言、またはユーザーの画面操作の結果に応じて表示する動的文言を指します。

## メッセージパターン {#message-pattern}

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

| パターン | 表示内容 | 表示例 |
| -------------------- | -------------------- | ------------------------------------------------------------ |
| 処理メッセージ | 処理の確認 | 注文内容を確認して「注文を確定する」ボタンを押してください。 |
| | 正常終了 | 注文が完了しました。 |
| | 業務エラー | カートに追加できませんでした。 |
| | | 商品の削除に失敗しました。 |
| | システムエラー | サーバーエラーが発生しました。 |
| | | ネットワークエラーが発生しました。 |
| 入力値検証メッセージ | 単項目チェックエラー | 値を入力してください |
| | 相関チェックエラー | パスワードと確認用パスワードが一致しません |
| ラベル | 画面のタイトル | Dressca |
| | 画面の項目名 | 合計 / 送料 |
| | UI ラベル | 注文を確定する |

## メッセージの管理単位 {#management-unit}

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

- 処理メッセージ

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

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

- 入力値検証メッセージ

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

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

- ラベル

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

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

## メッセージのファイル管理 {#message-file-management}

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

``` json title="メッセージの JSON ファイルの定義例"
{
"errorOccurred": "エラーが発生しました。",
...
}
```

### メッセージコードの定義 {#message-codes-definition}

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

- 可読性の向上

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

- エラー追跡の効率化

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

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

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

### エラーメッセージコードの統一 {#unification-of-message-codes}

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

![エラーメッセージ整形の流れ](../../../images/app-architecture/client-side-rendering/error-message-delivery-light.png#only-light){ loading=lazy }
![エラーメッセージ整形の流れ](../../../images/app-architecture/client-side-rendering/error-message-delivery-dark.png#only-dark){ loading=lazy }

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

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

- 一貫性の確保

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

- デバッグの効率化

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

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

### エラーメッセージ内のパラメータ {#parameter-of-error-messages}

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

```json title="パラメータを含むエラーメッセージの例"
{
"assetNotFound": "アセットコード: [0] のアセットが見つかりませんでした。",
}
```

パラメータに代入するべき値は、エラーレスポンスに含まれる ProblemDetails の拡張メンバーである `exceptionValues` から取得します。
ProblemDetails については、[こちら](./exception-handling.md#error-response) を確認してください。

### 多言語対応 {#localization}

メッセージを多言語対応する場合には、それぞれの言語の JSON ファイルを作成し、各言語のメッセージをフォルダーで分割して管理します。
以下に示すように、フォルダー名は [ISO-639 言語コード :material-open-in-new:](https://www.iso.org/iso-639-language-code){ target=_blank } に基づき、その言語を表す言語コードとします。

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

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

メッセージ管理方針に従った機能の実装方法などの詳細については、[こちら](../../../guidebooks/how-to-develop/vue-js/message-management.md) を確認してください。
Loading

0 comments on commit 0698633

Please sign in to comment.