マイグレーションガイド: v1.7.0

このガイドは v1.6.x から v1.7.0 へのアップグレードを支援します。バージョン 1.7.0 は CommandService に atomic なコマンドアドミッション条件を追加します。実行時の破壊的変更はありません。新しいフックをオーバーライドしない限り、既存のアプリケーションの動作はまったく変わりません。一部のユニットテストでは、モックの小さな更新が必要になる場合があります。

リリース日

2026-11-09

変更の概要

変更内容	影響	必要なアクション
新しい getCommandAdmissionConditions フック (core)	オーバーライドしない限りなし。デフォルトはチェックを返さず、通常の PutItem 経路のまま	なし。任意: コマンドの受け付けを制御するためにオーバーライドする
新しいアドミッション例外 (core)	フックがチェックを返した場合にのみスローされる	なし。フックを使う場合は処理する
CommandService が putItemWithConditions 経由で書き込む (core)	putItem だけを持つ手書きの DynamoDbService モックは失敗する。createMock() の自動モックは putItem に到達しなくなる	手書きのモックに putItemWithConditions を追加する。自動モックではそれをアサートするかスタブする
CLI インフラテンプレートの dynamodb:ConditionCheckItem	新規プロジェクトのみ	フックを使う場合は手動でアクションを追加する

移行前チェックリスト

• プロジェクトがすでに v1.6.x と Node.js 22 で動作している（v1.6.0 移行ガイドを参照）
• ユニットテストが DynamoDbService を手書きでモックしているか、createMock() でモックしているかを把握している

テストモックの更新

CommandService はすべての初回コマンドを DynamoDbService.putItemWithConditions 経由で書き込むようになりました。チェックが返されない場合、実際のメソッドは putItem を呼びます。テストで DynamoDbService をどのようにモックしているかを確認してください:

モックの方法	v1.7.0 以降の動作	対応
実際の DynamoDbService（例: aws-sdk-client-mock を使用、または putItem に jest.spyOn）	引き続き動作する: 条件がない場合、putItemWithConditions は putItem に委譲する	不要
putItem だけを定義した手書きのモック	putItemWithConditions is not a function で失敗する	putItemWithConditions を追加する
createMock()（@golevelup/ts-jest）による自動モック	例外は出ないが、putItemWithConditions が自動モックされるため putItem に到達しない。putItem に対するアサーションが原因の分かりにくい形で失敗する	putItemWithConditions をアサートするか、putItem を呼ぶようにスタブする

手書きのモックの場合:

// Before (v1.6.x)
const dynamoDbService = {
  getItem: jest.fn(),
  putItem: jest.fn(async (tableName, item) => item),
}

// After (v1.7.0)
const dynamoDbService = {
  getItem: jest.fn(),
  putItem: jest.fn(async (tableName, item) => item),
  putItemWithConditions: jest.fn(function (tableName, item, condition) {
    return this.putItem(tableName, item, condition)
  }),
}

createMock() の自動モックの場合は、putItemWithConditions をアサートするか、putItem を呼ぶようにスタブしてください。両方の方法はユニットテストを参照してください。フレームワークはこの動作を PR #516 で確認しています。

新機能: コマンドアドミッション条件

CommandService のサブクラスは、protected の getCommandAdmissionConditions(command, options) メソッドをオーバーライドして DynamoDB の ConditionCheck エントリを返せます。フレームワークはそれらを初回コマンドと同じ TransactWriteItems リクエストで書き込むため、コマンドはすべてのチェックが成功した場合にのみ受け付けられます。典型的な用途は、事前のゲート確認による競合なしに、メンテナンス中に他のコマンドを継続させつつ設定の更新を凍結することです。

トランザクションがキャンセルされると、フレームワークは次の例外をスローします:

例外	HTTP	発生条件
CommandAdmissionRejectedException	409	アドミッションチェックが失敗した
ConditionalCheckFailedException	409	コマンド書き込み自体がバージョン競合した
CommandAdmissionContentionException	503	トランザクションが TransactionConflict でキャンセルされた
TransactionCanceledException	500	その他のキャンセル

フック、サブクラスの例、プロバイダーの登録についてはコマンドアドミッション条件を参照してください。

フックを使う前に

• IAM: すべての witness テーブルに dynamodb:ConditionCheckItem を付与してください。v1.7.0 より前に mbc new で生成したプロジェクトにはこの権限がありません。infra/libs/infra-stack.ts の DynamoDB ポリシーに追加してください（CDK インフラストラクチャを参照）。権限がない場合、保護されたコマンドはアクセス拒否エラーで失敗します。
• キャパシティ: トランザクション内のすべての項目は、キャンセルされた場合でも 2 倍の書き込みキャパシティを消費します。
• 競合: 同じ witness 項目をチェックする同時実行コマンドは、DynamoDB サービス上で TransactionConflict により互いにキャンセルし合う可能性があります。これは未計測で、DynamoDB Local では再現しません。想定される同時実行数で実環境の負荷テストを行ってください。

CLI テンプレート（新規プロジェクトのみ）

ファイル	変更前	After (v1.7.0)
infra/libs/infra-stack.ts	dynamodb:PutItem, UpdateItem, GetItem, Query	dynamodb:ConditionCheckItem も追加

既存のプロジェクトは変更されません。追加のアクションはフックを使う場合にのみ必要です。

アップグレード手順

Step 1: 依存関係を更新

npm install \
  @mbc-cqrs-serverless/core@^1.7.0 \
  @mbc-cqrs-serverless/tenant@^1.7.0 \
  @mbc-cqrs-serverless/master@^1.7.0 \
  @mbc-cqrs-serverless/sequence@^1.7.0 \
  @mbc-cqrs-serverless/task@^1.7.0 \
  @mbc-cqrs-serverless/cli@^1.7.0

Step 2: テストモックを更新

手書きの DynamoDbService モックに putItemWithConditions を追加し、createMock() の自動モックに依存した putItem のアサーションを更新してください（テストモックの更新を参照）。

Step 3: テストとデプロイ

npm run test:cov

サポート

移行中に問題が発生した場合：

• GitHub Issues
• ドキュメント

関連ドキュメント

• 変更履歴 v1.7.0 - v1.7.0 リリースノート
• CommandService - コマンドアドミッション条件
• エラーカタログ - コマンドアドミッションの例外
• ユニットテスト - CommandService 向けの DynamoDbService のモック