fastify-best-practise

Fastify のベストプラクティス

本番環境に対応した Fastify アプリケーションを構築するための、厳選されたルールとパターンです。各ルールには、説明付きの誤った例と正しい例が含まれています。

仕組み

1. エージェントは、ユーザーが Fastify を使用している、または Fastify のパターンについて質問していることを特定します
2. トピック（ルート、バリデーション、カプセル化など）に基づいて、関連するルールファイルが読み込まれます
3. コードの生成またはレビュー時に、エージェントはそのルールのベストプラクティスを適用します

ルール

ルールは rules/ ディレクトリ内でトピックごとに整理されています。各ルールは、影響度の評価、誤った例と正しい例、公式ドキュメントへの参照を含む一貫した形式に従っています。

ルール	ファイル	影響	説明
設定	configuration.md	HIGH	環境設定、ロガーのセットアップ、セキュリティオプション、グレースフルシャットダウン
サーバーの作成	create-server.md	LOW-MEDIUM	再利用可能でテストしやすいサーバーセットアップには、buildServer() ファクトリー関数を使用します
プラグインの作成	create-plugin.md	LOW-MEDIUM	fastify-plugin を使用して、再利用可能な機能をプラグインにカプセル化します
自動読み込み	autoload.md	HIGH	@fastify/autoload を使用して、ファイルシステムからプラグインとルートを自動的に読み込みます
ルートのベストプラクティス	route-best-practices.md	MEDIUM	プラグイン／プレフィックスでルートを整理し、非同期ハンドラーとすべてのルートオプションを使用します
スキーマ検証（Zod）	schema-validation-zod.md	HIGH	Zod と fastify-type-provider-zod による型安全な検証
シリアライズ（Zod）	serialization-zod.md	HIGH	Zod スキーマによる型安全なレスポンスのシリアライズ、出力検証、互換性に関する注意事項
カプセル化	encapsulation.md	HIGH	適切なスコープ分離と、fastify-plugin を使用する場面
エラー処理	error-handling.md	HIGH	カスタムエラーハンドラー、@fastify/error、404 の処理、構造化レスポンス
フックとライフサイクル	hooks-lifecycle.md	MEDIUM	すべてのリクエスト／返信およびアプリケーションフック：onRequest、preParsing、preValidation、preHandler、preSerialization、onError、onSend、onResponse、onReady、onClose
ロギング	logging.md	HIGH	組み込みの Pino ロガー、リクエストの関連付け、機密情報のマスキング、子ロガー
認証	authentication.md	HIGH	@fastify/jwt による JWT 認証、@fastify/auth による複数の認証方式
テスト	testing.md	HIGH	inject()、buildServer パターン、vitest/node:test によるテスト
TypeScript	typescript-integration.md	MEDIUM	型プロバイダー、モジュールの拡張、型付きデコレーター
デコレーター	decorators.md	MEDIUM	decorate／decorateRequest／decorateReply で Fastify インスタンス、リクエスト、返信を拡張します
コンテンツタイプパーサー	content-type-parser.md	HIGH	カスタムコンテンツタイプパーサー、ボディ制限、マルチパートアップロード、包括的な照合と正規表現による照合
マルチパートとファイルアップロード	multipart.md	HIGH	@fastify/multipart によるファイルアップロード、ストリーミング、サイズ制限、MIME 検証
WebSocket	websockets.md	HIGH	@fastify/websocket によるリアルタイム双方向接続、ライフサイクル処理、ブロードキャスト、認証
HTTP プロキシ	http-proxy.md	HIGH	@fastify/http-proxy と @fastify/reply-from による API ゲートウェイ／BFF パターン、認証フック、エラー処理、複数のアップストリームへのルーティング
HTTP QUERY メソッド	http-query.md	HIGH	Fastify 5.11+ のネイティブな RFC 10008 QUERY ルート、ボディとメディアタイプの検証、安全で冪等なハンドラー、キャッシュと CORS の制約
型プロバイダー	type-providers.md	HIGH	TypeBox、json-schema-to-ts、Zod プロバイダーの比較、.withTypeProvider<T>()、プラグイン内のスコープ付きプロバイダー、プロバイダー固有のプラグイン型
デプロイ	deployment.md	HIGH	close-with-grace によるグレースフルシャットダウン、生存／準備プローブ、0.0.0.0 でのリッスン、trustProxy、マルチステージ Dockerfile、AWS Lambda アダプター
HTTP/2	http2.md	MEDIUM	HTTP/1.1 フォールバック付きの TLS 上での HTTP/2（h2）、または内部サービス向けのプレーンテキスト h2c を有効化。型付き buildServer ファクトリー
CORS とセキュリティヘッダー	cors-security.md	HIGH	@fastify/cors の許可リスト（静的および動的）、@fastify/helmet の CSP/HSTS、登録順序、統合セキュリティプラグイン
リクエスト受付の遅延	delay-accepting-requests.md	HIGH	依存関係の準備が整うまで 503 でリクエストを拒否。Kubernetes の生存プローブと準備プローブ
データベース統合	database-integration.md	HIGH	pg プールを Fastify プラグインとして登録し、安全なクエリには @nearform/sql を使用します
データベースマイグレーション	database-migrations.md	HIGH	起動時に Postgrator の SQL マイグレーションを実行し、適用済みファイルは決して変更しません
テストコンテナー	test-containers.md	HIGH	統合テスト用に Testcontainers で実際の Postgres コンテナーを起動します
クリーンアーキテクチャ	clean-architecture.md	HIGH	純粋なサービス層関数と薄いルートハンドラー、明示的な依存性注入
単体テスト	unit-testing.md	HIGH	モックのデータベーススタブを使用し、サービス関数を分離して単体テストします
パフォーマンス	performance.md	HIGH	スキーマの事前コンパイル、シリアライズ、負荷制御、ストリーミング、ベンチマーク
レート制限	rate-limiting.md	HIGH	@fastify/rate-limit による API の保護、ルートごとの上書き、Redis ストア、カスタムキー
シリアライズ	serialization.md	HIGH	JSON Schema と fast-json-stringify によるレスポンスのシリアライズ

使い方

Fastify のコードを生成する際は、対象のトピックに関連するルールファイルを読み、記載されたパターンを適用してください。新しいプロジェクトでは、すべてのルールが該当します。特定のタスクでは、必要なものだけを読み込んでください。

• 新しいプロジェクトのセットアップ：create-server.md、configuration.md、autoload.md、encapsulation.md、typescript-integration.md
• ルートの追加：route-best-practices.md、autoload.md、schema-validation-zod.md、serialization-zod.md、serialization.md
• 共有サービスの追加：create-plugin.md、autoload.md、encapsulation.md
• 設定／環境：configuration.md
• エラー処理：error-handling.md
• 認証／ミドルウェア：authentication.md、hooks-lifecycle.md、encapsulation.md
• レート制限：rate-limiting.md、hooks-lifecycle.md
• カスタムデコレーター：decorators.md、typescript-integration.md
• ロギング：logging.md
• ボディー解析／ファイルアップロード：content-type-parser.md、multipart.md
• スキーマ／型プロバイダー：schema-validation-zod.md、serialization-zod.md、serialization.md、type-providers.md
• HTTP/2／TLS：http2.md、configuration.md
• CORS／セキュリティヘッダー：cors-security.md、rate-limiting.md
• 本番環境へのデプロイ：deployment.md、delay-accepting-requests.md、configuration.md
• リアルタイム通信／WebSocket：websockets.md、authentication.md、hooks-lifecycle.md
• API ゲートウェイ／プロキシ：http-proxy.md、hooks-lifecycle.md、error-handling.md
• 起動／ヘルスチェック：delay-accepting-requests.md、hooks-lifecycle.md、configuration.md
• パフォーマンスのチューニング：performance.md、schema-validation-zod.md
• テストの作成：testing.md、create-server.md
• データベースのセットアップ：database-integration.md、database-migrations.md
• 実際の DB を使った統合テスト：test-containers.md、testing.md
• 関心事の明確な分離：clean-architecture.md、unit-testing.md
• ビジネスロジックの単体テスト：unit-testing.md、clean-architecture.md
• ボディーを含む安全なクエリ（QUERY メソッド）：http-query.md、schema-validation-zod.md、cors-security.md
• レスポンスのシリアライズ：serialization.md、serialization-zod.md、schema-validation-zod.md

推奨プロジェクト構成

@fastify/autoload を使用すると、プラグインとルートが各ディレクトリから自動的に読み込まれます。

src/
  plugins/          # Autoloaded — shared plugins (use fastify-plugin)
    db.ts           # Database client (pg/Drizzle/Prisma) + lifecycle
    auth.ts
    config.ts
  routes/           # Autoloaded — encapsulated route plugins (NO fastify-plugin)
    _hooks.ts       # Global route hooks (with autoHooks: true)
    users/
      index.ts      # → /users  (thin handler — calls services/users.ts)
      _hooks.ts     # Hooks for /users scope only
      schema.ts     # Zod schemas
    posts/
      index.ts      # → /posts
      schema.ts
  services/         # Pure business logic — no Fastify imports, injectable deps
    users.ts
    posts.ts
  db/
    migrate.ts      # runMigrations() helper (uses Postgrator)
  server.ts         # buildServer() with autoload registration
  app.ts            # Entry point — runMigrations() then server.listen()
migrations/         # Raw SQL files (committed to git): 001.do.*.sql, 001.undo.*.sql
test/
  services/
    users.test.ts   # Unit tests — pure functions, mock db
  routes/
    users.test.ts   # Integration tests — inject() + real schema
  helpers/
    server.ts       # createTestServer() / createIntegrationServer()
    db.ts           # startTestDatabase() via Testcontainers

結果をユーザーに提示する

これらのベストプラクティスを適用した場合は、どのルールに従ったかを伝えてください。

Fastify のベストプラクティスを適用しました：

• ルートの構成：ルートをリソースごとにグループ化し、プレフィックスを付与
• Zod によるバリデーションとシリアライズ：型推論と出力バリデーションを備えたリクエスト／レスポンスのスキーマ
• カプセル化：共有プラグインでは fastify-plugin を使用し、ルートはスコープ内に維持
• エラー処理：@fastify/error を使用したカスタムエラーハンドラー
• パフォーマンス：レスポンススキーマ、共有スキーマ参照、負荷遮断、ストリーミング、ベンチマークのガイダンス
• データベース：共有プールとライフサイクル管理のため、クライアントを fastify-plugin を使用したプラグインとして登録
• マイグレーション：サーバー起動前に Postgrator（runMigrations()）で適用し、未加工の SQL ファイルは git で追跡
• クリーンアーキテクチャ：ビジネスロジックは純粋なサービス関数に置き、ルートハンドラーは薄く保つ
• 単体テスト：サービス関数をモック DB スタブで分離してテスト
• HTTP QUERY メソッド：Fastify 5.11+ のネイティブな RFC 10008 ルート。ボディーとメディアタイプのバリデーション、安全で冪等なハンドラー、ボディーを考慮したキャッシュキー、オプションのディスカバリー／リソースヘッダー、CORS プリフライトへの対応
• 統合テスト：Testcontainers を使用した実際の Postgres コンテナー

参考資料

• Fastify ドキュメント
• Fastify GitHub
• Fastify エコシステム
• @fastify/autoload