本文へスキップ

欠落フィールドの処理

フィールドがリクエストに存在しない場合（値が undefined または null）、Express-Cargo は何をすべきかを知る必要があります。この動作は 2 つのデコレータで制御します。

  • @Default(value) — フォールバック値を割り当てます。
  • @Optional() — 「required」エラーを発生させずに、フィールドを空のままにできます。

どちらもフィールドが欠落したときの動作という同じことを決めるため、相互に排他的です。両方を同じフィールドに適用すると、スキーマエラーが発生します。

フィールドにどちらのデコレータもなく値が欠落している場合、バインドは <field> is required バリデーションエラーで失敗します。

@Default(value: T)​

@Default デコレータは、リクエストがフィールドを提供しない場合にクラスプロパティにデフォルト値を割り当てます。

  • value: フィールドがリクエストに存在しない場合に割り当てるデフォルト値。
class Request {
    @Body()
    @Default(1)
    price!: number;
}

デフォルト値が適用されるタイミング​

デフォルト値は、受信した値が undefined または null の場合にのみ適用されます（つまり、フィールドがリクエストに存在しない場合）。リクエストから来たその他の値はそのまま保持されます。

つまり、0、''、false のような falsy な値は実際の入力として扱われ、デフォルト値をトリガーしません。

class Request {
    @Body()
    @Default(10)
    quantity!: number
}
受信した quantityバインドされる値
欠落 / undefined10（デフォルト適用）
null10（デフォルト適用）
00（保持）
55（保持）

@Optional()​

@Optional デコレータはフィールドをオプションとしてマークし、「required」エラーを発生させずに省略または undefined/null に設定できるようにします。フィールドが欠落している場合は null のままになり、そのフィールドのバリデーションルールはスキップされます。

class Request {
    @Body()
    @Min(0)
    @Optional()
    discount?: number
}

ここでは、欠落した discount は null にバインドされ、@Min(0) ルールはスキップされます。discount が提供された場合は、通常どおり検証されます。

@Default と @Optional の選択​

フィールド欠落フィールド提供
@Default(value)value にバインド値を保持して検証
@Optional()null にバインド値を保持して検証
どちらもなし<field> is required エラー値を保持して検証

フィールドごとに1 つの戦略を選んでください。

class Request {
    // ❌ 無効: フィールドは 1 つの欠落値戦略のみ使用できます
    @Body()
    @Default(1)
    @Optional()
    price!: number
}