backend-architecture

バックエンドアーキテクチャ

現在の境界

• src/Exceptionless.Web/Api/Endpoints/：最小限の API ルート登録、バインディング、認可、レスポンスメタデータ。
• Api/Messages/ と Api/Handlers/：メディエーターリクエストとそのアプリケーション動作。対応するエンドポイントファミリーに従ってください。
• Api/Filters/、Api/Infrastructure/、Api/Results/：共有バリデーション、リクエストヘルパー、HTTP 結果のマッピング。
• Exceptionless.Core：ドメインモデル、サービス、リポジトリ、課金、シリアル化。
• Exceptionless.Insulation：ストレージ、キャッシュ、メール、その他のインフラストラクチャに関するプロバイダー実装。
• Exceptionless.Job：バックグラウンド処理。

エンドポイントの例については、src/Exceptionless.Web/Api/Endpoints/OrganizationEndpoints.cs と、そのメッセージおよびハンドラーを確認してください。エンドポイントグループでは、AuthorizationRoles ポリシーと AutoValidationEndpointFilter を使用します。メディエーターの結果は ToHttpResult と設定済みの結果マッパーを通じてマッピングされます。一般的な例から作り直すのではなく、エンドポイントのレスポンスと認可の契約を維持してください。

リポジトリの規約

ドメインの動作は Core に保持してください。Web と Job は Core を利用し、Insulation はインフラストラクチャの実装を提供します。HTTP に関する処理をドメインサービスに移さないでください。

• AppOptions を直接注入してください。シークレットではない設定には appsettings.yml を使用し、環境変数によるオーバーライドには EX_ プレフィックスを使用します。
• キャッシュ、キュー、メッセージバス、ファイルストレージ、分散ロック、レジリエンスには Foundatio の抽象化を使用してください。Elasticsearch 操作には foundatio-repositories を使用してください。
• キュー項目は、永続的な処理が成功した後に完了扱いにしてください。再試行可能な失敗と無効な入力を区別してください。
• サポートされている箇所ではキャンセルを伝播させてください。構造化ログと ExceptionlessState スコープを使用して、組織／プロジェクトのコンテキストを記録してください。
• WebSocket 通知には、メッセージバスを基盤とする MessageBusBroker と WebSocketConnectionManager を使用してください。
• OpenAPI スナップショットと互換性については、ルートのガイダンスに従ってください。JSON の動作を変更する場合は、シリアル化アーキテクチャを参照してください。

実装の詳細

• コンストラクターインジェクションと readonly の依存関係フィールドを優先してください。.editorconfig に従い、非同期メソッドには Async サフィックスを使用し、region の追加は避けてください。
• プロバイダー固有の並行する抽象化を作成するのではなく、ICacheClient、IQueue<T>、IMessageBus、IFileStorage、ILockProvider、IResiliencePolicyProvider を使用してください。
• キューコンシューマーは通常 QueueJobBase<T> を継承し、スケジュール済みジョブは JobWithLockBase などの基底クラスと [Job] スケジュール属性を使用します。ジョブを変更する際は、ロック、完了、放棄、キャンセルの動作を維持してください。無効な入力が無限の再試行サイクルに入らないようにしてください。
• モデルのバリデーションには DataAnnotations と既存の MiniValidation 統合を使用してください。エンドポイントのバインディング／バリデーションエラーと、メディエーターから HTTP 結果へのマッピングを維持してください。想定されるステータスと ProblemDetails の形式については、Api/Filters/AutoValidationEndpointFilter.cs、Api/Results/ApiResultMapper.cs、エンドポイントのテストを確認してください。
• 補間されたログメッセージではなく、構造化メッセージテンプレートを使用し、共有コンテキストには ExceptionlessState を使用してください。パスワード、API キー、完全なトークン、機密性の高いペイロードは決してログに記録しないでください。必要な識別子と安全な要約を優先してください。