TypeScript Academy · レッスン

防御的パースとエラーエンベロープ

堅牢なリクエスト処理を構築します。防御的にパースし、すべての失敗を簡潔なJSONエラーエンベロープに変換して、内部情報の漏えいを防ぎます。

レッスン 2/28 ステップ

「防御的パースとエラーエンベロープ」はCoddyKit上の無料TypeScript Academyレッスンです。これはレッスン2/2です。下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。これはTypeScript Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 TypeScript Academyコースには全2レッスンが含まれています。

導入

目標：防御的にパースし、予測可能なJSONエラーエンベロープを常に返します。検証を境界の近くに置き、失敗の形式を統一し、レスポンスを最小限に保ちながらログには十分な情報を残します。

信頼できないすべての入力にsafeParseを使用
一貫した{ error, code, details? }
4xxと5xxの使い分け

エンベロープのマッパー

小さく再利用可能なErrorEnvelopeを定義します。unknown型のエラーを、スタックトレースを公開せずに変換します。

export type ErrorEnvelope = { error: string; code?: string; details?: unknown }

export function toEnvelope(u: unknown): ErrorEnvelope {
  if (u instanceof Error) return { error: u.message }
  if (typeof u === "string") return { error: u }
  try { return { error: JSON.stringify(u) } } catch { return { error: "Unknown error" } }
}

validate ヘルパー

スキーマを、判別可能な結果を返すvalidateヘルパーでラップします。ハンドラーを小さく一貫した状態に保てます。

import { z, type ZodTypeAny } from "zod"

export function validate<T extends ZodTypeAny>(schema: T, value: unknown) {
  const r = schema.safeParse(value)
  if (!r.success) {
    return { ok: false as const, issues: r.error.format() }
  }
  return { ok: true as const, data: r.data as z.infer<T> }
}

防御的なハンドラー

早い段階で検証し、問題の詳細を含む400を返します。予期しない失敗はerror middlewareに伝播させ、エンベロープを含む500として処理します。

import type { Request, Response, NextFunction } from "express"
import { z } from "zod"
import { validate } from "./validate"
import { toEnvelope, type ErrorEnvelope } from "./envelope"

const bodySchema = z.object({ email: z.string().email(), newsletter: z.boolean().default(false) })

export function subscribe(req: Request, res: Response<{ ok: true } | ErrorEnvelope>, next: NextFunction) {
  const r = validate(bodySchema, req.body)
  if (!r.ok) return res.status(400).json({ error: "Invalid body", details: r.issues })
  try {
    // pretend to persist
    return res.status(201).json({ ok: true })
  } catch (e) {
    return next(e)
  }
}

export function errorMiddleware(err: unknown, _req: Request, res: Response<ErrorEnvelope>, _next: NextFunction) {
  const env = toEnvelope(err)
  res.status(500).json(env)
}

一般的なエンベロープ

一般的な結果用に小さなヘルパーを用意します。404／401と安定したcode文字列を使用することで、クライアントが確実に分岐できます。

export function notFound(resource: string): { status: 404; body: { error: string; code: string } } {
  return { status: 404, body: { error: `${resource} not found`, code: "NOT_FOUND" } }
}

export function unauthorized(): { status: 401; body: { error: string; code: string } } {
  return { status: 401, body: { error: "unauthorized", code: "UNAUTHORIZED" } }
}

ログとレスポンス

ログとレスポンスのバランス：サーバー側ではエラー全体（スタック、リクエストID、ユーザーID）をログに記録しますが、クライアントには最小限のエンベロープを返します。PIIについては、レート制限と秘匿化を検討します。

エンベロープの実践チェック

クイックチェック：検証エラーはどのように返すべきですか？

対話的なレッスンで答える

まとめ

まとめ：safeParseで入力を検証し、失敗を簡潔なエンベロープに変換して、詳細なログと最小限のクライアントレスポンスを分離します。

無料で開始

AI チューターと学ぶ TypeScript — 無料

ブラウザでリアルコードを書いて実行し、24/7 の AI チューターから瞬時にサポートを受け、ウェブまたはアプリで続きから学習できます。

コース: 101
レッスン: 352

無料で学習を始めるコース全体を表示

よくある質問

「防御的パースとエラーエンベロープ」レッスンは無料ですか？

はい。「防御的パースとエラーエンベロープ」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、TypeScript Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 TypeScript Academyコースには全2レッスンが含まれています。

「防御的パースとエラーエンベロープ」で何を学びますか？

堅牢なリクエスト処理を構築します。防御的にパースし、すべての失敗を簡潔なJSONエラーエンベロープに変換して、内部情報の漏えいを防ぎます。ブラウザで直接実行するハンズオンコードでTypeScript Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

TypeScript Academyを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのTypeScript Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。これはレッスン2/2です。

「防御的パースとエラーエンベロープ」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このTypeScript Academyレッスンでコードを書いて実行できますか？

はい。すべてのTypeScript Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

zod/valibotスキーマと推論
防御的パースとエラーエンベロープ

← TypeScript Academyに戻る