ムジェはユーザーのさまざまなペルソナを尊重し、記録の価値を保存するプラットフォームを指向しています。サービスが成長するにつれて、既存に作成された断片化されたロジックは保守の複雑度を高め、時にはユーザーの意図とは異なる結果を招くこともあります。最近行われたアップデートを通じて直面した技術的問題とこれを解決するために試みた構造的改善事項を共有したいと思います。

1. フォームバインディングの曖昧性解決とUI/UX一貫性の確保

既存の投稿エディタは、メインページのクイック作成(Quick Compose)ツールとは異なるユーザー体験を提供していました。特に匿名作成可否を決定するチェックボックスは単純な形態に留まっており、サービス全般の視覚的言語と一致しない問題がありました。これを改善するため、エディタの匿名設定をスイッチ形式のトグルUIに変更し、「無名」と「公開」という明確なテキストフィードバックを追加しました。

UI変更過程で技術的に最も重点を置いた部分はデータバインディングの整合性です。Thymeleafのth:field属性を使用する場合、Springはチェックボックスが解除された際に値が欠落することを防ぐため、_isAnonymousというヒドゥンフィールドを自動的に生成します。この時、開発者が手動で定義したname属性とJavaScriptによる動的値変更が重なり、サーバーに重複したパラメータが送信されてブール(Boolean)値が常にtrueとして解釈される欠陥が発見されました。

これを解決するため、上部のスイッチは状態表示のためのUIコンポーネントとしてのみ活用し、実際のデータ送信はJavaScriptによって制御される別のヒドゥンフィールドで一元化しました。結果的に、フロントエンドの状態変化がバックエンドDTO(Data Transfer Object)に正確にマッピングされる安定した構造を確保できました。

2. ドメイン識別子の一貫性: メールからハンドルへ

投稿の修正及び削除権限を検証する過程で、既存はユーザーのメールアドレスを主要識別子として活用してきました。しかし、ドメインモデルでユーザーを固有に表すペルソナは「ハンドル(@handle)」です。システム内部識別子であるメールと対外的識別子であるハンドルが検証ロジックで混用されることは、ドメイン観点から意味論的不一致を招き、今後のURLルーティングやドメイン拡張時にエラーを誘発する可能性が高かったのです。

今回の改善作業では、サービス内のすべての所有権検証ロジックをハンドルベースに変更しました。コントローラ層でUserPrincipalからハンドル情報を抽出してサービスに伝達するように構造を変更することで、ドメインモデルの一貫性を高め、データアクセス権限検証手順をより直感的に再定義しました。

3. API共通例外処理による堅固なエラーレスポンス設計

クライアントとサーバー間の通信で例外状況に対する明確なレスポンスは、サービスの信頼度と直結します。@ControllerAdviceを活用してRestController専用グローバル例外処理器であるApiGlobalExceptionHandlerを実装しました。

特に@Validアノテーションを通じて発生するMethodArgumentNotValidExceptionを捕捉し、バリデーション検査に失敗したフィールドとエラーメッセージをLinkedHashMapに入れて構造化されたJSON形式で返すよう設定しました。また、IllegalArgumentExceptionのようなランタイム例外に対しても一貫したレスポンス規格を適用することで、クライアントがエラー原因を即座に把握して対応できる開発環境を構築しました。

おわりに

今回の作業は表に現れる華やかな機能の追加ではなかったものの、サービスの基盤となるデータ処理の正確度を高め、内部ロジックの凝集度を強化することに注力しました。コード一行の変更がユーザーにはより良い安定性として伝わることを期待します。