@maru
Fastify 5.10 ガイド — LogControllerとTypeBoxの実践的パターン
Node.jsエコシステムにおいて高性能バックエンド構築の標準となったFastifyが、v5.10.xのアップデートでより堅牢かつ柔軟になりました。今回のメジャーバージョンでは、レガシーな構造が刷新され、厳格なJSONスキーマ仕様への準拠が義務付けられたほか、新しいログコントローラーレイヤーにより、ロギングのパフォーマンスと拡張性が大幅に強化されています。複雑なマイクロサービス環境でランタイム性能を最大化し、堅牢な型安全性を確保するために、開発者が適用すべき不可欠なプロダクション設計パターンをまとめます。
1. LogControllerの導入 — 宣言的に制御するリクエストログ
Fastify v5.10.0の最大のアーキテクチャ上の変更は、新しいログコントローラーレイヤーの導入です。従来のトップレベルオプションであったdisableRequestLoggingやrequestIdLogLabelは公式に非推奨となり（FSTDEP023, FSTDEP024）、将来のv6バージョンで完全に削除される予定です。代わりに、今後はLogControllerクラスを継承することで、宣言的かつオブジェクト指向的な手法でロギングのライフサイクルを制御できるようになります。
この構造を利用することで、/healthのようなヘルスチェックパスのログを省略したり、リクエスト完了時に特定の指標を一貫して記録するロジックを容易に実装可能です。Fastify公式GitHubのPR #6580で定義されたアーキテクチャに基づいて設計されており、ランタイムオーバーヘッドを引き起こすような一時的なフック呼び出しなしで、エンジンレベルでの高性能なロギングフィルタリングが可能です。
次はLogControllerを継承して/healthパスのログを無視し、レスポンス終了時に経過時間を記録する実践的な例です。
import Fastify, { LogController, FastifyRequest, FastifyReply } from 'fastify';
class CustomLogController extends LogController {
// /health 헬스체크 경로의 로그 기록을 제외합니다.
override isLogDisabled(request: FastifyRequest): boolean {
return request.url === '/health';
}
// 요청 완료 시점에 실행되어 최종 처리 지표를 기록합니다.
override requestCompleted(
error: Error | null,
request: FastifyRequest,
reply: FastifyReply,
metadata?: Record<string, unknown>
): void {
const duration = reply.elapsedTime; // Fastify v5에서 표준화된 경과 시간 속성
const level = error ? 'error' : 'info';
request.log[level]({
duration,
statusCode: reply.statusCode,
err: error
}, 'request completed');
}
}
const server = Fastify({
logController: new CustomLogController()
});上記のコードのように、従来のreply.getResponseTime()の代わりに、v5で推奨されるreply.elapsedTimeプロパティを活用して処理時間を正確に記録します。このようにオブジェクト指向パターンへ転換されたログコントローラーレイヤーにより、可読性が高くメンテナンスの容易なロギングパイプラインを構築できます。
2. TypeBoxによるスキーマベースの検証と完全な型推論
Fastify v5では、従来の不完全な簡易短縮スキーマのサポートが完全に終了し、すべてのルート検証において標準的なJSONスキーマ仕様への準拠が必須となりました。この厳格な検証要件を生産性を落とさずに解決する最も効果的なツールがTypeBoxです。TypeScript開発者は@fastify/type-provider-typeboxを組み合わせることで、一度の定義でランタイム検証とコンパイル時の型推論を同時に達成できます。
ポイントは、Fastifyインスタンス生成時にwithTypeProviderメソッドをコンストラクター関数に対して直接メソッドチェーンとして呼び出す必要があるという点です。すでに生成されたインスタンスに対して単独で呼び出すと、変更された型プロバイダー情報が正しく伝搬されないため注意が必要です。
import Fastify from 'fastify'
import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
import { Type } from '@sinclair/typebox'
// 생성자 호출부에 직접 체이닝하여 인스턴스를 생성합니다.
const fastify = Fastify().withTypeProvider<TypeBoxTypeProvider>()
fastify.post('/users', {
schema: {
body: Type.Object({
name: Type.String(),
email: Type.String({ format: 'email' })
}),
response: {
201: Type.Object({
id: Type.String(),
name: Type.String()
})
}
}
}, async (request, reply) => {
// request.body의 name과 email 타입이 자동으로 완벽하게 추론됩니다.
const { name, email } = request.body
return reply.status(201).send({
id: 'user-123',
name
})
})このパターンを適用すれば、スキーマを定義した瞬間にrequest.bodyおよびレスポンスのデータ構造がTypeScriptの静的型システムと完全に同期されます。追加のランタイムオーバーヘッドはなく、検証済みのAjvコンパイラをそのまま使用するため、型安全性と高性能を両立させる必要があるエンタープライズ環境において必須の標準パターンです。
3. avvioベースのプラグインアーキテクチャとデコレーターパターン
Fastifyはavvioベースの有向非巡回グラフ（DAG）プラグインローダーシステムを使用し、グローバルな状態汚染を徹底的に防ぐ厳格なカプセル化を標準で提供しています。この構造により、一箇所で定義したミドルウェアやフックが意図せず他のルートに影響を与える副作用を根本的に遮断できます。
しかし、データベースクライアントやグローバルキャッシュのように、アプリケーション全体で共有すべき共通リソースは、このカプセル化を解いて上位コンテキストへエクスポートする必要があります。この際、公式ヘルパーパッケージであるfastify-pluginを使ってプラグインをラップしてエクスポートすれば、カプセル化が解除され、デコレーターとして登録したリソースにどこからでもアクセス可能になります。一方、一般的なAPIルート構成では、カプセル化を維持するのがベストプラクティスです。
以下はTypeScript環境でデータベースクライアントをグローバルデコレーターとして登録し、安全に使用するための模範的な実装手法です。
import fp from 'fastify-plugin';
import { FastifyPluginAsync } from 'fastify';
// 가상의 데이터베이스 클라이언트
const dbClient = {
query: async (sql: string) => `Executed: ${sql}`,
};
// TypeScript 모듈 보강을 통한 인스턴스 타입 확장
declare module 'fastify' {
interface FastifyInstance {
db: typeof dbClient;
}
}
const dbPlugin: FastifyPluginAsync = async (fastify) => {
// fastify-plugin 덕분에 부모 컨텍스트로 노출됩니다.
fastify.decorate('db', dbClient);
};
export default fp(dbPlugin);このようにfastify-pluginでプラグインをラップし、モジュール拡張（module augmentation）を追加することで、コンパイラレベルで型安全性を完璧に保証しながら共有リソースを柔軟に管理できます。
結論：プロダクション移行チェックリスト
Fastify v5.10.xに基づいてプロダクションアプリケーションを新規構築、あるいはアップグレードする際に必ず確認すべき重要チェックリストです。
第一に、インフラのランタイム環境を確認する必要があります。Fastify v5はレガシーコードや古いAPIの負債を整理し、最小動作要件をNode.js 20以上に引き上げました。以前のバージョンのNode.jsを使用している場合は、ランタイムの更新が先行して必要です。
第二に、パフォーマンス計測およびルート確認APIの変更点を反映させる必要があります。以前レスポンス遅延時間を取得する際によく使われていたreply.getResponseTime()メソッドが削除されたため、今後はreply.elapsedTimeプロパティを通じて値を直接読み取る必要があります。また、特定のパスの存在を確認していたfastify.hasRoute()メソッドは前方一致のような曖昧な探索をサポートしておらず、完全一致する文字列パスのみをマッチングさせるよう厳格化されました。
第三に、スキーマ検証とロギングパイプラインの構造的転換です。過去に一部許容されていた簡易短縮スキーマはサポートが完全に終了したため、すべてのルート検証は完全な標準JSONスキーマ仕様に準拠して定義する必要があります。ロギングに関しては、従来のトップレベルオプションであるdisableRequestLoggingが非推奨となったため、長期的な運用を見据えてLogControllerクラスを継承してライフサイクルを制御する手法への移行を推奨します。
こうした整理を経て構築されたFastifyは、不要なリクエストオーバーヘッドを減らし、より強力なパフォーマンスと型安全性を提供します。高性能なマイクロサービスインフラを設計したり、大規模なTypeScriptバックエンドを安定的に運用したい組織にとって、Fastify v5.10.xは頼もしい技術基盤となるでしょう。
参考リンク