2026년 Zod로 TypeScript 런타임 타입 검증 완벽 가이드

한 프로젝트에서 백엔드 API가 업데이트되면서 응답 구조가 살짝 바뀌었는데, 프론트엔드는 전혀 모르고 기존 타입 정의를 그대로 사용했어요. TypeScript는 당연히 에러를 안 잡았고요. 결과는? 프로덕션에서 수천 명의 사용자가 빈 화면만 보는 대참사였죠. 런타임 검증이 있었다면 즉시 에러를 감지하고 폴백 처리를 할 수 있었을 텐데 말이에요.

# npm 사용하는 경우
npm install zod

# yarn 사용하는 경우
yarn add zod

# pnpm 사용하는 경우 (2026년 점점 많이 쓰여요!)
pnpm add zod

# bun 사용하는 경우
bun add zod

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020"],
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "strictNullChecks": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

// 방법 1: 전체 임포트 (가장 많이 씀!)
import { z } from "zod";

// 방법 2: 특정 메서드만 임포트
import { z, ZodError } from "zod";

// 방법 3: 네임스페이스 임포트 (레거시 코드에서 가끔 보여요)
import * as zod from "zod";

CommonJS 환경(require)에서는 const { z } = require("zod"); 형태로 사용할 수 있지만, 2026년 현재는 ESM 사용을 강력히 권장해요. 타입 추론이 더 정확하고 에러 메시지도 명확하거든요!

import { z } from 'zod';

// 문자열 스키마
const nameSchema = z.string();

// 숫자 스키마
const ageSchema = z.number();

// 불리언 스키마
const isActiveSchema = z.boolean();

// 날짜 스키마
const dateSchema = z.date();

// 실제 검증해보기
const result = nameSchema.parse("홍길동"); // 통과!
console.log(result); // "홍길동"

// 잘못된 타입으로 검증하면?
try {
  nameSchema.parse(123); // 에러 발생!
} catch (error) {
  console.error("타입이 맞지 않아요!");
}

const userProfileSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  age: z.number().min(18).max(120),
  isVerified: z.boolean(),
  createdAt: z.date()
});

// 타입스크립트 타입도 자동으로 추출!
type UserProfile = z.infer;

// 실제 사용
const userData = {
  id: 1,
  name: "김개발",
  email: "dev@example.com",
  age: 28,
  isVerified: true,
  createdAt: new Date()
};

const validatedUser = userProfileSchema.parse(userData);
console.log(validatedUser); // 검증 통과!

// 주소 스키마
const addressSchema = z.object({
  street: z.string(),
  city: z.string(),
  zipCode: z.string().regex(/^\d{5}$/)
});

// 취미 스키마
const hobbySchema = z.object({
  name: z.string(),
  level: z.enum(['beginner', 'intermediate', 'advanced'])
});

// 사용자 전체 스키마
const fullUserSchema = z.object({
  profile: userProfileSchema,
  addresses: z.array(addressSchema), // 배열로 감싸기
  hobbies: z.array(hobbySchema).optional(), // 선택사항
  metadata: z.record(z.string()) // 키-값 쌍
});

// 실제 데이터
const complexUser = {
  profile: {
    id: 1,
    name: "이개발",
    email: "lee@example.com",
    age: 30,
    isVerified: true,
    createdAt: new Date()
  },
  addresses: [
    { street: "테헤란로", city: "서울", zipCode: "06234" }
  ],
  hobbies: [
    { name: "코딩", level: "advanced" }
  ],
  metadata: {
    lastLogin: "2026-05-21",
    deviceType: "mobile"
  }
};

const validated = fullUserSchema.parse(complexUser);

// 유니온 타입: "이것 또는 저것"
const paymentSchema = z.union([
  z.object({
    method: z.literal('card'),
    cardNumber: z.string(),
    cvv: z.string()
  }),
  z.object({
    method: z.literal('bank'),
    accountNumber: z.string(),
    bankCode: z.string()
  })
]);

// 인터섹션 타입: "이것과 저것 모두"
const baseUserSchema = z.object({
  id: z.number(),
  name: z.string()
});

const timestampSchema = z.object({
  createdAt: z.date(),
  updatedAt: z.date()
});

const userWithTimestampSchema = z.intersection(
  baseUserSchema,
  timestampSchema
);

// 또는 더 간단하게 and() 메서드 사용
const simpleIntersection = baseUserSchema.and(timestampSchema);

• 문자열 검증: .email(), .url(), .uuid(), .regex(), .min(), .max(), .length()
• 숫자 검증: .min(), .max(), .int(), .positive(), .negative(), .multipleOf()
• 배열 검증: .min(), .max(), .length(), .nonempty()
• 날짜 검증: .min(), .max()
• 공통: .optional(), .nullable(), .default(), .transform()

// 회원가입 폼 스키마
const signupFormSchema = z.object({
  // 이메일: 필수, 이메일 형식
  email: z.string()
    .email("올바른 이메일을 입력해주세요"),
  
  // 비밀번호: 최소 8자, 최대 20자, 정규식
  password: z.string()
    .min(8, "비밀번호는 최소 8자 이상이어야 해요")
    .max(20, "비밀번호는 20자를 초과할 수 없어요")
    .regex(
      /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/,
      "영문 대소문자와 숫자를 포함해야 해요"
    ),
  
  // 닉네임: 3-15자, 한글/영문/숫자만
  nickname: z.string()
    .min(3)
    .max(15)
    .regex(/^[가-힣a-zA-Z0-9]+$/, "특수문자는 사용할 수 없어요"),
  
  // 나이: 정수, 18세 이상
  age: z.number()
    .int("정수만 입력 가능해요")
    .min(18, "18세 이상만 가입할 수 있어요")
    .max(120, "올바른 나이를 입력해주세요"),
  
  // 전화번호: 선택사항, 형식 검증
  phone: z.string()
    .regex(/^010-\d{4}-\d{4}$/, "010-0000-0000 형식으로 입력해주세요")
    .optional(),
  
  // 마케팅 동의: 기본값 false
  marketingAgreed: z.boolean().default(false)
});

// 실제 검증
const formData = {
  email: "user@example.com",
  password: "Pass1234",
  nickname: "코딩왕",
  age: 25,
  phone: "010-1234-5678"
};

const validated = signupFormSchema.parse(formData);

// 리터럴 타입: 정확히 하나의 값만
const adminRoleSchema = z.literal('admin');

// Enum: 여러 값 중 하나
const userRoleSchema = z.enum(['admin', 'user', 'guest']);

// 숫자 리터럴도 가능
const httpOkSchema = z.literal(200);

// 실전 예시: 주문 상태 관리
const orderStatusSchema = z.enum([
  'pending',
  'confirmed',
  'shipping',
  'delivered',
  'cancelled'
]);

const orderSchema = z.object({
  orderId: z.string().uuid(),
  status: orderStatusSchema,
  priority: z.enum(['low', 'medium', 'high']).default('medium'),
  items: z.array(z.object({
    productId: z.number(),
    quantity: z.number().positive()
  }))
});

// 타입 추출도 물론 가능!
type OrderStatus = z.infer;
// type OrderStatus = 'pending' | 'confirmed' | 'shipping' | 'delivered' | 'cancelled'

저는 보통 API 응답 상태나 설정 값 같은 걸 검증할 때 enum을 많이 써요. 특히 백엔드에서 정해진 값만 내려와야 하는 경우에 완전 유용하더라고요. 혹시라도 예상 못 한 값이 오면 바로 에러가 나니까 빠르게 잡을 수 있어요.

// 문자열을 숫자로 변환
const stringToNumberSchema = z.string()
  .transform((val) => parseInt(val, 10))
  .pipe(z.number().positive());

// 날짜 문자열을 Date 객체로
const dateStringSchema = z.string()
  .transform((str) => new Date(str))
  .pipe(z.date());

// 실전: 쿼리 파라미터 파싱
const queryParamsSchema = z.object({
  page: z.string()
    .default('1')
    .transform(Number),
  
  limit: z.string()
    .default('10')
    .transform(Number)
    .pipe(z.number().min(1).max(100)),
  
  search: z.string()
    .transform(val => val.trim().toLowerCase())
    .optional(),
  
  sortBy: z.enum(['name', 'date', 'price'])
    .default('date')
});

// URL: /api/products?page=2&limit=20&search=  노트북  &sortBy=price
const result = queryParamsSchema.parse({
  page: '2',
  limit: '20',
  search: '  노트북  ',
  sortBy: 'price'
});

console.log(result);
// {
//   page: 2,
//   limit: 20,
//   search: '노트북',
//   sortBy: 'price'
// }

transform을 쓸 때는 반드시 pipe()와 함께 써야 해요. transform으로 변환한 다음 값에 대해서 추가 검증을 하려면 pipe로 연결해야 하거든요. 이거 처음에 몰라서 좀 헤맸어요.

const userSettingsSchema = z.object({
  // 필수 필드
  userId: z.number(),
  
  // 선택 필드 (없어도 됨)
  nickname: z.string().optional(),
  
  // null 가능 (명시적으로 null을 보낼 수 있음)
  profileImage: z.string().url().nullable(),
  
  // null이거나 undefined 둘 다 가능
  bio: z.string().nullish(),
  
  // 기본값 제공
  theme: z.enum(['light', 'dark']).default('light'),
  fontSize: z.number().min(12).max(20).default(14),
  
  // 복합 사용
  notifications: z.object({
    email: z.boolean().default(true),
    push: z.boolean().default(false),
    sms: z.boolean().optional()
  }).optional()
});

// 최소한의 데이터만 있어도 OK
const minimalSettings = userSettingsSchema.parse({
  userId: 123
});

console.log(minimalSettings);
// {
//   userId: 123,
//   theme: 'light',
//   fontSize: 14,
//   profileImage: null (nullable이므로)
// }

import { z } from 'zod';

// 결제 방법별로 다른 스키마 정의
const creditCardPayment = z.object({
  type: z.literal('credit_card'),
  cardNumber: z.string().length(16),
  cvv: z.string().length(3),
  expiryDate: z.string().regex(/^\d{2}\/\d{2}$/)
});

const bankTransferPayment = z.object({
  type: z.literal('bank_transfer'),
  accountNumber: z.string().min(10),
  bankCode: z.string().length(3),
  accountHolder: z.string()
});

const cryptoPayment = z.object({
  type: z.literal('crypto'),
  walletAddress: z.string().startsWith('0x'),
  networkType: z.enum(['ethereum', 'bitcoin', 'polygon'])
});

// discriminatedUnion으로 통합
const paymentSchema = z.discriminatedUnion('type', [
  creditCardPayment,
  bankTransferPayment,
  cryptoPayment
]);

// 타입 안전하게 사용
const processPayment = (payment: z.infer) => {
  switch (payment.type) {
    case 'credit_card':
      console.log(`카드 결제: ${payment.cardNumber}`);
      break;
    case 'bank_transfer':
      console.log(`계좌이체: ${payment.accountNumber}`);
      break;
    case 'crypto':
      console.log(`암호화폐: ${payment.walletAddress}`);
      break;
  }
};

const eventSchema = z.object({
  startDate: z.string().datetime(),
  endDate: z.string().datetime(),
  registrationDeadline: z.string().datetime(),
  maxParticipants: z.number().positive(),
  currentParticipants: z.number().nonnegative()
}).refine(
  (data) => new Date(data.startDate) < new Date(data.endDate),
  {
    message: "종료일은 시작일보다 나중이어야 해요",
    path: ["endDate"]
  }
).refine(
  (data) => new Date(data.registrationDeadline) < new Date(data.startDate),
  {
    message: "등록 마감일은 시작일보다 빨라야 해요",
    path: ["registrationDeadline"]
  }
).refine(
  (data) => data.currentParticipants  {
  // 비밀번호 확인 검증
  if (data.password !== data.confirmPassword) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: "비밀번호가 일치하지 않아요",
      path: ["confirmPassword"]
    });
  }
  
  // 이전 비밀번호와 동일한지 확인
  if (data.oldPassword && data.password === data.oldPassword) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: "새 비밀번호는 이전 비밀번호와 달라야 해요",
      path: ["password"]
    });
  }
  
  // 비밀번호 강도 체크
  const hasUpperCase = /[A-Z]/.test(data.password);
  const hasLowerCase = /[a-z]/.test(data.password);
  const hasNumber = /[0-9]/.test(data.password);
  const hasSpecial = /[!@#$%^&*]/.test(data.password);
  
  if (!(hasUpperCase && hasLowerCase && hasNumber && hasSpecial)) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: "비밀번호는 대소문자, 숫자, 특수문자를 포함해야 해요",
      path: ["password"]
    });
  }
});

// transform으로 데이터 가공
const userInputSchema = z.object({
  email: z.string().email().transform(val => val.toLowerCase().trim()),
  username: z.string().transform(val => val.trim()),
  age: z.string().transform(val => parseInt(val, 10)).pipe(
    z.number().positive().max(150)
  ),
  tags: z.string().transform(val => 
    val.split(',').map(tag => tag.trim()).filter(Boolean)
  )
});

// 사용 예시
const result = userInputSchema.parse({
  email: '  USER@EXAMPLE.COM  ',
  username: '  john_doe  ',
  age: '25',
  tags: 'typescript, zod, validation, '
});
// 결과:
// {
//   email: 'user@example.com',
//   username: 'john_doe',
//   age: 25,
//   tags: ['typescript', 'zod', 'validation']
// }

// preprocess로 더 강력한 전처리
const dateSchema = z.preprocess((arg) => {
  if (typeof arg === 'string' || arg instanceof Date) {
    return new Date(arg);
  }
  return arg;
}, z.date().min(new Date('2026-01-01')));

// 다양한 형식의 날짜 입력 처리
dateSchema.parse('2026-05-21');  // ✅ 통과
dateSchema.parse(new Date());     // ✅ 통과
dateSchema.parse('2025-12-31');   // ❌ 2026년 이전 날짜

// 복잡한 파이프라인 구성
const priceSchema = z
  .string()
  .transform(val => val.replace(/[^0-9.]/g, ''))  // 숫자와 소수점만 남기기
  .pipe(z.string().regex(/^\d+\.?\d{0,2}$/))     // 소수점 둘째자리까지만
  .transform(val => parseFloat(val))              // 숫자로 변환
  .pipe(z.number().positive().max(1000000));      // 범위 검증

priceSchema.parse('$1,234.56');  // 결과: 1234.56
priceSchema.parse('€999.99');    // 결과: 999.99

// API 요청 스키마 - 모든 패턴 조합
const apiRequestSchema = z.object({
  action: z.enum(['create', 'update', 'delete']),
  timestamp: z.preprocess(
    (arg) => typeof arg === 'string' ? new Date(arg) : arg,
    z.date()
  ),
  payload: z.discriminatedUnion('action', [
    z.object({
      action: z.literal('create'),
      data: z.object({
        name: z.string().trim().min(1),
        email: z.string().email().toLowerCase(),
        tags: z.string().transform(val => 
          val.split(',').map(t => t.trim()).filter(Boolean)
        )
      })
    }),
    z.object({
      action: z.literal('update'),
      id: z.string().uuid(),
      data: z.object({
        name: z.string().trim().min(1).optional(),
        email: z.string().email().toLowerCase().optional()
      }).refine(
        (data) => Object.keys(data).length > 0,
        "최소 하나의 필드는 업데이트해야 해요"
      )
    }),
    z.object({
      action: z.literal('delete'),
      id: z.string().uuid(),
      confirm: z.literal(true, {
        errorMap: () => ({ message: "삭제하려면 confirm을 true로 설정해야 해요" })
      })
    })
  ])
}).superRefine((data, ctx) => {
  // 타임스탬프가 미래인지 확인
  if (data.timestamp > new Date()) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: "미래 시간은 사용할 수 없어요",
      path: ["timestamp"]
    });
  }
  
  // 액션과 페이로드 일치 여부 확인
  if (data.action !== data.payload.action) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: "액션 타입이 일치하지 않아요",
      path: ["payload", "action"]
    });
  }
});

고급 패턴을 너무 많이 조합하면 오히려 코드가 복잡해질 수 있어요. 참고로 저는 한 스키마에 최대 2-3개 패턴만 조합하는 걸 추천해요. 그 이상 가면 디버깅이 진짜 힘들어지거든요. 처음에는 저도 모든 패턴을 다 쓰려다가... 완전 스파게티 코드가 됐었어요. 진짜예요.

import { z } from 'zod';

// 사용자 응답 스키마
const UserApiResponseSchema = z.object({
  id: z.number(),
  email: z.string().email(),
  name: z.string(),
  avatar: z.string().url().nullable(),
  createdAt: z.string().datetime(),
  role: z.enum(['user', 'admin', 'moderator']),
  metadata: z.record(z.unknown()).optional()
});

// 페이지네이션 응답 스키마
const PaginatedResponseSchema = z.object({
  data: z.array(UserApiResponseSchema),
  pagination: z.object({
    page: z.number(),
    pageSize: z.number(),
    total: z.number(),
    hasNext: z.boolean()
  })
});

// API 호출 함수
async function fetchUsers(page: number = 1) {
  const response = await fetch(`/api/users?page=${page}`);
  const json = await response.json();
  
  // 검증 및 타입 추론
  const result = PaginatedResponseSchema.safeParse(json);
  
  if (!result.success) {
    console.error('API 응답 검증 실패:', result.error);
    throw new Error('잘못된 API 응답 형식');
  }
  
  return result.data; // 타입 안전!
}

const ProductSchema = z.object({
  id: z.string(),
  name: z.string(),
  // 문자열로 받아서 숫자로 변환
  price: z.string().transform((val) => parseFloat(val)),
  // ISO 문자열을 Date 객체로
  publishedAt: z.string().datetime().transform((val) => new Date(val)),
  // 쉼표로 구분된 문자열을 배열로
  tags: z.string().transform((val) => val.split(',').map(t => t.trim())),
  // 문자열 boolean을 실제 boolean으로
  isActive: z.string().transform((val) => val === 'true')
});

// 사용 예시
const apiData = {
  id: "123",
  name: "맥북 프로",
  price: "2890000",
  publishedAt: "2026-05-21T10:30:00Z",
  tags: "노트북, 애플, 프로",
  isActive: "true"
};

const product = ProductSchema.parse(apiData);
console.log(typeof product.price); // number
console.log(product.publishedAt instanceof Date); // true
console.log(Array.isArray(product.tags)); // true

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

// 회원가입 스키마
const SignupSchema = z.object({
  email: z.string()
    .email('올바른 이메일 형식이 아닙니다')
    .min(5, '이메일은 최소 5자 이상이어야 합니다'),
  password: z.string()
    .min(8, '비밀번호는 최소 8자 이상이어야 합니다')
    .regex(/[A-Z]/, '대문자를 1개 이상 포함해야 합니다')
    .regex(/[a-z]/, '소문자를 1개 이상 포함해야 합니다')
    .regex(/[0-9]/, '숫자를 1개 이상 포함해야 합니다')
    .regex(/[^A-Za-z0-9]/, '특수문자를 1개 이상 포함해야 합니다'),
  confirmPassword: z.string(),
  name: z.string()
    .min(2, '이름은 최소 2자 이상이어야 합니다')
    .max(20, '이름은 최대 20자까지 가능합니다'),
  age: z.number()
    .min(14, '만 14세 이상만 가입 가능합니다')
    .max(120, '올바른 나이를 입력해주세요'),
  terms: z.boolean()
    .refine((val) => val === true, '약관에 동의해주세요')
}).refine((data) => data.password === data.confirmPassword, {
  message: '비밀번호가 일치하지 않습니다',
  path: ['confirmPassword']
});

type SignupForm = z.infer;

function SignupPage() {
  const { register, handleSubmit, formState: { errors } } = useForm({
    resolver: zodResolver(SignupSchema)
  });

  const onSubmit = async (data: SignupForm) => {
    try {
      const response = await fetch('/api/signup', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data)
      });
      // 성공 처리
    } catch (error) {
      console.error('회원가입 실패:', error);
    }
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('email')} />
      {errors.email && <span>{errors.email.message}</span>}
      {/* 나머지 필드들... */}
    </form>
  );
}

import { useState, useCallback } from 'react';
import { debounce } from 'lodash';

// 이메일만 따로 검증하는 스키마
const EmailSchema = z.object({
  email: z.string().email()
}).pick({ email: true });

function EmailInput() {
  const [error, setError] = useState<string | null>(null);
  
  // 디바운스된 검증 함수
  const validateEmail = useCallback(
    debounce((value: string) => {
      const result = EmailSchema.safeParse({ email: value });
      if (!result.success) {
        setError(result.error.errors[0].message);
      } else {
        setError(null);
      }
    }, 500), // 500ms 대기
    []
  );
  
  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    validateEmail(e.target.value);
  };
  
  return (
    <>
      <input onChange={handleChange} />
      {error && <span style={{ color: 'red' }}>{error}</span>}
    </>
  );
}

const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB
const ACCEPTED_IMAGE_TYPES = ['image/jpeg', 'image/png', 'image/webp'];

const ImageUploadSchema = z.object({
  file: z.custom<File>((val) => val instanceof File, '파일을 선택해주세요')
    .refine((file) => file.size  ACCEPTED_IMAGE_TYPES.includes(file.type), {
      message: 'JPG, PNG, WebP 형식만 업로드 가능합니다'
    }),
  description: z.string().optional()
});

// 사용 예시
function handleFileUpload(e: React.ChangeEvent<HTMLInputElement>) {
  const file = e.target.files?.[0];
  if (!file) return;
  
  const result = ImageUploadSchema.safeParse({ 
    file,
    description: '프로필 사진' 
  });
  
  if (!result.success) {
    alert(result.error.errors[0].message);
    return;
  }
  
  // 업로드 진행
  uploadFile(result.data.file);
}

import { z } from 'zod';

// 공통 에러 메시지
const customErrorMap: z.ZodErrorMap = (issue, ctx) => {
  if (issue.code === z.ZodIssueCode.invalid_type) {
    if (issue.expected === 'string') {
      return { message: '문자열을 입력해주세요' };
    }
    if (issue.expected === 'number') {
      return { message: '숫자를 입력해주세요' };
    }
  }
  
  if (issue.code === z.ZodIssueCode.too_small) {
    if (issue.type === 'string') {
      return { message: `최소 ${issue.minimum}자 이상 입력해주세요` };
    }
  }
  
  if (issue.code === z.ZodIssueCode.too_big) {
    if (issue.type === 'string') {
      return { message: `최대 ${issue.maximum}자까지 입력 가능합니다` };
    }
  }
  
  return { message: ctx.defaultError };
};

// 전역 설정
z.setErrorMap(customErrorMap);

// 이제 모든 스키마에서 자동으로 한글 메시지 사용
const UserSchema = z.object({
  name: z.string().min(2).max(20),
  age: z.number().min(0).max(150)
});

• API 응답은 항상 safeParse로 검증하기
• 폼 검증에는 React Hook Form과 zodResolver 사용
• 실시간 검증은 디바운싱 적용하기
• 파일 업로드는 크기와 타입 모두 체크
• 에러 메시지는 사용자 친화적으로 작성
• 복잡한 검증은 refine 메서드 활용
• 공통 에러 메시지는 errorMap으로 관리

// 베이스 스키마들을 먼저 정의해요
const addressSchema = z.object({
  city: z.string(),
  street: z.string(),
  zipCode: z.string().regex(/^\d{5}$/)
});

const contactSchema = z.object({
  email: z.string().email(),
  phone: z.string()
});

// 조합해서 사용하는 거죠
const userSchema = z.object({
  name: z.string(),
  address: addressSchema,  // 재사용!
  contact: contactSchema   // 또 재사용!
});

// 부분적으로 확장도 가능해요
const premiumUserSchema = userSchema.extend({
  membershipLevel: z.enum(['gold', 'platinum']),
  points: z.number()
});

// 회원가입할 때는 일부 필드만 필요해요
const signupSchema = userSchema.pick({
  name: true,
  contact: true
});

// 업데이트할 때는 ID 빼고요
const updateSchema = userSchema.omit({
  id: true
});

// partial로 모든 필드를 옵셔널하게
const partialUpdateSchema = userSchema.partial();

const userSchema = z.object({
  email: z.string({
    required_error: "이메일은 필수 입력 항목이에요",
    invalid_type_error: "이메일 형식이 올바르지 않아요"
  }).email("올바른 이메일 주소를 입력해주세요"),
  
  age: z.number({
    required_error: "나이를 입력해주세요",
    invalid_type_error: "나이는 숫자로 입력해야 해요"
  }).min(19, "만 19세 이상만 가입 가능해요")
    .max(120, "나이를 다시 확인해주세요"),
  
  password: z.string()
    .min(8, "비밀번호는 최소 8자 이상이어야 해요")
    .regex(
      /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/,
      "영문 대소문자와 숫자를 포함해야 해요"
    )
});

// ❌ 안 좋은 예 - 매번 새로 생성
function validateUser(data: unknown) {
  const schema = z.object({ name: z.string() });
  return schema.parse(data);
}

// ✅ 좋은 예 - 한 번만 생성
const userSchema = z.object({ name: z.string() });

function validateUser(data: unknown) {
  return userSchema.parse(data);
}

// 재귀적 구조는 lazy로
type Category = {
  name: string;
  subcategories: Category[];
};

const categorySchema: z.ZodType = z.lazy(() =>
  z.object({
    name: z.string(),
    subcategories: z.array(categorySchema)
  })
);

// 스키마로부터 타입 추론
const userSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  role: z.enum(['admin', 'user'])
});

// 이렇게 타입을 자동으로 만들어요
type User = z.infer;
// { id: number; name: string; email: string; role: 'admin' | 'user' }

// 입력 타입도 만들 수 있어요 (변환 전)
type UserInput = z.input;

// 출력 타입 (변환 후)
type UserOutput = z.output;

// 기존 타입이 있을 때
interface User {
  id: number;
  name: string;
  email: string;
}

// Zod 스키마로 구현
const userSchema: z.ZodType = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email()
});

// 타입 안전성 보장!
const user = userSchema.parse(data);
// user는 User 타입으로 추론돼요

1. 환경 변수 검증

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']),
  API_URL: z.string().url(),
  PORT: z.string().transform(Number),
  DATABASE_URL: z.string().min(1)
});

export const env = envSchema.parse(process.env);

2. API 응답 검증

const apiResponseSchema = z.object({
  success: z.boolean(),
  data: z.unknown(),
  error: z.string().optional()
});

async function fetchData(url: string) {
  const response = await fetch(url);
  const json = await response.json();
  return apiResponseSchema.parse(json);
}

3. 폼 검증 헬퍼

function createFormValidator(schema: T) {
  return (data: unknown) => {
    const result = schema.safeParse(data);
    
    if (result.success) {
      return { data: result.data, errors: null };
    }
    
    // 필드별 에러 매핑
    const errors = result.error.errors.reduce((acc, err) => {
      const path = err.path.join('.');
      acc[path] = err.message;
      return acc;
    }, {} as Record);
    
    return { data: null, errors };
  };
}

• 너무 복잡한 스키마는 가독성이 떨어져요. 적절히 분리하세요
• 모든 데이터를 검증할 필요는 없어요. 외부 입력만 검증하는 게 효율적이에요
• 프로덕션에서는 에러 로깅을 꼭 설정하세요
• 스키마 버전 관리도 고려해보세요 (API v1, v2 등)

// 에러를 보기 좋게 출력하기
function debugZodError(error: z.ZodError) {
  console.log('? 검증 실패:');
  error.errors.forEach((err) => {
    console.log(`
      경로: ${err.path.join(' → ')}
      문제: ${err.message}
      받은 값: ${JSON.stringify(err.received)}
    `);
  });
}

// 사용 예시
const result = userSchema.safeParse(data);
if (!result.success) {
  debugZodError(result.error);
}

// 테스트 헬퍼
function expectValidation(
  schema: z.ZodType,
  validData: unknown,
  invalidData: unknown
) {
  expect(schema.safeParse(validData).success).toBe(true);
  expect(schema.safeParse(invalidData).success).toBe(false);
}