11 人が閲覧(直近 30 日) TypeScript

DTOとは?意味・Entityとの違いとNestJSのValidationPipe設定【v12実測】

DTOとは?意味・Entityとの違いとNestJSのValidationPipe設定【v12実測】

DTO(Data Transfer Object)は、層やプロセスの間でデータを運ぶためだけのオブジェクトです。この記事では、用語の意味とEntity・DAOとの違いを整理したうえで、TypeScriptでのDTOの書き方、NestJS 12の入力検証(ValidationPipe)と出力の整形を扱います。whitelistとforbidNonWhitelistedの組み合わせなど、挙動の説明はNestJS 12.3.2で実際にリクエストを送って確かめた結果です。

まとめ:DTOの意味とNestJSで押さえる設定

  • DTOは、データの受け渡しに使うオブジェクトです。Martin Fowlerの定義では、プロセス間の呼び出し回数を減らすためにデータをまとめて運ぶことが目的です。
  • Entityは永続化や業務ルールを担い、DTOは外部との入出力の形を決めます。Entityに内部項目が含まれ、出力時に除外していなければ、パスワードハッシュなどがAPIの応答に出るおそれがあります。
  • TypeScriptでは、実行時に検証するならDTOをclassかZodなどのスキーマで書きます。interfaceとtypeはコンパイル後に消えるので、検証には使えません。
  • NestJSのValidationPipeはwhitelist: trueとforbidNonWhitelisted: trueを組み合わせて指定します。forbidNonWhitelistedだけでは、未定義のプロパティがそのまま通ります。
  • レスポンスは、返す項目を列挙したDTOかスキーマで整形します。Entityに@Exclude()を付ける方式は、隠すべき列を追加した際に指定を忘れると、その列が応答に含まれます。

DTOの意味と本来の目的

Fowlerによる定義とリモート呼び出しの削減

DTOという用語は、Martin Fowlerの著書『Patterns of Enterprise Application Architecture』(2002年)で広まりました。同書のパターンカタログのData Transfer Objectの項は、DTOを「An object that carries data between processes in order to reduce the number of method calls.」と定義しています。リモートのインターフェースは1回の呼び出しが高くつくので、呼び出しの回数を減らし、1回で多くのデータを運ぶ必要がある、という説明です。

たとえば、顧客名・住所・電話番号をリモートで1項目ずつ取得すると、通信が3回発生します。これを1つのDTOにまとめれば、通信は1回で済みます。DTO自体は業務ロジックを持たず、シリアライズできる値の入れ物にとどめます。

Web APIでのDTO:リクエストとレスポンスの形

現在のWebアプリでDTOと呼ぶものは、主にHTTPのリクエストボディやレスポンスの形を表すクラスやスキーマです。コントローラーは受け取ったJSONをDTOとして検証してからサービス層へ渡し、レスポンスではEntityをそのまま返さず、公開してよい項目だけを持つDTOに詰め替えます。

Fowlerは2004年10月21日のブログ記事LocalDTOで、同じプロセス内でDTOを使うことに否定的な見解を示しています。粒度の粗いAPIは扱いにくく、ドメイン層からDTOへの詰め替えも手間になるためです。画面のモデルとドメインモデルの形が大きく違う場合は例外としています。WebのAPIはプロセスの境界にあたるので、ここにDTOを置くのは定義どおりの使い方です。一方、同じアプリの内部で層ごとにDTOを増やす設計は、この指摘に当てはまります。

DTOとEntity・DAO・値オブジェクトの違い

用語 役割 ロジック 同一性 NestJSでの例
DTO 入出力データの運搬 持たない なし CreateUserDto
Entity 永続化・業務データ 持つことがある IDで識別 TypeORMの@Entity()クラス
DAO/Repository データストアへのアクセス 取得・保存処理 対象外 Repository<User>
値オブジェクト ドメインの値の表現 不変条件を持つ 値で比較 Emailクラスなど

DAOはデータを取りに行くオブジェクトで、DTOは取ってきたデータを運ぶオブジェクトです。JavaではDAOがDTOを返す組み合わせがよく使われます。JPAやEF CoreでのEntityの書き方はエンティティクラスとは?JPAとEF Coreの書き方・DTOとの違い、TypeScriptでのEntity定義はTypeORMの使い方(エンティティ・リレーション)、値オブジェクトの実装はDDDの実装手順:値オブジェクトから集約までで扱っています。

EntityとDTOを分ける理由は、入力と出力の両方にあります。OWASPのMass Assignment Cheat Sheetは、呼び出し側が編集してよい項目だけを持つDTOのような専用の入力オブジェクトを使い、項目は許可リストで指定し、禁止リストに頼らないよう勧めています。Entityを入力に使い、受け取った値をそのまま保存する実装では、isAdminのような項目をリクエストから書き換えられます。出力に使い、返す項目を絞っていなければ、追加した列もそのまま応答に載ります。

TypeScriptでDTOを書く方法:class・interface・Zodの選び方

JavaScriptとTypeScriptでは、DTOを通常のclassやオブジェクトとして表現し、必要に応じて検証ライブラリを組み合わせます。書き方は次の3通りで、実行時に入力を検証するかどうかで選びます。

書き方 実行時に残るか 検証 向く場面
class+class-validator 残る デコレーターで宣言 NestJSのValidationPipe
interface・type 消える できない 検証済みの値の型付けだけ
Zodなどのスキーマ 残る スキーマで宣言 フロントエンドと共有

NestJS公式ドキュメントのControllersの章は、DTOをinterfaceではなくclassで定義するよう推奨しています。TypeScriptのinterfaceはトランスパイル時に消えるため、実行時に型情報(metatype)を必要とするPipeから参照できません。classはJavaScriptの構文としてコンパイル後も残ります。

同じ理由で、@Body() dtos: CreateUserDto[]のような配列はValidationPipeで要素を検証できません。TypeScriptは配列などのジェネリック型のメタデータを出力しないためです。公式ドキュメントは、配列をプロパティに持つラッパークラスを作るか、ParseArrayPipeを使うよう案内しています。スキーマで書く場合のZodの基本はZodの使い方入門を参照してください。

NestJSで入力用のDTOを定義する手順

class-validatorでDTOを定義する例

検証ルールは、class-validatorのデコレーターでプロパティに付けます。依存パッケージはnpm i class-validator class-transformerで追加します。ネストしたオブジェクトは、@ValidateNested()とclass-transformerの@Type()をセットで指定しないと中身が検証されません。

// src/users/dto/create-user.dto.ts
import { Type } from 'class-transformer';
import {
  IsDefined, IsEmail, IsInt, IsOptional, IsString, Length, Max, Min, ValidateNested,
} from 'class-validator';

export class AddressDto {
  @IsString()
  city: string;
}

export class CreateUserDto {
  @IsString()
  @Length(1, 50)
  name: string;

  @IsEmail()
  email: string;

  @IsOptional()
  @IsInt()
  @Min(0)
  @Max(150)
  age?: number;

  @IsDefined()
  @ValidateNested()
  @Type(() => AddressDto)
  address: AddressDto;
}

@ValidateNested()は、プロパティが存在するときに中身を検証するだけです。@IsDefined()を外すと、addressを丸ごと省いたリクエストが201で通ります。付けるとaddress should not be null or undefinedで400になるので、必須のネスト項目には@IsDefined()を付けます。

tsconfig.jsonではexperimentalDecoratorsとemitDecoratorMetadataを有効にします。この例はstrictPropertyInitialization: falseを前提にしており、有効にする場合はname!: stringのように宣言します。検証時点(2026年11月4日)のnpmの版は、@nestjs/commonと@nestjs/coreが12.3.2(2026年10月27日公開。11月4日に12.3.3が公開)、class-validator 0.15.1、class-transformer 0.5.1です。NestJS 12.0.0のリリースノートのとおり12系はESMパッケージなので、検証ではmodule: "nodenext"を指定し、相対importに.js拡張子を付けています。

PartialType・OmitTypeによる更新用DTOの派生

PATCH用のDTOを手で書き直すと、作成用DTOとルールがずれていきます。@nestjs/mapped-typesの関数を使うと、元のDTOの検証ルールを引き継いだまま派生クラスを作れます。

// src/users/dto/update-user.dto.ts
import { OmitType, PartialType } from '@nestjs/mapped-types';
import { CreateUserDto } from './create-user.dto.js';

// email を除き、残りを全て任意項目にする
export class UpdateUserDto extends PartialType(
  OmitType(CreateUserDto, ['email'] as const),
) {}
関数 生成されるクラス
PartialType(A) Aの全プロパティを任意にする
PickType(A, keys) 指定したプロパティだけを持つ
OmitType(A, keys) 指定したプロパティを除く
IntersectionType(A, B) AとBのプロパティを合わせる

{"name":"Jiro"}だけを送ったPATCHは200で通り、作成用DTOでは必須のaddressが任意に変わっていました。{"name":"","address":{}}は、作成用DTOと同じ@Lengthとaddress.cityのルールで400です。

注意したいのはnullです。{"name":null}は200で通り、ハンドラーにname: nullが届きました。PartialTypeは既定で各プロパティに@IsOptional()相当を付け、nullとundefinedの検証を飛ばすためです。第2引数に{ skipNullProperties: false }を渡すと、同じリクエストが400になりました。ただし、元から@IsOptional()を付けていたageのnullは、この指定でも通ります。

Swaggerを使うアプリでは、同名の関数を@nestjs/swaggerからimportします。公式ドキュメントのValidationの章は、@nestjs/swaggerを使うアプリで@nestjs/mapped-types版を使うと、ドキュメントに記載のない副作用が起こりうると警告しています。OpenAPI自体の書き方はOpenAPIとは?Swaggerとの違いとYAMLの書き方で解説しています。

ValidationPipeのオプション別の挙動(NestJS 12.3.2で実測)

Node.js v26.5.0・TypeScript 7.0.2の環境で、上記のDTOを受け取るエンドポイントにcurlでJSONを送り、ValidationPipeの設定だけを変えて結果を比べました。ValidationPipeはmain.tsでグローバルに登録しています。

// src/main.ts
const app = await NestFactory.create(AppModule);
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,
    forbidNonWhitelisted: true,
    transform: true,
  }),
);
await app.listen(3000);

whitelistとforbidNonWhitelistedの組み合わせ

DTOに定義していないisAdminと、ネスト先に定義していないaddress.zipを含むボディをPOSTした結果です。

設定 結果 ハンドラーが受け取る値
指定なし 201 isAdmin・zipが残る
forbidNonWhitelistedのみ 201 isAdmin・zipが残る
whitelistのみ 201 isAdmin・zipを削除
whitelist+forbidNonWhitelisted 400 ハンドラーは実行されない

公式ドキュメントも、forbidNonWhitelistedはwhitelistに加えてtrueにするオプションだと説明しています。単独で指定すると、エラーにも削除にもならず、isAdminがハンドラーに届く状態が残ります。その値を無制限に保存すると、不正な権限変更につながります。4行目の設定では、エラーメッセージはproperty isAdmin should not existとaddress.property zip should not existの2件でした。

whitelistだけの場合、削除はクライアントに知らされません。更新用DTOから外したemailをPATCHで送ると、200が返り、ハンドラーには空のオブジェクトが届きました。クライアントは更新できたと誤解します。項目を受け付けないことを相手に伝えたいAPIでは、forbidNonWhitelistedを併用して400にします(このときはproperty email should not exist)。

削除されるのは、class-validatorのデコレーターが1つも付いていないプロパティです。class-transformerの@Type()だけでは保持されません。検証ルールが不要な項目でも、DTOに残したいなら@IsOptional()や@Allow()を付けます。

transformとenableImplicitConversionの違い

transform: false(既定)では、ハンドラーが受け取る値はCreateUserDtoのインスタンスではなく、プレーンなオブジェクトでした(instanceofがfalse)。transform: trueにすると、DTOクラスのインスタンスになります。

文字列の"20"を送ったageは、transform: trueだけでは数値に変換されず、age must be an integer numberで400になりました。DTO全体で宣言どおりの型に変換するには、transformOptions: { enableImplicitConversion: true }を追加します。この設定でageは20になりました。

暗黙変換は、型違いの入力も検証に通します。同じ設定で{"name":123,"email":"[email protected]","address":{"city":456}}を送ると、"123"と"456"という文字列に変換されて201で通りました。型違いを400にしたい項目があるなら、全体の暗黙変換は使わず、変換が必要な項目だけに@Type()を指定します。また、whitelistを外して暗黙変換だけを有効にすると、isAdmin: trueが残ったまま通りました。

クエリ文字列の値は文字列として届きます。ページ番号は、次のように@Type(() => Number)で数値に変換します。

// src/users/dto/list-users.query.ts
import { Type } from 'class-transformer';
import { IsInt, IsOptional, Min } from 'class-validator';

export class ListUsersQuery {
  @IsOptional()
  @Type(() => Number)
  @IsInt()
  @Min(1)
  page?: number = 1;
}

GET /users?page=2のtypeof query.pageは、オプションなしのValidationPipeでは"string"、whitelist: trueを指定するとtransform: falseのままでも"number"でした。NestJSのvalidation.pipe.jsは、validatorOptionsに既定以外のキーがあると、変換後のオブジェクトをプレーンなオブジェクトに戻して返すためです。transformの有無だけで、届く値の型を判断しないでください。

ValidationPipeのエラー応答:ステータス・件数・形式

オプション 既定 実測での変化
errorHttpStatusCode 400 422を指定するとUnprocessable Entity
stopAtFirstError false 1プロパティにつき最初の1件だけ返る
errorFormat ‘list’ ‘grouped’でプロパティ名をキーにした形
disableErrorMessages false messageが"Bad Request"だけになる

stopAtFirstError: trueでは、"20"を送ったageのエラーが3件からage must not be greater than 150の1件に減りました。errorFormat: 'grouped'では、messageが{"address.city":["city must be a string"]}のようなオブジェクトになり、キーがパスを持つぶんメッセージから親のaddress.が外れます。フロントエンドで入力欄ごとにエラーを出すなら'grouped'が扱いやすい形です。本番でDTOの項目名を外部に見せたくない場合はdisableErrorMessages: trueを指定します。400の発生源を切り分ける手順はHTTP error 400(Bad Request)とは?発生源の切り分けにまとめています。

レスポンスのDTOで内部項目を返さない方法

入力の検証に比べ、出力の整形は見落とされがちです。passwordHashとisAdminを含むDBの行を想定し、グローバルにClassSerializerInterceptorを登録した状態で、返し方ごとの応答を比べました。

ハンドラーが返すもの passwordHash isAdmin・email
DBの行(プレーンなオブジェクト) 返る 返る
@Exclude()付きEntityのインスタンス 返らない 返る
plainToInstance(Dto, row) 返る 返る
同上+excludeExtraneousValues: true 返らない 返らない
@SerializeOptions({ type: Dto, excludeExtraneousValues: true }) 返らない 返らない

1行目は、インターセプターを登録していても素通りします。公式ドキュメントのSerializationの章も、ハンドラーはクラスのインスタンスを返す必要があり、プレーンなオブジェクトは正しくシリアライズされないと警告しています。2行目の@Exclude()は禁止リストなので、隠したい列を追加した際に指定を忘れると、その列が応答に含まれます。3行目は、@Expose()を付けたDTOに詰め替えても、excludeExtraneousValuesを指定しなければ全項目が残りました。

返す項目を列挙する許可リストにするには、4行目か5行目の書き方にします。ハンドラーごとに詰め替えを書かずに済むのは@SerializeOptions()のtypeです。

// src/users/dto/user-response.dto.ts
import { Expose } from 'class-transformer';

export class UserResponseDto {
  @Expose() id: number;
  @Expose() name: string;
}

// src/users/users.controller.ts
@Get(':id')
@SerializeOptions({ type: UserResponseDto, excludeExtraneousValues: true })
findOne(@Param('id', ParseIntPipe) id: number): Promise<UserResponseDto> {
  return this.usersService.findOne(id); // DBの行をそのまま返してもid・nameだけが出る
}

// src/main.ts
app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));

Zodのスキーマで出力を決める場合は、NestJS 12で追加されたStandardSchemaSerializerInterceptorを使います。@SerializeOptions({ schema: userResponseSchema })でz.object({ id: z.number(), name: z.string() })を指定すると、passwordHashを含む行を返しても応答は{"id":1,"name":"Taro"}でした。z.object()は宣言していないキーを取り除くので、スキーマがそのまま許可リストになります。

ZodでDTOを定義する場合(StandardSchemaValidationPipe)

NestJS 12の@nestjs/commonにはStandardSchemaValidationPipeがあります。Zod、Valibot、ArkTypeなど、Standard Schemaに準拠したライブラリのスキーマで入力を検証するPipeです。

import { Body, Controller, Post, StandardSchemaValidationPipe } from '@nestjs/common';
import { z } from 'zod';

const createUserSchema = z.object({
  name: z.string().min(1),
  age: z.coerce.number().int().min(0),
  // 注意: null・空文字列・falseも0に変換される
});
type CreateUserDto = z.infer<typeof createUserSchema>;

@Controller('users')
export class UsersController {
  @Post()
  create(@Body({ schema: createUserSchema }) body: CreateUserDto) {
    return body;
  }
}

// main.ts
app.useGlobalPipes(new StandardSchemaValidationPipe());

zod 4.6.7で{"name":"Taro","age":"20","isAdmin":true}を送ると、{"name":"Taro","age":20}が返りました。z.object()は未定義のキーを既定で取り除くので、whitelistに相当する設定は要りません。{"name":"Taro","age":null}はage: 0になって201で通ったので、z.coerceはnullを拒否したい項目には使わないでください。型はz.inferで得られ、スキーマと型の二重管理が起きません。classではないのでPartialTypeは使えず、部分更新にはcreateUserSchema.partial()を使います。

公式ドキュメントによると、2つのPipeは同時に登録できます。ValidationPipeはclassで型付けした引数だけを、StandardSchemaValidationPipeはschemaを宣言した引数だけを検証するためです。app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true }), new StandardSchemaValidationPipe())と並べた状態で、class版のDTOはisAdminで400、Zod版のルートは余分なキーを落として201になり、それぞれの規則で動きました。

既存のclass-validatorのDTOが多いプロジェクトは、ValidationPipeを残したまま、フロントエンドとスキーマを共有したいルートから順にZodへ移すと、変更対象を限定できます。ただし、移行するルートごとに余分なキーの拒否・削除、型変換、エラー応答の互換性を確認します。新規のプロジェクトで入力と出力の両方をスキーマで書くなら、最初からStandardSchemaValidationPipeとStandardSchemaSerializerInterceptorで揃えれば、DTOのclassとデコレーターは不要になります。NestJSでのAPI設計や既存システムとの連携を外部に相談したい場合は、API開発・システム連携の支援も用意しています。

よくある質問

DTOは何の略ですか?

Data Transfer Objectの略で、日本語では「データ転送オブジェクト」と訳されます。層やプロセスの間でデータをまとめて運ぶためのオブジェクトで、業務ロジックは持たせません。

DTOとDAOの違いは何ですか?

DAO(Data Access Object)はデータベースなどへのアクセス処理をまとめたオブジェクトで、DTOはそこで取得したデータを運ぶ入れ物です。DAOが検索結果をDTOに詰めて返す、という組み合わせで使われます。

forbidNonWhitelistedを設定しても400になりません。なぜですか?

まず、whitelist: trueを同時に指定しているか確認してください。NestJS 12.3.2での検証では、forbidNonWhitelisted: trueだけでは、未定義のプロパティを含むリクエストがそのまま201で通りました。併用していても400にならない場合は、そのルートにValidationPipeが登録されているか、引数の型がinterfaceではなくclassかを確認します。

EntityをそのままDTOとして使ってもよいですか?

おすすめしません。入力に兼用するとisAdminのような項目をリクエストから書き換えられ、出力に兼用すると列を足しただけでpasswordHashのような内部項目が応答に載ります。入力用と出力用のDTOを分け、どちらも項目を列挙する許可リストにしてください。

JavaではDTOをどう書きますか?

JEP 395で正式機能になったJava 16以降では、DTOをrecordで定義できます。アクセサー、equals、hashCodeが自動で生成され、フィールドはfinalで再代入できないため、値を運ぶDTOに向いています。ただし、参照先のListなどの中身まで不変になるわけではありません。書き方はJavaのレコードクラス(record)とは?で解説しています。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2024.08.22 テックブログ Bokehとは?Pythonでの使い方と2軸グラフの作り方【3.10.1対応】
  2. 2026.11.09 テックブログ teket不正アクセス:ログインできない理由と再開見通し、入場・退会・偽メールの確認【11月16日時点】
  3. 2026.11.12 コラム 年末調整2026の変更点|基礎控除104万円・扶養62万円と給与システムの改修項目
  4. 2026.08.04 テックブログ SCADAとは?スキャダの仕組みとPLC・DCS・MESとの役割分担を実装目線で解説
  5. 2026.11.20 テックブログ Gemini 4 Neonとは?HydrogenとCarbonとの違い・料金・3.1 Pro Previewからの移行を実装目線で解説【2026年11月】

RELATED POSTS 関連記事

目次