メインコンテンツまでスキップ

移行ガイド: v1.3.1

このガイドはv1.3.0からv1.3.1へのアップグレードを支援します。v1.3.1には破壊的変更がないため、既存のコードはそのまま動作します。

リリース日

2026-06-02

破壊的変更のサマリー

v1.3.1には破壊的変更はありません。アップグレードはそのまま互換性があります。

移行前チェックリスト

アップグレード前に、以下を確認してください:

  • アップグレード後にテストスイート全体を実行して、リグレッションがないことを確認する

アップグレード手順

ステップ1:依存関係の更新

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

ステップ2:テストの実行

npm run test:cov

v1.3.1の新機能

グループベースのロール認可(オプトイン)

RolesGuardは、custom:groups JWTクレームに格納されたユーザーのグループメンバーシップからロールを解決できるようになりました。グループの解決には実装したカスタムリゾルバーを使用し、グループIDからロールへのマッピングはJWTに格納されません。

この機能は完全にオプトインです。 既存の@Roles()チェックはコード変更なしで引き続き動作します。グループ由来のロールを使用したい場合のみ対応が必要です。

有効化方法:GroupRoleResolverの実装

import {
GroupRoleResolver,
IGroupRoleResolver,
ResolveGroupRolesInput,
} from "@mbc-cqrs-serverless/core";

// @Injectable()を追加しない — @GroupRoleResolver()がシングルトンプロバイダーを登録する
@GroupRoleResolver()
export class AppGroupRoleResolver implements IGroupRoleResolver {
async resolveRoles({
tenantCode,
groupIds,
claims,
}: ResolveGroupRolesInput): Promise<string[]> {
// グループIDをロールにマッピング(DB、設定、またはハードコードから取得)
return groupIds.includes("admin-group") ? ["admin"] : ["user"];
}
}

AppModuleにリゾルバーをプロバイダーとして登録:

import { Module } from "@nestjs/common";
import { AppGroupRoleResolver } from "./app-group-role-resolver";

@Module({
providers: [AppGroupRoleResolver],
})
export class AppModule {}
リゾルバーのガイドライン
  • リゾルバークラスに**@Injectable()を追加しないでください**。@GroupRoleResolver()と同時に追加するとスコープの競合が発生します(AP027アンチパターン)。@GroupRoleResolver()はすでにクラスをシングルトンプロバイダーとして登録します。
  • エラーを伝播させる — リゾルバーエラーはサイレントな403ではなく5xxとして現れ、バックエンドの停止と実際のアクセス拒否を区別できます。
  • アプリケーションごとにリゾルバーは1つだけ実装してください。

AP027: @GroupRoleResolver + @Injectableアンチパターン

新しいAP027アンチパターン検出器(mbc_check_anti_patterns)は、@GroupRoleResolver()@Injectable()の両方が付与されたリゾルバークラスを検出します。リゾルバーを作成する場合は、@GroupRoleResolver()のみを付与してください。

完全なドキュメントは認証 — グループベースのロールを参照してください。

UserContextフィールドの更新

getUserContext()UserContextに2つの追加フィールドを返すようになりました:

フィールド説明
tenantRolesstring[]アクティブなテナントのcustom:rolesクレームからの直接ロール
tenantGroupIdsstring[]アクティブなテナントのcustom:groupsクレームからのグループID

既存のtenantRole(単数形の文字列)は後方互換性のために維持されます。

フォールトトレラントなcustom:groupsパース

custom:groups JWTクレームが不正または欠落している場合、フレームワークはエラーをスローする代わりに空のグループリスト(グループロールなし)にフォールバックします。これにより、リクエストは直接ロールのみで処理を続行できます。

サポート

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

関連ドキュメント