faasjs-best-practices

FaasJS のベストプラクティス

デフォルトのワークフロー

1. タスクの領域を特定し、その領域を担当する最も範囲の狭い FaasJS スキルを読み込みます。
2. インポートやパスを選ぶ前に、リポジトリ内の指示と関連する tsconfig.json ファイルを確認します。
3. 変更は最小限にとどめ、タスクの範囲内に限定します。設定変更を伴わない無関係なリファクタリング、推測に基づくフォールバック、新しいエイリアスは避けます。
4. 外部入力は境界で検証し、データにアクセスする前に認証・テナント・権限のスコープを確認し、秘密情報は決してログに記録しません。
5. 引き継ぐ前に、可能であれば vp check --fix && vp test を実行します。実行できない場合は、その理由を記録し、役立つ範囲で最小限の検証を行います。

これらのリファレンスを読み込む

• 新規プロジェクト、機能の構成、設定、CLI、コメント、命名、共通テスト：faasjs-project-workflow を使用します。
• React UI、@faasjs/ant-design、useFaas、フォーム、テーブル、ドロワー、CRUD 画面、React テスト：faasjs-react-ant-design を使用します。
• .api.ts、defineApi、HTTP プラグインヘルパー、ミドルウェア、.job.ts、defineJob：faasjs-api-jobs を使用します。
• @faasjs/pg、QueryBuilder、テーブル宣言、マイグレーション、PostgreSQL テスト：faasjs-pg を使用します。
• 同じトランザクション内でジョブをキューに追加するビジネス書き込み：faasjs-pg と faasjs-api-jobs の両方を読み込みます。
• プラグインのライフサイクル、注入されるフィールド、ロガーの使用、Node のブートストラップ、実行時設定の読み込み：faasjs-plugins-runtime を使用します。
• @faasjs/utils、JSON、YAML、ストリームヘルパー、検証ヘルパー：faasjs-utils-data を使用します。
• faas.yaml、ルーティング、HTTP プロトコル、プラグインのコントラクトに関する規範的な実行時の動作：faasjs-specs を使用します。

注意点

• Zod は外部入力のコントラクトに使用します。内部の typeof、instanceof、null チェックは制御フロー述語として維持します。
• ローカルの TypeScript インポートでは拡張子を省略し、深い相対インポートより設定済みのエイリアスを優先します。
• React フックの戻り値と、トップレベルの defineApi／defineJob のハンドラーコンテキストのみを分割代入します。ビジネス上の値は params.key として見える状態に保ちます。
• 中間変数が複雑な条件を説明する場合、再利用される場合、または可読性を高める場合を除き、値は直接返します。
• 生成されるジョブのパスを実行時の検出方法と一致させ、トランザクションのスコープ内で使用するクライアントをコールバックの外に持ち出さないでください。

検証

• フォーマットとリントには vp check --fix を使用します。
• テストには vp test または vp test <pattern> を使用します。
• .api.ts または .job.ts ファイルを追加、名前変更、移動、削除した後は、npx faas types を実行します。
• データベースの変更で必要となり、DATABASE_URL が利用可能な場合に限り、npx faasjs-pg migrate または対象を絞った PG チェックを実行します。