encore-architecture

Encore アプリケーションアーキテクチャ

ディレクトリや宣言を選ぶ前に、論理的なアプリケーションを設計してください。Encore.ts と Encore.go に同じアーキテクチャ上の考え方を適用します。言語固有の実装には encore-service または encore-go-service を使用してください。

アプリケーションを読む

利用可能な場合は、既存のコードと Encore アプリケーションモデルを調査してください。次のものを特定します。

• ユーザー操作とシステム操作
• API、cron ジョブ、Pub/Sub ハンドラー
• データモデルと、それを変更するコード
• インフラストラクチャリソースと、それを使用するサービス
• 既存の同期呼び出しとイベントフロー
• 障害、スケーリング、デプロイ、セキュリティの要件

要求された変更がそれらを再定義する必要がない限り、確立されたアプリケーションの概念を維持してください。

サービスをプロセスから分離する

Encore サービスは、固定されたデプロイ単位ではなく、コードと API の境界として扱ってください。Encore プラットフォームは、コードを変更せずに環境ごとに設定して、すべてのサービスを 1 つのプロセスで実行したり、各サービスを個別のプロセスに配置したりできます。

サービス境界は、アプリケーションの責務を表現するために使用してください。プロセスの割り当ては、それらの責務を再設計せずに分離とスケーリングを変更するために使用してください。

実用的な場合はバックエンドを 1 つの Encore アプリケーションに保ち、アプリケーションモデルがそのサービス、リソース、IAM、トレーシング、Flow 図にまたがるようにしてください。

サービス境界を選ぶ

安定した境界がすでに判明していない限り、新しいアプリケーションは 1 つのサービスで開始してください。その内部のコードは、モジュール、ディレクトリ、または Go のサブパッケージで整理してください。

独自の操作とデータを持つまとまりのあるビジネス能力には、個別のサービスを検討してください。障害の分離、独立したスケーリングやデプロイ、より小さなセキュリティインターフェース、既存の外部システムの継ぎ目などが、その根拠を強めることがあります。

分割のコストを考慮してください。ネットワーク障害、サービス間の調整、分散整合性、および両側が維持しなければならないインターフェースです。ほとんどの変更が両側に影響する場合、またはどちらの側も単独では有用な作業を完了できない場合は、振る舞いを一緒に保ってください。

ハンドラー、ビジネスロジック、データベースアクセスなどの技術的な層を表すサービスは避けてください。別のサービスのテーブルへの汎用的なアクセスではなく、ReserveInventory のような能力の操作を公開してください。

1 つの境界をまたぐ繰り返しの順次呼び出しや、転送サービスの中継が長く続くことは、提案されたサービスが狭すぎる可能性がある証拠として扱ってください。

データの責務を割り当てる

各データモデル、そのビジネスルール、およびそのスキーマ変更に対して、1 つのサービスの責務を割り当ててください。別のサービスがそれらのルールを適用するために所有サービスを必要とする場合は、呼び出しまたはイベントを優先してください。

Encore は、TypeScript では SQLDatabase.named、Go では sqldb.Named を通じて共有データベースアクセスをサポートしています。レポート、段階的なマイグレーション、または別のサービスインターフェースが取り除く以上の複雑さを追加する場合には、意図的に使用してください。データベースを共有する前に、マイグレーションの所有権と書き込みアクセスを定義してください。

サービスごとに 1 つのデータベースを Encore の要件として課さないでください。共有スキーマアクセスによって生じる結合と、別のサービスインターフェースによって生じる結合を比較評価してください。

通信を選ぶ

呼び出し元が続行する前に結果を必要とする場合、操作が成功または失敗を報告しなければならない場合、または 1 つのサービスが要求された能力を所有している場合は、型付きサービス API を使用してください。

呼び出し元が待つ必要がない場合、複数のコンシューマーが独立して反応する場合、またはコンシューマーの再試行が元のリクエストを繰り返すべきでない場合は、Pub/Sub を使用してください。結果整合性を考慮し、重複配信が正確性に影響する場合はハンドラーを冪等にしてください。

即時のリクエスト/レスポンスのワークフローは同期的に保ってください。順序付きイベントを通じて同期呼び出しの連鎖を再現するのではなく、イベントコンシューマーは独立させて保ってください。

データベースの変更とイベントの発行を一貫させなければならない場合は、それらの間の障害を想定して設計してください。Encore.go はトランザクション対応の Pub/Sub アウトボックスを提供します。それ以外の場合は、アプリケーション固有の整合性メカニズムが必要です。

インターフェースと認可を定義する

操作をパブリック、認証済み、またはプライベートとして分類します。外部クライアントがそれを必要としない限り、内部のケイパビリティの操作はプライベートに保ちます。

認証とクロスオリジンポリシーはゲートウェイに配置します。特定のケイパビリティまたはレコードに関する認可の判断は、それを所有するサービスに委ねます。

整理と進化

Encore サービスはネストできません。関連するサービスの大きな集合はシステムディレクトリにグループ化します。システムはソースコードを整理するものであり、Encore のリソースやデプロイ単位ではありません。

サービスを分割する際は、一緒に移動する操作とデータを特定し、新しいサービスを追加し、直接呼び出しを API またはイベントに置き換え、移行中のデータ所有権を定義します。結果として得られるモデルを Encore Flow で確認し、サービス境界を越えるようになった呼び出しをテストします。

アーキテクチャを推奨する際は、提案するサービス、それらの責務、所有するリソース、および通信経路を明示します。各サービスの分割について具体的な理由を説明し、重要な整合性や障害に関するトレードオフに言及します。提示された要件を満たす最小のアーキテクチャを優先します。

完全なガイドと言語別の例については、App Structure を参照してください。