Zod Validation - 🌲 Sonamu

Sonamu는 Zod를 사용하여 TypeScript 타입을 런타임에서도 검증합니다. 이 문서는 Zod validation의 모든 기능과 패턴을 설명합니다.

Zod란?

타입 안전 스키마

TypeScript 타입 자동 추론 별도 타입 정의 불필요

런타임 검증

실행 시 데이터 검증 잘못된 데이터 차단

상세한 에러

필드별 에러 메시지 디버깅 용이

변환 & 기본값

데이터 변환 및 기본값 유연한 처리

기본 사용법

Zod 스키마는 Entity에서 자동 생성되지만, 직접 정의할 수도 있습니다.

스키마 정의

import { z } from "zod";

// Entity로부터 자동 생성
export const User = z.object({
id: z.number().int(),
email: z.string().max(100),
age: z.number().int(),
role: z.enum(["admin", "normal"]),
});

export type User = z.infer<typeof User>;

데이터 검증

import { User } from "./user.types";

try {
const user = User.parse({
id: 1,
email: "john@test.com",
age: 30,
role: "admin",
});
// ✅ 검증 성공, user는 User 타입
console.log(user.email);
} catch (error) {
// ❌ 검증 실패 시 ZodError
console.error(error);
}

parse vs safeParse:

parse(): 에러를 던집니다. try-catch로 처리
safeParse(): 에러를 반환합니다. result.success로 체크

API 핸들러에서는 parse()를 사용하여 자동으로 400 에러를 반환하고, UI에서는 safeParse()로 안전하게 처리합니다.

기본 타입 검증

Entity의 각 타입별 Zod 검증입니다.

문자열 검증

const email = z.string();
email.parse("john@test.com");  // ✅

const withLength = z.string().max(100);
withLength.parse("a".repeat(100)); // ✅
withLength.parse("a".repeat(101)); // ❌

숫자 검증

const age = z.number().int();
age.parse(30);  // ✅
age.parse(30.5);  // ❌ Must be integer

날짜 검증

const birthDate = z.date();
birthDate.parse(new Date());  // ✅
birthDate.parse("2024-01-01");  // ❌ Expected Date, received string

불린 검증

const isActive = z.boolean();
isActive.parse(true); // ✅
isActive.parse(false); // ✅
isActive.parse("true"); // ❌ Expected boolean, received string

// 변환: 문자열 → 불린
const coerced = z.coerce.boolean();
coerced.parse("true"); // ✅ true
coerced.parse("false"); // ✅ false
coerced.parse(1); // ✅ true
coerced.parse(0); // ✅ false

복합 타입 검증

배열

const tags = z.string().array();
tags.parse(["typescript", "nodejs"]);  // ✅
tags.parse(["typescript", 123]);  // ❌

객체

const user = z.object({
  name: z.string(),
  profile: z.object({
    bio: z.string(),
    website: z.string().url().optional(),
  }),
});

user.parse({
name: "John",
profile: {
bio: "Hello",
website: "https://john.com",
},
}); // ✅

Enum

const role = z.enum(["admin", "moderator", "normal"]);

role.parse("admin"); // ✅
role.parse("guest"); // ❌ Invalid enum value

Union (여러 타입 중 하나)

const idOrEmail = z.union([z.number().int(), z.string().email()]);

idOrEmail.parse(123); // ✅
idOrEmail.parse("john@test.com"); // ✅
idOrEmail.parse("not-an-email"); // ❌

고급 검증 패턴

조건부 검증

const password = z.string()
  .min(8)
  .refine(
    (val) => /[A-Z]/.test(val),
    { message: "대문자를 포함해야 합니다" }
  )
  .refine(
    (val) => /[0-9]/.test(val),
    { message: "숫자를 포함해야 합니다" }
  )
  .refine(
    (val) => /[!@#$%^&*]/.test(val),
    { message: "특수문자를 포함해야 합니다" }
  );

password.parse("Abc12345!"); // ✅
password.parse("abc12345"); // ❌ 대문자 없음

데이터 변환

const age = z.string().transform(val => parseInt(val, 10));

age.parse("30"); // ✅ 30 (number)

기본값 설정

const settings = z.object({
  theme: z.enum(["light", "dark"]).default("light"),
  notifications: z.boolean().default(true),
});

settings.parse({}); // ✅ { theme: "light", notifications: true }
settings.parse({ theme: "dark" }); // ✅ { theme: "dark", notifications: true }

실전 검증 패턴

API 파라미터 검증

export const UserListParams = z.object({
  num: z.number().int().min(1).max(100).default(24),
  page: z.number().int().min(1).default(1),
  search: z.enum(["id", "email", "username"]).optional(),
  keyword: z.string().trim().optional(),
  orderBy: z.enum(["id-desc", "id-asc", "created_at-desc"]).optional(),
}).refine(
  (data) => {
    // keyword가 있으면 search도 필수
    if (data.keyword && !data.search) {
      return false;
    }
    return true;
  },
  {
    message: "keyword와 search는 함께 사용해야 합니다",
    path: ["search"],
  }
);

비즈니스 로직 검증

const dateRange = z.object({
  startDate: z.date(),
  endDate: z.date(),
}).refine(
  (data) => data.endDate > data.startDate,
  {
    message: "종료일은 시작일보다 이후여야 합니다",
    path: ["endDate"],
  }
).refine(
  (data) => {
    const diff = data.endDate.getTime() - data.startDate.getTime();
    const days = diff / (1000 * 60 * 60 * 24);
    return days <= 365;
  },
  {
    message: "기간은 최대 1년까지만 가능합니다",
    path: ["endDate"],
  }
);

Form 검증

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { UserSaveParams } from "@/services/user/user.types";

function UserForm() {
  const form = useForm({
    resolver: zodResolver(UserSaveParams),
    defaultValues: {
      email: "",
      username: "",
      role: "normal",
    },
  });

  const onSubmit = form.handleSubmit((data) => {
    // data는 자동으로 UserSaveParams 타입
    console.log(data);
  });

  return (
    <form onSubmit={onSubmit}>
      <input {...form.register("email")} />
      {form.formState.errors.email && <span>{form.formState.errors.email.message}</span>}

      <input {...form.register("username")} />
      {form.formState.errors.username && <span>{form.formState.errors.username.message}</span>}

      <button type="submit">저장</button>
    </form>
  );
}

에러 처리

ZodError 구조

try {
  User.parse(invalidData);
} catch (error) {
  if (error instanceof z.ZodError) {
    console.log(error.issues);
    // [
    //   {
    //     code: "invalid_type",
    //     expected: "string",
    //     received: "number",
    //     path: ["email"],
    //     message: "Expected string, received number"
    //   },
    //   {
    //     code: "too_small",
    //     minimum: 8,
    //     type: "string",
    //     inclusive: true,
    //     path: ["password"],
    //     message: "String must contain at least 8 character(s)"
    //   }
    // ]
  }
}

에러 메시지 커스터마이징

const user = z.object({
  email: z.string().email("유효한 이메일 주소를 입력하세요"),
  age: z.number()
    .int("나이는 정수여야 합니다")
    .min(0, "나이는 0 이상이어야 합니다")
    .max(120, "나이는 120 이하여야 합니다"),
});

에러 포맷팅

const result = User.safeParse(invalidData);

if (!result.success) {
  // Flat 에러 (필드별)
  const flatErrors = result.error.flatten();
  console.log(flatErrors.fieldErrors);
  // {
  //   email: ["Invalid email"],
  //   age: ["Number must be greater than 0"]
  // }

  // Form 에러 (React Hook Form 형식)
  const formErrors = result.error.format();
  console.log(formErrors.email?._errors); // ["Invalid email"]
}

성능 최적화

스키마 재사용

// ❌ 매번 새로 생성 (느림)
function validate(data: unknown) {
  const schema = z.object({
    name: z.string(),
    age: z.number(),
  });
  return schema.parse(data);
}

// ✅ 스키마 재사용 (빠름)
const schema = z.object({
  name: z.string(),
  age: z.number(),
});

function validate(data: unknown) {
  return schema.parse(data);
}

부분 검증

// 전체 검증 불필요 시 부분 검증
const user = z.object({
  id: z.number(),
  email: z.string().email(),
  profile: z.object({
    bio: z.string(),
    website: z.string().url(),
  }),
});

// 이메일만 검증
const emailOnly = user.pick({ email: true });
emailOnly.parse({ email: "john@test.com" }); // ✅ 빠름

// profile만 검증
const profileOnly = user.pick({ profile: true });

다음 단계

E2E Type Safety

엔드투엔드 타입 안전성

Entity Types

Entity 타입 변환

Generated Types

생성 타입 활용

Model Testing

Zod 검증 테스트하기

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​Zod란?

타입 안전 스키마

런타임 검증

상세한 에러

변환 & 기본값

​기본 사용법

​스키마 정의

​데이터 검증

​기본 타입 검증

​문자열 검증

​숫자 검증

​날짜 검증

​불린 검증

​복합 타입 검증

​배열

​객체

​Enum

​Union (여러 타입 중 하나)

​고급 검증 패턴

​조건부 검증

​데이터 변환

​기본값 설정

​실전 검증 패턴

​API 파라미터 검증

​비즈니스 로직 검증

​Form 검증

​에러 처리

​ZodError 구조

​에러 메시지 커스터마이징

​에러 포맷팅

​성능 최적화

​스키마 재사용

​부분 검증

​다음 단계