vtex-io-data-access-patterns

データアクセスとストレージのパターン

このスキルを使う場合

データをどこに保存すべきか、VTEX IO アプリでどのように読み書きすべきかが主な問題となる場合に、このスキルを使います。

• IO アプリの新しいデータフローを設計する場合
• アプリ設定、構成アプリ、Master Data、VBase、VTEX コア API のどれを使うか判断する場合
• 大規模なデータ、重複したデータ、または重要なデータを読み書きするコードをレビューする場合
• 既存の API の周囲にキャッシュレイヤーや派生ローカルビューを導入する場合

次の用途では、このスキルを使わないでください。

• Master Data の詳細なスキーマやエンティティモデリング
• アプリ設定や構成アプリのスキーマ設計
• AUTH_TOKEN、STORE_TOKEN、マニフェストの権限などの認証トークンやポリシー
• サービスのランタイム規模の設定や並行処理のチューニング

判断ルール

データの種類ごとに適切な保存先を選ぶ

• 機能フラグ、認証情報、外部ベース URL、動作の切り替え設定など、マーチャントや運用担当者が管理する安定した構成には、アプリ設定または構成アプリを使います。
• アカウントに属し、検証、フィルタリング、検索、ページネーション、ライフサイクル管理が必要な、構造化されたカスタム業務レコードには Master Data を使います。
• キーによる読み取りが主で、広範な検索は通常行わない、シンプルなキー付きドキュメント、補助スナップショット、キャッシュのような JSON ペイロードには VBase を使います。
• 注文、カタログ、価格設定、物流などの VTEX コアドメインに属するデータには、VTEX コア API を使います。
• データが別のシステムに属し、VTEX IO がそのシステムとの連携のみを担う場合は、外部ストアまたは外部 API を使います。

信頼できる唯一の情報源を明確にする

• 注文、商品、価格、在庫など、コアコマースドメインでは VTEX コア API を信頼できる唯一の情報源として扱います。
• 所有者が明確な限定的な派生用途がない限り、注文、カタログレコード、価格、在庫をすべて Master Data や VBase に複製しないでください。
• IO アプリでローカルコピーが必要な場合は、そのアプリに必要な最小限のフィールドまたは派生ビューのみを保存し、必要に応じて信頼できる情報源から詳細全体を再取得します。
• アプリ設定や構成アプリを汎用的な運用データストアとして使わないでください。

読み取りとキャッシュを意図的に設計する

• Node にデータセット全体を読み込んでメモリ上でフィルタリングするのではなく、API レベルのフィルタリング、ページネーション、フィールド選択、範囲を限定した読み取りを優先します。
• 繰り返しの読み取りに見合うメリットがあり、キャッシュされたビューの無効化ルールまたは鮮度ルールが明確な場合にのみ、キャッシュを使います。
• バックグラウンドジョブやイベントパイプラインで永続的な処理状態が必要な場合は、再試行と冪等性に必要なステータスおよび相関データのみを保存します。
• 用途として永続的なアプリ所有の監査証跡が明示的に必要でない限り、長期間保持されるログ、トレース、または上限のない履歴を Master Data や VBase に保存しないでください。

厳守すべき制約

制約：構成ストアを運用データの保存に使ってはいけません

アプリ設定と構成アプリには、トランザクションレコード、上限のないリスト、または頻繁に変化する運用状態ではなく、構成を表すデータを保存しなければなりません。

重要な理由

構成ストアをデータ保存に使うと、システムの境界が曖昧になり、ワークスペースの動作を把握しにくくなるほか、設定が小規模で安定していることを前提とするツールやフローの期待が損なわれます。

検出方法

settingsSchema、構成アプリのペイロード、または設定関連 API 内に、レコードの配列、ログ、履歴、注文、その他増え続ける運用データのペイロードが見つかった場合は、そこで作業を中断し、そのデータを Master Data、VBase、コア API、または外部ストアに移してください。

正しい例

{
  "settingsSchema": {
    "type": "object",
    "properties": {
      "enableModeration": {
        "type": "boolean"
      }
    }
  }
}

誤った例

{
  "settingsSchema": {
    "type": "object",
    "properties": {
      "orders": {
        "type": "array"
      }
    }
  }
}

制約：コアシステムは、各ドメインの信頼できる唯一の情報源であり続ける必要があります

Orders、Catalog、Pricing、Logistics などの VTEX コアシステムは、それぞれのビジネスドメインにおける主要な信頼できる唯一の情報源であり続ける必要があります。

これが重要な理由

コアドメインの主要な保存先としてローカルの IO コピーを扱うと、照合のずれ、古いデータの読み取り、古いデータに基づいたビジネス上の意思決定が発生します。

検出方法

アプリが注文のペイロード全体、商品ドキュメント、在庫スナップショット、価格表を Master Data または VBase に保存し、そのコピーをビジネス上の意思決定における主要な情報源として使用している場合は、処理を停止し、信頼できる上流の情報源を中心としたフローに再設計してください。

正しい例

const order = await ctx.clients.oms.getOrder(orderId)

ctx.body = {
  orderId: order.orderId,
  status: order.status,
}

誤った例

const cachedOrder = await ctx.clients.masterdata.getDocument({
  dataEntity: 'ORD',
  id: orderId,
})

ctx.body = cachedOrder

制約：大量データの読み取りでは、全件スキャンとメモリ内フィルタリングを避ける必要があります

大規模または増加中のデータセットには、全件スキャンや広範なメモリ内フィルタリングではなく、範囲を限定したクエリ、フィルター、ページネーション、または事前計算済みの派生ビューを通じてアクセスする必要があります。

これが重要な理由

範囲が限定されていない読み取りは非効率でスケールしにくく、データセットの増加に伴って、サービスの動作が不安定になりやすくなります。

検出方法

通常のリクエストフローで、Master Data、VTEX API、または外部ストアからコレクション全体を取得し、その結果を Node でフィルタリングまたは集計するコードが見つかった場合は、処理を停止し、アクセス経路を再設計してください。

正しい例

const documents = await ctx.clients.masterdata.searchDocuments({
  dataEntity: 'RV',
  fields: ['id', 'status'],
  where: 'status=approved',
  pagination: {
    page: 1,
    pageSize: 20,
  },
})

誤った例

const allDocuments = await ctx.clients.masterdata.scrollDocuments({
  dataEntity: 'RV',
  fields: ['id', 'status'],
})

const approved = allDocuments.filter((doc) => doc.status === 'approved')

推奨されるパターン

データ設計では、まず次の 4 つの問いから始めます。

1. このデータは誰のものですか？
2. 信頼できる唯一の情報源はどこですか？
3. アプリはどのようにデータをクエリしますか？
4. アプリは本当にローカルコピーを保存する必要がありますか？

次に、意図を明確にして選択します。

• 安定した設定には、アプリ設定または設定用アプリを使用する
• アプリのドメインが所有する構造化カスタムレコードには、Master Data を使用する
• シンプルなキー付きドキュメントやキャッシュのようなペイロードには、VBase を使用する
• 信頼できるコマースデータには、VTEX コア API を使用する
• VTEX 外で所有されているデータには、外部ストアまたは API を使用する

アプリがローカルコピーを保存する場合は、そのコピーを小さく、派生データに限定し、信頼できる情報源に対する二次的なものであることを明確にしてください。

よくある失敗パターン

• レコード、履歴、大規模なリストの汎用ストレージとしてアプリ設定を使用する。
• VTEX コアの注文、商品、価格の完全なコピーを、並行する信頼できる唯一の情報源として Master Data または VBase に保存する。
• 通常のリクエストフローで、メモリ内でフィルタリング、並べ替え、集計するためだけにデータセット全体を取得する。
• 上限のないデバッグログやイベントダンプに Master Data または VBase を使用する。
• データの鮮度、無効化、所有権のルールが明確でないままキャッシュを追加する。
• 信頼できる情報源やストレージに関する判断を明示せず、場当たり的なデータアクセスの判断をハンドラー全体に分散させる。

レビュー用チェックリスト

• このデータは本当に設定ですか？それとも Master Data、VBase、コア API、外部システムに保存すべきですか？
• 信頼できる唯一の情報源が明確になっていますか？
• 注文、カタログ、価格、在庫などのドメインについて、VTEX コアを信頼できる情報源として扱っていますか？
• ローカルストレージは、アプリが実際に所有するデータ、または限定された派生ビューに限られていますか？
• 適切な箇所で、フィルター、フィールド選択、ページネーションを使って読み取り範囲を限定していますか？
• キャッシュやローカルコピーの鮮度と無効化のルールが明確ですか？

関連スキル

• vtex-io-app-settings - 主な判断が、アプリレベルの設定のモデル化方法に関するものである場合に使用します
• vtex-io-service-configuration-apps - 共有する構造化設定を ctx.vtex.settings 経由で注入する場合に使用します
• vtex-io-masterdata-strategy - 主な判断が、Master Data が適切なストレージ手段かどうか、およびそのモデル化方法に関するものである場合に使用します

参考資料

• Master Data - アカウント単位の構造化されたカスタムデータストレージ
• VBase - VTEX IO アプリ向けのキーと値のストレージおよび JSON ブロブ
• VTEX IO クライアントを使用した VTEX コマース API の呼び出し - VTEX IO から Orders、Catalog、Pricing などの主要 API を利用する方法
• アプリの設定の構成 - 運用データの保存先ではなく、設定としてアプリの設定を使用する方法
• アプリ設定用のインターフェイスの作成 - 公開設定と非公開設定、および設定の境界