zod

Zod (Typescript Schema Validator)

TypeScript 환경에서 객체 구조와 데이터 유효성을 검증하는 라이브러리

불확실한 데이터를 런타임에서 검증하여 타입 불일치로 인한 오류를 사전에 방지함

• Schema(스키마): 객체의 설계도

• 런타임 검증: 타입스크립트는 컴파일 타임에서 타입을 체크하지만, 런타임에서 들어오는 외부 데이터까지 안전하게 검증 가능

• 외부 JSON, API 응답, 사용자 입력 등 불확실한 데이터를 안전하게 다루는 데 필수

Zod 메서드 핵심 분류

1. 객체/타입 정의

메서드	목적	예시
z.object({...})	객체 구조 정의	z.object({ name: z.string() })
z.string(), z.number(), z.boolean()	기본 타입 정의	z.string().min(3)
z.array(schema)	배열 검증	z.array(z.string())
z.enum([...])	리터럴 값 집합 검증	z.enum(['A','B'])
z.literal(value)	특정 값만 허용	z.literal('admin')

---

2. 값 검증 / 조건부 검증

메서드	목적	예시
.min(), .max()	최소/최대 길이, 값 검증	z.string().min(3)
.email(), .url()	포맷 검증	z.string().email()
.refine(predicate, { message })	커스텀 조건 검증	z.string().refine(val => val.includes('@'), { message: '이메일 아님' })
.optional()	선택적 필드	z.string().optional()
.nullable()	null 허용	z.string().nullable()

---

3. 값 변환 / 가공

메서드	목적	예시
.transform(fn)	검증된 값을 다른 형태로 변환 (sync/async)	z.string().transform(val => Number(val))
.coerce.*()	원시 타입 강제 변환	z.coerce.number() (문자열 → 숫자)
.catch(defaultValue)	실패 시 기본값으로 대체	z.number().min(0).catch(0)

---

4. 파싱 / 안전한 처리

메서드	목적	예시
.parse(value)	값 검증 + 변환, 실패 시 예외 throw	schema.parse(input)
.safeParse(value)	값 검증 + 변환, 실패 시 { success, error } 반환	schema.safeParse(input)
.parseAsync(value)	async transform 포함 시 사용	await schema.parseAsync(input)
.safeParseAsync(value)	async transform + 안전 처리	await schema.safeParseAsync(input)

---

5. 타입 추론

메서드	목적	예시
z.infer<typeof schema>	스키마 기반 TypeScript 타입 추론	type User = z.infer<typeof userSchema>

Error

ZodError 구조를 통해 어떤 필드가 왜 실패했는지 확인 가능

• .errors : 각 필드별 에러 정보

• .message : 기본 에러 메시지

const schema = z.string().min(5, { message: "최소 5글자 필요" });
const result = schema.safeParse("abc");
if (!result.success) console.log(result.error.errors);

ZodError 데이터 구조

{
  issues: [
    {
      code: 'invalid_type',    // 에러 코드. Zod 내부에서 정의한 에러 유형
      expected: 'string',      // 예상 타입 또는 값
      received: 'undfeind',    // 실제 들어온 값
      path: [Array],           // 문제가 발생한 필드 경로. 최상위 필드는 []로 표시
      message: 'Not a string!' // 커스텀/기본 에러 메시지
    }
  ],
  // 런타임에 에러를 추가할 때 사용되는 메서드
  addIssue: [Function (anonymous)], 
  addIssues: [Function (anonymous)],
  // 내부적으로 issues와 동일
  errors: [
    {
      code: 'invalid_type',
      expected: 'string',
      received: 'undefined',
      path: [Array],
      message: 'Not a string!'
    }
  ]
}

에러 관련 메서드

• .refine()

  • 커스텀 조건 검증을 추가할 때 사용

  • 조건을 만족하지 않으면 지정한 메시지로 실패 처리

• .catch()

  • 검증 실패 시 기본값을 반환하도록 처리

  • 예외를 던지지 않고 안전하게 기본값으로 대체 가능

• .message()

  • 기본 제공되는 에러 메시지를 커스텀할 때 사용

  • 대부분 .min(), .max(), .email() 등 메서드에 옵션으로 전달

transform

검증한 값(validated value)을 원하는 형태로 변환할 때 사용

• 외부 데이터가 검증은 되지만, 앱 내부에서 다른 형태로 사용해야할 때

• Ex: 문자열 → 숫자, 날짜 문자열 → Date 객체, API 응답 포맷 변환 등

• validate → 변환 → 사용 순서를 한 줄로 줄일 수 있음

• async 비동기 함수도 지원함

  • async transform을 쓸 경우, parseAsync() 또는 safeParseAsync()를 사용해야 함

const dateSchema = z.string().transform(str => new Date(str));

const date = dateSchema.parse("2025-08-17T00:00:00Z");
console.log(date instanceof Date); // true

국제화 (i18n)

Zod 에러 메시지를 국제화할 수 있음

• zod-i18n-map

• lib/i18n-zod.ts에 설정을 두고, 프로젝트 전역에서 import { z } from '@/lib/i18n-zod'로 사용

• 사용자 요청 헤더(Accept-Language)에 따라 동적으로 언어를 바꿔서 사용 가능

import i18next from 'i18next';
import { z } from 'zod';
import { zodI18nMap } from 'zod-i18n-map'
// import your language translation files
import translation from 'zod-i18n-map/locales/ko/zod.json';

i18next.init({
  lng: 'ko',
  resources: {
    ko: { zod: translation },
  },
});
z.setErrorMap(zodI18nMap);

export { z };

ETC

• API 응답 검증

  • 외부 API에서 데이터를 받을 때 항상 safeParse 사용

  • 예외로 앱이 터지는 것을 방지 가능

• TypeScript 타입과 연계

  • z.infer<typeof schema>로 타입 추론 → 타입 정의 중복 방지

• Nested Object 검증

  • 객체 안 객체 구조도 .object 안에 .object를 중첩해 사용 가능

• Optional & Default

  • optional()과 default()를 조합하여 누락 필드 처리 가능

• Coercion

  • 숫자가 문자열로 오는 API 응답 시 .coerce.number() 사용 가능

• Async 검증

  • 비동기 검증 로직 필요 시 z.preprocess + async 가능