Modular Backend
リクエストされた動作を、最小限の読みやすい変更で完了してください。これらの規約を新しいバックエンドと、既存プロジェクトの影響を受けるコードに適用します。焦点を絞った修正をプロジェクト全体の移行に拡大しないでください。
関連するリファレンスを読み込む
| タスク | 読むもの |
|---|---|
| 新しいモジュール、構造リファクタリング、DTO、依存性注入 | アーキテクチャ |
| エラー契約、バリデーション失敗、グローバルフィルター、i18n | エラーとi18n |
| クエリ、インデックス、トランザクション、Redis、キャッシュ/ストレージ動作 | データとRedis |
| ユーザー、認証パッケージ、セッション、OAuth、デバイス、フィンガープリント、パスワード/IPハッシュ | アイデンティティ |
| ヘッダーとJWTガード、ミドルウェア、ルートおよびパラメータデコレータ | リクエスト境界 |
| ブートストラップ、設定、レート制限、ログ、ヘルスチェック、検証 | 運用 |
| キュー、ワーカー、スケジュール、ウェブフックの冪等性、リソース制限 | バックグラウンドワーク |
| Dockerfile、ローカルCompose、起動/停止Bashスクリプト、API/ワーカーコマンド | Docker |
| CIチェック、コンテナ、マイグレーション、リリース、ロールバック | CI/CD |
新しいバックエンド、基盤の全面見直し、または不足しているベースラインコンポーネントの修正リクエストの場合は、編集前にアーキテクチャ、運用、エラーとi18n、リクエスト境界、Docker、データとRedisを読んでください。他のリファレンスはタスクの必要に応じて読んでください。インストールされているバージョンと実際のドメインに合わせて例を適応させてください。ポータブルなMarkdownと標準的なプロジェクトツールを使用してください。ホストエージェントの権限モデルに従ってください。
編集前にスコープを確立する
リポジトリの指示、パッケージマニフェスト、ブートストラップ、影響を受けるモジュールと呼び出し元、関連するスキーマ、Redisの使用状況、テストを読んでください。設定定義とサンプル変数名を発見に使用してください。
新しいバックエンド。 基盤とアーキテクチャのルールを直接適用してください。接続されたベースラインを実装し、要求された製品フローに関連するリファレンスを使用してください。動作やデータの所有権に影響を与える不足している製品上の決定事項については質問してください。スキルはすでにベースラインのエンジニアリング上の選択を設定しています。
既存のバックエンド。 読み取り専用のアーキテクチャ評価から始めてください。現在のアーキテクチャ、提案するターゲット、そしてどのコンポーネントを保持、変更、追加、または延期するかを提示してください。「modular-backendに従ってこのバックエンドを修正してください」 はバックエンド全体をカバーします。リクエストが特定の変更を選択せずに標準を指定する場合は、どの提案を適用するかを1つの簡潔な質問で尋ね、決定を待ってください。ユーザーがすでに特定の変更を明示的にリクエストした場合は、最初に関連するアーキテクチャを分析して共有し、その変更を進め、さらにアーキテクチャ上の変更を行う前に質問してください。分析のみのリクエストは評価で終了します。ユーザーがスコープを選択した後、それを実装し、該当する受け入れチェックを実行してください。
機能、エンドポイント、またはバグを指定するリクエストの場合は、評価をそのパスと影響を受ける呼び出し元に限定してください。これらのルールに従う最も近い既存のモジュールを、命名、ファイル配置、DTO、エラー、トランザクションスタイルのモデルとして使用してください。
新しいバックエンド、基盤の全面見直し、またはベースラインの修正
- AppBuilderとHelmetはHTTPに必須です。
src/main.tsは薄く保ち、HTTP構築はsrc/builder/app.builder.tsに配置してください。NestFastifyAdapterを明示的に使用するか、NestなしのNode.js HTTPには直接fastifyを使用してください。互換性のある@fastify/helmetを初期化またはリッスン前に登録してください。HTTP統合テストでは実際のビルダーをバインドしてください。HTTPを持たないワーカーは独自のエントリポイントを使用します。 - HTTPエラーを1つのグローバルフィルターまたはFastifyハンドラーでローカライズしてください。
code、status、messageKeyを持つモジュールエラー定義、型付きレジストリ、共有例外を使用してください。新しいHTTPコントラクトでは{ status, code, message }を返してください。statusはHTTPステータスと一致し、codeは言語間で安定し、messageはi18nから取得されます。既存のAPIについては、互換性のある移行が合意されるまで公開フィールドを保持してください。 - Redisインフラストラクチャと実際のRedisデータパスは必須です。 検証済みの接続設定、集中管理されたRedisキーとTTLファイル、1つの共有Redisプロバイダー、そして準備完了プローブを追加してください。Redisに、それが信頼できる情報源である少なくとも1つの有用なデータファミリーを割り当ててください。ドメインリポジトリを介して実際の読み取りと書き込みを実装してください。接続、ヘルスプローブ、またはSQLレスポンスキャッシュだけではこのルールを満たしません。公開されたクライアント設定、ライブランキング/状態、共有スロットリングなど、既存の製品フローを適切に使用してください。製品にクライアント設定またはバージョンポリシーがある場合は、その公開ドキュメントをRedisに保存して提供してください。スコープから正当なデータファミリーを選択できない場合は、不足している製品上の決定事項を特定してください。
- 共有テンプレートからRedisキーを生成してください。
[プレースホルダー]テンプレートはredis-keys.config.tsに、TTLはredis-ttl.config.tsに、generateRedisKey/generateRedisKeysはsrc/utils/redis-key.util.tsに保持してください。共有プロバイダーが設定された名前空間を一度適用するようにしてください。実際のリーダー、ライター、ジョブでこのパスを使用してください。ユーザーが計画された移行を選択しない限り、改訂中は既存のキー形式を保持してください。Redisキー例 を参照してください。 - Redisが所有し、準備された読み取りはRedisに残してください。 キーファミリーごとに、投入、更新、キー欠落、有効期限、停止、復旧の動作を設定してください。真のエンティティ欠落には型付きの不在を、停止や準備ができていない必要なプロジェクションには型付きの利用不可を使用してください。これらの役割に対するSQLフォールバックをクエリしないでください。合意された使い捨てキャッシュに対してのみ、明示的なキャッシュアサイド例外を使用してください。無関係な改訂では既存の読み取りコントラクトを保持してください。
- HTTP用の共有レート制限を組み込んでください。 実施ガードまたはフックを登録し、外部ルート用のデフォルトバジェットを設定してください。存在する認証、復旧、および高コストなアクションには、Redisバックアップのより厳しいバジェットを追加してください。パスワードログインには、別々のIPと正規化されたアカウントカウンターを使用してください。アトミックにインクリメントして期限切れにし、429と
Retry-Afterで応答し、必要な実施が利用できない場合は型付きの503を返してください。システムルートの例外には明示的なポリシーを使用してください。 - HTTPで公開されるすべての増加コレクションにページネーションを適用してください。 検証済みのクエリDTO、制限付きの上限、およびすべてのソート値と一意のタイブレーカーを含む安定したキーセットカーソルを使用してください。リポジトリ内の呼び出し元のスコープとフィルターを使用して
limit + 1をクエリしてください。新しいリストには{ items, nextCursor }を返してください。正確な合計を計算し、APIコントラクトで必要な場合にのみページ番号オフセットを使用してください。 - APIが使用するガードとデコレータを配線してください。 モバイル/デバイスコントラクトには型付きヘッダーガードを、保護されたJWTルートにはJWTガードを、ポリシーで必要な場合にはロール、ゲスト、またはプロバイダー固有のガードを使用してください。ガードを登録し、パラメータデコレータを使用して検証済みのコンテキストを消費してください。クロスカッティングなトランスポート関心事にはFastifyリクエストフックまたは既存のミドルウェアを使用してください。
- 実行可能なDockerワークフローを提供してください。 Dockerfile、ローカル依存関係用のCompose、プロジェクトスコープのBash起動/停止コマンドを提供または再利用してください。準備完了を待ち、信頼できるデータには永続ボリュームを使用してください。改訂時には同等の確立されたワークフローを保持してください。ワークロードがそれを正当化する場合にのみ、ジョブスケジュールとコンシューマーを実行してください。
- 必要なモジュール/機能のみを実装してください。認証/ユーザー/デバイスワークフローは再利用可能なガイダンスであり、それを必要としないサービスにアカウント機能を追加する許可ではありません。
- 最初にNode.jsの組み込み機能と公式のNestJSモジュールを使用してください。承認されたベースラインには、互換性のある
@fastify/helmet、単一のRedisクライアント、および適切なi18n統合がインストールされていない場合のNest HTTPエラー用のnestjs-i18nが含まれます。新しいパスワード認証フローは、Argon2id用の互換性のあるargon2を使用してもかまいません。トークンダイジェストとキー付きフィンガープリントにはnode:cryptoを使用してください。既存の動作するRedisクライアントを保持するか、新しいプロジェクトではデフォルトでredisにしてください。インポートされた場所ではfastifyを直接使用してください。その他の新しいサードパーティパッケージ、オプションのピア、Fastifyプラグインは明示的な承認が必要です。運用 を参照してください。 - 接続されたブートストラップ、検証済み設定、プロバイダー、必要なマイグレーション、ローカルセットアップ、および要求されたAPIを提供してください。接続されていないスキャフォールドファイルで止まらないでください。
既存のバックエンド / 改訂
- 共有関数を変更したりファイルを移動したりする前に、すべての呼び出し元を見つけてください:サービス、コントローラー、ジョブ、ガード、エクスポート、モック、フィクスチャ、レスポンスコンシューマー。
- 無関係な変更、パブリックコントラクト、トークン/ストレージ動作、バリデーション、所有権フィルター、確立された命名を保持してください。クリーンアップはタスクのパスに限定してください。
- タスクがHTTP基盤をセットアップ、置換、または修復する場合、Fastify、AppBuilder、Helmetをまとめてスコープに入れてください。無関係な機能変更中はアダプターとブートストラップを保持してください。Fastifyに移行する場合は、該当する場合、ステータスコード、ミドルウェア、クッキー、アップロード、署名付きウェブフックボディを確認してください。
- 関連するサービスを変更する場合、クエリを具体的なリポジトリに抽出してください。トランザクションコンテキスト、ロック、エラーハンドリング、戻り値の形状、ソフトデリート、テナントスコープを保持してください。
- リストまたはリミッターを変更する場合、既存のパブリックカーソルとレスポンスコントラクトを保持し、スコープ内でバリデーションを強化してください。レート制限メタデータを実行中のガードまたはフックにトレースしてください。データクエリではアクターとテナントのスコープを維持してください。互換性のないカーソルまたはリミッターキーの変更は明示的に計画してください。
- インフラストラクチャのセットアップまたはリファクタリングの場合、同じパッケージポリシーを適用してください。タスクが変更しない限り、既存の統合を保持してください。パッケージを追加する前に、要求されたインフラストラクチャに必要な依存関係を解決してください。
- フォールバックを黙って削除したり、セッションストレージを切り替えたり、トークンの有効期間を変更したり、クリーンアップとしてすべてのセッションを無効にしたりしないでください。要求された移行のための互換性とデータ/キー移行を計画してください。
- 必要なマイグレーションを作成してください。ライブデータを削除したり、誤って本番マイグレーションを実行したりしないでください。
アーキテクチャルール
src/modules/の下の各機能に完全なレイアウトを使用してください。 すべての機能モジュールにはdto/、コントローラー、サービス、リポジトリ、および<feature>.module.tsが含まれます。モジュールルートには単一のコントローラー、サービス、またはリポジトリを保持してください。レイヤーが複数のファイルを取得する場合、controllers/、services/、またはrepositories/にグループ化してください。必要な場合はモジュール固有のエラーにerrors/を使用してください。機能APIやデータアクセスを持たない場合は、サポートプロバイダーをインフラストラクチャの下またはジョブをワーカーの下に配置してください。スコープされた改訂では、モジュールレイアウトの変更がタスクの一部でない限り、既存のパスを保持してください。- コントローラーはHTTPを処理し、サービスは決定し、リポジトリはデータにアクセスします。 コントローラーにビジネスロジック、ORMクエリ、またはRedisコマンドはありません。サービスはルールとオーケストレーションを所有します。リポジトリはクエリとRedis操作を所有し、アトミックな不変条件を強制する条件付き書き込みを含みます。
- 実際的に構成してください。 モジュール間のビジネスアクションは、所有するサービスを呼び出します。データのみの作業または共有トランザクションのために、エクスポートされたリポジトリの直接使用は許可されます。体裁のためにパススルーサービスメソッドを作成しないでください。
- トランザクションの所有権を作業の近くに保ってください。 サービスは1つの渡されたトランザクションクライアントで複数のリポジトリにまたがることができます。リポジトリは自己完結型のアトミック操作を所有できます。すべての参加者はそのクライアントを使用します。汎用のUnit of Workやトランザクションフレームワークはありません。
- 小さく、読みやすいコードを書いてください。 ヘルパー、標準API、インストール済みの依存関係を再利用してください。投機的なオプション、ラッパー、基底クラス、汎用リポジトリ、および使い捨ての抽象化を避けてください。冗長なバリデーションとキャッチ&スローを削除してください。境界バリデーション、認可、並行性、およびデータ損失に対する保護は保持してください。
- 実際の作業を減らしてください。 クエリ、ラウンドトリップ、フィールド、行、および中間割り当てを最小限にしてください。アイテムごとの並列クエリは依然としてN+1です。ワークロードの時間と空間のバランスを取ってください。両方の絶対最小値を約束したり、速度のためにパスワードハッシュを弱めたりしないでください。
- インデックスを正当化してください。 各インデックスを実際のクエリまたは整合性制約にリンクしてください。さらに追加する前に、主/一意/複合インデックスを検査してください。投機的な重複を追加したり、スキーマの外観のみに基づいてインデックスを削除したりしないでください。
- Redisに役割を割り当ててください。 プライマリデータ、準備された読み取りモデル、使い捨てキャッシュを区別してください。所有権、投入/更新、TTL、ミス、停止、復旧を定義してください。データベースへの自動キャッチフォールバックはありません。キャッシュミスと接続障害は別物です。データリファレンスからポリシーを選択してください。
- 共有コードのみを共有してください。 共通ヘルパーはutils/commonに、インフラストラクチャはlibsに、共有設定はconfigに属します。モジュール専用のヘルパーはローカルに保ってください。RedisキーとTTLを集中化してください。
- エラーを所有し、型付けしてください。 モジュールの
errors/ディレクトリの下にドメインエラーを定義してください。AppExceptionを通じて登録されたErrorCodeをスローし、HTTP境界でそのmessageKeyを翻訳してください。内部クエリ、スタックトレース、シークレット、プロバイダーの詳細をレスポンスから除外してください。
完了して確認する
必要な呼び出し元、DTO、エラー定義、プロバイダー/エクスポート、設定、スキーマ/マイグレーション、テストを更新してください。成功だけでなく、重要な失敗も実装してください。
基盤作業の場合は、受け入れチェック に従ってください。本番エントリポイントをビルダー経由で、1つの実際の機能をRedisリポジトリ経由でトレースしてください。Helmet、ローカライズされたHTTPエラーコントラクト、Redisの初期化とシャットダウン、およびミスと停止を確認してください。実際の制限付きルートで429と503を確認し、新しい各リストコントラクトで安定したページネーションをテストしてください。欠落または未確認のベースライン項目を報告してください。
新しい非自明なロジックには、小さな動作テストまたはアサートベースのチェックが必要です。影響を受ける不変条件を確認してください:所有権、クエリ数、ロールバック、トークンの有効期限/再利用/並行性、Redisのミスと停止、またはアトミック更新。自明な移動は実装ミラーリングを必要としません。