Zod 스키마 검증 실전 가이드 — TypeScript 런타임 타입 안전성

Zod 기본 스키마 정의 — 핵심 타입 총정리

Zod 기본 타입 정의 예시
import { z } from 'zod';

// 원시 타입
const nameSchema = z.string().min(1, '이름을 입력해주세요').max(50);
const ageSchema = z.number().int().min(0).max(150);
const activeSchema = z.boolean();

// 검증
const result = nameSchema.safeParse('');
if (!result.success) {
  console.log(result.error.issues); // [{code: 'too_small', message: '이름을 입력해주세요', ...}]
}

// parse vs safeParse
// parse: 실패 시 ZodError throw
// safeParse: 항상 {success, data} 또는 {success, error} 반환
const parsed = nameSchema.parse('홍길동'); // => '홍길동'
const safe = ageSchema.safeParse('스물다섯'); // => { success: false, error: ... }

z.infer — 스키마에서 TypeScript 타입 자동 추론

z.infer로 타입 자동 생성
import { z } from 'zod';

const UserSchema = z.object({
  id: z.number().int().positive(),
  name: z.string().min(1).max(100),
  email: z.string().email(),
  role: z.enum(['admin', 'user', 'guest']),
  createdAt: z.string().datetime(),
  profile: z.object({
    bio: z.string().optional(),
    avatarUrl: z.string().url().optional(),
  }).optional(),
});

// 자동 타입 추론 — interface를 따로 작성할 필요 없음
type User = z.infer<typeof UserSchema>;

// User 타입:
// {
//   id: number;
//   name: string;
//   email: string;
//   role: "admin" | "user" | "guest";
//   createdAt: string;
//   profile?: { bio?: string; avatarUrl?: string; } | undefined;
// }

function processUser(user: User) {
  console.log(user.role); // 타입 완전 지원
}

폼 검증 실전 — React Hook Form + Zod

React Hook Form + zodResolver 연동
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const signupSchema = z.object({
  username: z.string().min(3, '3자 이상 입력해주세요').max(20),
  email: z.string().email('올바른 이메일 형식이 아닙니다'),
  password: z.string().min(8, '비밀번호는 8자 이상이어야 합니다'),
  confirmPassword: z.string(),
}).refine((data) => data.password === data.confirmPassword, {
  message: '비밀번호가 일치하지 않습니다',
  path: ['confirmPassword'],
});

type SignupFormData = z.infer<typeof signupSchema>;

export function SignupForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<SignupFormData>({
    resolver: zodResolver(signupSchema),
  });

  const onSubmit = (data: SignupFormData) => {
    // data는 이미 검증된 상태 — 타입도 완전히 추론됨
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('email')} placeholder="이메일" />
      {errors.email && <p>{errors.email.message}</p>}
      <input {...register('password')} type="password" />
      {errors.password && <p>{errors.password.message}</p>}
      <button type="submit">가입</button>
    </form>
  );
}

API 응답 검증 — 런타임 타입 안전성 확보

fetch API 응답 Zod 검증
import { z } from 'zod';

const PostSchema = z.object({
  id: z.number(),
  title: z.string(),
  body: z.string(),
  userId: z.number(),
  tags: z.array(z.string()).optional(),
});

const PostListSchema = z.array(PostSchema);

type Post = z.infer<typeof PostSchema>;

async function fetchPosts(): Promise<Post[]> {
  const res = await fetch('https://jsonplaceholder.typicode.com/posts');
  const json = await res.json();

  // 런타임 검증 — 구조가 맞지 않으면 즉시 에러
  const result = PostListSchema.safeParse(json);

  if (!result.success) {
    // result.error.format()으로 필드별 에러 확인
    console.error('API 응답 형식 오류:', result.error.format());
    throw new Error('API response validation failed');
  }

  return result.data; // 완전히 타입 안전한 Post[]
}

에러 메시지 커스터마이징과 한국어 처리

에러 메시지 커스터마이징
import { z } from 'zod';

// 방법 1: 각 메서드에 직접 메시지 설정
const productSchema = z.object({
  name: z.string({
    required_error: '상품명은 필수입니다',
    invalid_type_error: '상품명은 문자열이어야 합니다',
  }).min(1, '상품명을 입력해주세요'),
  price: z.number({
    required_error: '가격은 필수입니다',
  }).positive('가격은 0보다 커야 합니다'),
  stock: z.number().int().nonnegative('재고는 음수일 수 없습니다'),
});

// 에러 구조 확인
const result = productSchema.safeParse({ name: '', price: -1000, stock: -5 });
if (!result.success) {
  // flatten() — 필드별 에러 배열
  const flat = result.error.flatten();
  console.log(flat.fieldErrors);
  // { name: ['상품명을 입력해주세요'], price: ['가격은 0보다 커야 합니다'], stock: ['재고는 음수일 수 없습니다'] }
}

Next.js 서버 액션에서 Zod 검증
'use server';
import { z } from 'zod';

const ContactSchema = z.object({
  name: z.string().min(1, '이름을 입력해주세요'),
  email: z.string().email('올바른 이메일 주소를 입력해주세요'),
  message: z.string().min(10, '메시지는 10자 이상 입력해주세요').max(1000),
});

export async function submitContact(formData: FormData) {
  const raw = {
    name: formData.get('name'),
    email: formData.get('email'),
    message: formData.get('message'),
  };

  const result = ContactSchema.safeParse(raw);

  if (!result.success) {
    return {
      success: false,
      errors: result.error.flatten().fieldErrors,
    };
  }

  // result.data는 타입 안전
  await saveContact(result.data);
  return { success: true };
}