アプリケーションアーキテクチャ概要編にメッセージ管理方針を追記する

[tsuna-can-se]

#7 から独立。

プロパティファイル使って管理するよ、みたいな方針の話を書く。
プロパティファイルの単位、国際化対応、などの方針を定める。

[rnakagawa16]

メッセージ管理方針では以下のことを記載する

バックエンド側

何を管理するか

クライアントサイドレンダリング

• バリデーションメッセージ（フォーム入力のバリデーションメッセージ）
  • しかし、今の実装では特にバリデートは行っていないように見える
• システムメッセージ（ログやシステム通知に使用されるメッセージ）
  • backendのログに出力するメッセージ

サーバーサイドレンダリング

上記にプラスして、ボタンなどのラベルを保存するメッセージプロパティを作る

どこで管理するか

• 共通部分に記載するのか、各層で個別に設定するのか
  • 今は、メッセージ文字列はsystem-common層のsrc/main/resource内のプロパティファイルで管理している
  • 各層のsrc/main/resourceにサブプロジェクト名と同様のフォルダーを配置し、その中にメッセージプロパティファイルを配置する
  • この方針をとるのはweb層でsystem-commonやapplication-coreの複数のプロパティファイルを参照するが、同じ名前だと判断できないため

また、以下のことも記載する

• MessageSourceとmessages.propertiesの関係を示す（開発編のほう）
  • MessageSourceで呼び出せることなども含めて書くか？

どの様に管理していくか

• ログメッセージ名は意味の分かりやすいものを使う
  • IDのような形で書くのはどのエラーメッセージなのかわからないように見える
• ログのエラーメッセージのレベル（infoかwarnかなど）についてはここでは記載しない
  • web層やapplication-core層でログを出力する際のメソッドで分けるのでプロパティファイル上でメッセージのレベルを管理するわけではない

どのような単位でプロパティファイルを分けるか

• そもそもの変更方法（開発編のほう）
  • application-common.propertiesに設定されているspring.messages.basenameで使用するプロパティファイルを設定
  • spring.messages.basename=messages（複数ある場合はカンマ区切り）
• 他言語対応
  • 日英などのプロパティをそれぞれ分ける
    • messages.properties（デフォルト）
    • messages_en.properties（英語）
    • spring.messages.basename=messages_jaのようにして使用するものを変える
  • ブラウザの言語設定によって出力する内容を変える方法もあるよう。
    • Cookie上にリクエストヘッダーからの言語情報を取得するようなBean登録を行う
    • アーキテクチャのほうでは、Cookieに保存してLocaleを自動設定するような仕組みを導入するよう記載してみる
    • バックエンド側からフロントエンド側に送るエラーメッセージの値は言語に関係ないIDのような値のため特にCookieから言語設定をとってくる必要はないので実装しなくてもよいと考える

[rnakagawa16]

AlesInfiny Maia OSS Editionとしてどこまで実装するか

バックエンド側

メッセージプロパティの管理場所を決定し反映する

• 共通部分に保存しておくことのメリットデメリットを把握する
  • 大きなプロジェクトになるほど共通部分で管理し続けることの負荷が大きくなる
• 分割しておくことのメリットデメリットを把握する
  • 現時点のDresscaはログの出力はWebで一括で行っているため、Webで管理しておくのもあり？
  • application-core単体でテストなどを行うときにログが定義されていないみたいなことになるかも

プロパティファイルの分割方法を決定し反映する

• 少なくともシステムメッセージとフロントエンドのエラーメッセージのファイルは分割したい
  • 文章では分割すべきって書いてあるのに、サンプルはそうなってないというのは結構問題

多言語対応の方針を決定し反映する

• 実装が結構時間がかかる
• Cookieの保存の話などをドキュメントでするとなると実装しておいた方がいいかもしれない
  • この実装が必要なのは、フロントエンド側にメッセージを送る際にメッセージをそのまま送る場合
  • 今回の実装は、アセットコードなどのメッセージ部品を送るだけなので、多言語メッセージ対応はフロントエンド側に任せている
  • 開発者側のメッセージをフロントエンド側の言語設定に合わせるような実装は必要ない
• バックエンド側だけでも実装しておくといい
  • メッセージプロパティを複数用意し、使用するプロパティファイルを手動で切り替えるだけでいいので特に問題ないかも

[rnakagawa16]

AlesInfiny Maia OSS Edition としてどこまで実装するか

フロントエンド側

利用ライブラリ

Vue-i18nを利用する。
https://vue-i18n.intlify.dev/guide/advanced/composition

npm install vue-i18n

プロパティファイルの配置

src/localesに以下のjsonファイルを配置する。

• labelTextList : viewページ内で表示するテキストを保持する
• messageList.json : フロントエンドのToastやログのメッセージを保持する
• validationTextList.json: yupの入力値検証で利用するメッセージを保持する

また、他言語対応のためにファイル末尾に_jp、_enをつけたjsonファイルをそれぞれ配置する。

• codesList_en.json
• codesList_jp.json

[rnakagawa16]

バックエンド側のプロパティメッセージの管理方法について

E_SHARE系

system-common で管理する

E_ASSET系などの業務系メッセージ

.log

application-core で管理する

.front

フロントエンド側で管理する
これに伴い、レスポンスの内容を変更する必要あり。（ProblemDetailなど）

ProblemDetailの修正

ProblemDetail 内に対して、以下のような値を付与する

{
"title" : "タイトル",
"detail": "詳細",
...
"exceptionId" : "例外ID",
"exceptionValue" : "フロントエンド側に返すエラーメッセージの値"
}

ProblemDetail の値に基づいて、exceptionIdに一致するエラーメッセージを取得、
exceptionValueをもとに整形し、画面に出力する

バックエンド側の変更点

1. 404エラーとして判断していた業務エラーの中にProblemDetailsを含めるように修正する
2. 共通例外ハンドリングとしてExceptionHandlerのLogicExceptionを例外ハンドラとしていたものに関しては、ProblemDetalsの中に業務エラーを示すような形で統一的なProblemDetailsの値を入れる

[rnakagawa16]

メッセージコード新旧対応一覧

メッセージについて、Marisのメッセージコードをもとに以下のように変更する。
メッセージ内容に関しては従来のまま変更しない。

旧	新
E_SHARE0000	SystemError
E_ASSET0001	AssetNotFound
E_BASKET0001	BasketIsNullOnCheckout
E_BASKET0002	CatalogItemIdDoesNotExistInBasket
E_ORDER0001	BasketIsEmptyOnCheckout
E_ORDER0002	OrderNotFound
E_CATALOG0001	CatalogIdNotFound
D_ASSET0001	AssetApplicationServiceGetAsset
D_BASKET0001	ShoppingApplicationServiceAddItemToBasket
D_BASKET0002	ShoppingApplicationServiceSetBasketItemsQuantities
D_BASKET0003	ShoppingApplicationServiceGetBasketItems
D_BASKET0004	ShoppingApplicationServiceCheckout
D_ORDER0001	OrderApplicationServiceGetOrder
D_CATALOG0001	CatalogApplicationServiceGetCatalogItems
D_CATALOG0002	CatalogApplicationServiceCountCatalogItems
D_CATALOG0003	CatalogApplicationServiceGetBrands
D_CATALOG0004	CatalogApplicationServiceGetCategory

フロントエンドのエラーメッセージのkey名とバックエンドのメッセージコードを同一のものを使用して合わせる仕様とする。
この際、フロントエンドのエラーメッセージはjsonファイルで管理する。
jsonのkeyはキャメルケースで記載することが通例のようだが、メッセージコードはパスカルケースで記載されている。
どちらに合わせるか要相談。

メッセージコードの名称が長いことによる対応

checkstyleにおいて120文字を超える警告が発生する。
これに対し、MessageIdConstantのクラスには、文字数超過の警告対象から除外する。

<suppress checks="LineLength" files=".*MessageIdConstant.java$"/>

[rnakagawa16]

各サブプロジェクトのmessages.propertisに対して、web層で複数のmessages.propertiesを参照するために
messages-application-core.propertiesやmessages-system-common.propertiesのような形で設定している。

参考文献
https://www.brightec.co.uk/blog/internationalize-your-multi-module-spring-boot-application

ただ、この命名を使用すると接尾辞に多くの情報が含まれることになりみにくい。
フォルダーを配置する方針のほうが見やすく、かつメッセージプロパティファイルをフォルダー内で一括管理できるためわかりやすい。
また、messages-application-core.propertiesの名前だと、messages.propertiesなのかapplication.propertiesなのかが一目でわかりづらい。

[rnakagawa16]

フロントエンド側メッセージ管理リスト

ファイル名	key
labelTextList	labalTextList
messageList	errorMessageList
	toastMessageList
validationTextList	validationTextList

[rnakagawa16]

yup の setLocale の使い方

yup.config.ts は yup の validation で表示する文字列を管理するファイルである。
現在、このファイルは、main.ts で利用されているが、表示する文字列を多言語対応させるために vue-i18n の useI18nメソッドを利用しようとすると、main.ts でまたアプリケーションに反映されていない状態でjsonファイルを参照するようになり、エラーが発生する。

そのため、LoginView上でyup.config.tsを参照するように変更する必要がある。
その変更を実施すると、validation-items.tsで一元管理していたemailの検証が正しく動作しなくなるため、こちらを削除数方針をとることが問題ないかを確認する必要あり。

[rnakagawa16]

メッセージ管理方針のドキュメントで記載すること

バックエンド側

CSR編アーキテクチャ

プロパティファイルの分割

・共通処理と業務処理のプロパティファイルは分けること
・CSRアプリケーションでは、バックエンド側に保存するメッセージは、エラーメッセージや通知メッセージのようなログのためのメッセージだけであり、入力値検証で返すメッセージや画面上に表示するボタンのラベルやメッセージなどは管理しないこと
・多言語対応する際には言語ごとにプロパティファイルを分けること

メッセージコードについて

・メッセージコードを格納する定数には、エラーメッセージか業務メッセージかを見分けるために頭文字にEやDをつけること
・メッセージコードがわかりやすいようにコード名はそのメッセージを表す分をキャメルケースで記載すること
・ProblemDetailsに詰め込むため、フロントエンド側のメッセージコードと統一すること

開発手順

プロパティファイルの分割方法

・どのサブプロジェクトに格納されたプロパティファイルかが判別できるよう、src/main/resourceの配下にサブプロジェクト名のフォルダーを作成し、その中でメッセージプロパティを管理すること
・application.properties上でどのメッセージプロパティを参照するかを明記すること
　・複数のメッセージプロパティを参照する場合には、カンマ区切りで記載すること

# web層のサブプロジェクトの場合
spring.messages.basename=applicationcore.messages,systemcommon.messages

フロントエンド側

CSR編アーキテクチャ

・vueファイル上に直接記載するテキストラベル、エラーやToastのメッセージ、yupやvee-validateで利用する入力値検証のメッセージをそれぞれのjsonファイルで管理する
・メッセージファイルを多言語対応する場合には、それぞれのメッセージを言語ごとに作成すること

メッセージコードについて