trpc-patterns

TRPC のパターン

概要

入力スキーマ、プロシージャの選択、ミドルウェアの合成、エラー処理に関する、確立された blogic-template-ts のパターンを使って TRPC ルーターを実装します。

このスキルを使用する場面

TRPC ルーターやプロシージャを実装またはリファクタリングする際、特にベースプロシージャの選択、認可ミドルウェアの追加、エラー処理の標準化を行う場合にこのスキルを使用します。

基本ルール

1) シンプルなスキーマはインラインにする

シンプルな入力スキーマは、プロシージャ内に直接定義します。

ハードコードした文字列リテラルの代わりに、プロジェクトの enum と共有型を使用します。

protectedProcedure.input(z.object({ organizationId: z.string().min(1) }));

次のルールを適用します。

• 分かりやすいスキーマはインラインにします。
• プロジェクトのパッケージにある共有 enum／型を再利用します。
• 再利用や複雑さを考慮して妥当な場合に限り、スキーマ定数を切り出します。

詳しい例は references/simple-schemas.md を参照してください。

2) 要件を満たす範囲で最も限定的なベースプロシージャを選択する

次の順序でベースプロシージャを選択します。

1. 実装の都合ではなく、アクセス要件を起点にします。
2. 認証が不要な場合は publicProcedure を選択します。
3. 認証済みのユーザーであれば誰でもアクセスできる場合は protectedProcedure を選択します。
4. グローバルな管理者ロールが必要な場合は adminProcedure を選択します。
5. organizationId にスコープされたメンバーシップが必要な場合は protectedMemberAccessProcedure を選択します。
6. 既存のプロシージャのいずれも必要なアクセスルールを表現できない場合に限り、.use() を使ってカスタムプロシージャを構築します。

次の判断フローを適用します。

• 認証不要 -> publicProcedure
• 認証が必要で、組織のスコープは不要 -> protectedProcedure
• グローバルな管理者のみの操作 -> adminProcedure
• 組織にスコープされた操作で、メンバーシップの確認が必要 -> protectedMemberAccessProcedure
• 追加のロール／権限／リソースの確認 -> 最も近いベースプロシージャにミドルウェアを追加して拡張

プロシージャの詳しい例とコンテキストの動作については、references/custom-procedures.md を参照してください。

3) コンテキストの拡張でミドルウェアを合成する

.use() で再利用可能なミドルウェアを作成し、必ず opts.next(...) で処理を続行します。

const procedure = protectedProcedure.use(async (opts) => opts.next({ ctx: {} }));

次のルールを適用します。

• ミドルウェア関数には、その役割が分かる名前を付けます。
• コンテキストは、後続のハンドラーに必要な値だけで拡張します。
• 新しいプロシージャを導入する前に、既存のベースプロシージャを基にします。

高度なミドルウェアのパターンについては、references/middleware-patterns.md を参照してください。

4) 標準化されたアプリケーションエラーをスローする

プロジェクトのインフラストラクチャから、標準化されたエラーヘルパーをインポートしてスローします。

if (!resource) throw notFoundError("Resource not found");

次のルールを適用します。

• ヘルパーベースのエラー（badRequestError、unauthorizedError、forbiddenError、notFoundError）をスローします。
• プロジェクトにヘルパーがある場合、ルートやミドルウェアのコードで TRPCError を直接インスタンス化しないでください。
• エラーメッセージは、アクションが明確で、ドメインに即したものにします。

詳しいパターンについては、references/error-handling.md を参照してください。

5) インポートはプロジェクトの規約に従う

blogic-template-ts リポジトリでは、次の規約に従います。

• 共有ドメインの enum／型は、プロジェクトのパッケージ（例：@project/common）からインポートします。
• 標準化されたエラーヘルパーは、プロジェクトのインフラストラクチャモジュール（例：@/infrastructure/errors）からインポートします。

このエコシステム以外で作業する場合は、対象のコードベースにある同等のモジュールにこれらの規約を対応させてください。

型推論の指針

バックエンドのルーター定義から、TypeScript の静的型推論を活用します。

次のルールを適用します。

• ルートルーターの型を一貫してエクスポートします。
• フロントエンドの TRPC クライアント設定にルーター型をインポートします。
• 推論された TRPC の型と重複するエンドポイントのレスポンス型／入力型を手動で定義しないでください。

追加の例については references/custom-procedures.md を参照し、ルーターのエクスポートに一貫性を保ってください。

対象範囲

このスキルでは、TRPC ルーターの構造、アクセス制御、ミドルウェア、エラーに重点を置きます。

クエリレベルのパフォーマンス最適化（JOIN 戦略、一括読み取り、N+1 の削減、インデックス作成）は、performance-optimization スキルに委ねてください。

リソース

詳しい例と実装の詳細については、以下をお読みください。

• references/simple-schemas.md - インラインスキーマパターンの完全な例
• references/custom-procedures.md - 基本的なプロシージャの動作とコンテキストの拡張
• references/middleware-patterns.md - 高度なミドルウェアの合成パターン
• references/error-handling.md - ヘルパーを使ったエラーパターンの詳細

クエリとデータベースのパフォーマンスに関するガイダンスを参照するには、performance-optimization スキルを読み込んでください。