よくある質問
ライブラリの使用に関するよくある質問への回答を掲載しています。質問をクリックすると回答が表示されます。
1. はじめに
Q: express-cargo プロジェクトとは何ですか？
A: Express.js における繰り返しで面倒なリクエストデータ処理（req.body、req.query など）を、クラスベースのアプローチで自動化するために設計されたミドルウェアです。TypeScript デコレータを活用することで、データバインディングとバリデーションを一箇所で宣言的に処理できます。
Q: インストール時の注意点はありますか？
A: Node.js バージョン 20 以上を推奨します。既存の Express プロジェクトに標準ミドルウェアとして柔軟に統合できるよう設計されています。
Q: TypeScript の設定は必須ですか？
A: はい。デコレータを使用するため、tsconfig.json で以下の 2 つのオプションを true に設定する必要があります：
experimentalDecorators: trueemitDecoratorMetadata: true
また、ランタイムで型情報を読み取るために reflect-metadata パッケージのインストールが必要です。
2. データバインディング & デコレータ
Q: @Body と @Query の違いは何ですか？
A: データの抽出元が異なります：
@Body: HTTP リクエストボディからデータを抽出します。主にPOSTやPUTリクエストで使用されます。@Query: URL クエリ文字列（例:?id=1&name=test）からパラメータを抽出します。主にGETリクエストでのフィルタリングやソートに使用されます。@Params()（または@Uri()）、@Header()、@Session()を使用して、他のリクエストデータもバインドできます。
Q: @Uri() とは何ですか？@Params() と異なりますか？
A: @Uri() は @Params() のエイリアスです。URL パスパラメータ（例: /:id）をバインドする際に、可読性の好みに応じて選択できます。
Q: バインドされたデータはどのように取得しますか？
A: ルーターで bindingCargo(ClassName) ミドルウェアを通過させた後、ハンドラ内で getCargo<ClassName>(req) 関数を呼び出すことでインスタンスを取得できます。
3. バリデーション & トランスフォーメーション
Q: バリデーション失敗時はどのように処理されますか？
A: @Min、@Max、@Length などのデコレータを使用して内部的にバリデーションが実行されます。無効なデータが検出されると、ミドルウェアは自動的にエラーレスポンスを返すか、例外をスローします。
Q: フィールドの値を加工・変換するにはどうすればよいですか？
A: @Transform() デコレータを使用します。例えば、@Transform(v => v.trim()) と記述することで、バインディング前に入力データを希望の形式に変換できます。
Q: 特定のフィールドが存在しない場合にエラーを回避するには？
A: @Optional() デコレータを使用します。値が null または undefined でもフィールドは正常にバインドされ、そのフィールドのバリデーションはスキップされます。
4. フレームワーク互換性
Q: Fastify や NestJS で使用できますか？
A: このライブラリは Express.js 専用ミドルウェアとして設計されています。
- NestJS: NestJS には独自の
ValidationPipeやデコレータがあり、機能が重複する場合があります。Express アダプターを使用すれば技術的には可能ですが、このライブラリの主な目的は純粋な Express 環境での DX 向上です。 - Fastify: 現在、公式にはサポートされていません。
5. トラブルシューティング
Q: クラスインスタンスのデータが undefined を返すのはなぜですか？
A: 以下の 2 点をご確認ください：
express.json()などのボディパースミドルウェアがbindingCargoの前に宣言されていますか？reflect-metadataがアプリケーションのエントリポイントの最上部でインポートされていますか？
Q: 自動型変換は行われますか？
A: はい。クラスフィールドで定義された型（string、number、boolean など）に基づいて、値の自動変換を試みます。例えば、@Query() から取得した文字列 "123" は、フィールドの型が number として定義されている場合、自動的に数値に変換されます。
6. その他
Q: 商用プロジェクトで無料で使用できますか？
A: このライブラリは MIT ライセンスで提供されています。商用目的でも自由に使用、変更、配布することができます。