Zod란 무엇인가

TypeScript 환경에서 데이터 유효성 검사를 위한 유연한 스키마 선언 라이브러리이다. 런타임에서 데이터의 형태를 검증할 수 있게 해주며, 동시에 타입 추론 기능을 활용하여 컴파일 시점의 타입 안정성까지 보장한다. 최근에는 애플리케이션에서 Form, API 응답 등 외부로부터 들어오는 데이터의 신뢰성을 확보하는 데 필수적인 역할을 하고 있다.

Zod 장점

Zod의 가장 큰 장점은 정적 타입 추론을 사용한 TypeScript 우선 스키마 유효성 검사이다. 스키마를 한 번 정의하면 해당 스키마로부터 TypeScript 타입을 자동으로 추론할 수 있어, 타입 정의와 유효성 검사 로직을 이중으로 관리할 필요 없이 일관된 데이터 모델을 유지할 수 있다.

Zod의 기본 사용법

Zod를 사용하는 기본적인 흐름은 스키마 정의, 데이터 파싱 그리고 타입 추론의 세 단계로 나눌 수 있다.

스키마 정의

z.object()를 사용하여 객체 스키마를 정의하고, 각 필드의 타입을 z.string(), z.number() 등으로 지정한다.

import { z } from 'zod';

const UserSchema = z.object({
  username: z.string(),
  email: zl.string(),
  age: z.number(),
});

위 방식을 기존과 비교한다면, 기존 방식은 아래와 같다.

interface User {
  username: string;
  email: string;
  age: number;
}

이렇게 진행할 경우 문제는 런타임에서 아무것도 검증되지 않는다.

const data = JSON.parse(req.body);
// age가 string 이어도 에러가 발생하지 않는다. (런타임)

TypeScript는 컴파일에서만 타입을 검사하고, 서버에서 들어오는 JSON, API 응답은 보장하지 못 한다. 반대로 Zod를 사용하면 런타임 환경에서 데이터 검증, 잘못된 값이면 에러 throw, 타입 자동 추론(z.infer<typeof UserSchema>)등이 가능하기에 Zod를 사용한다.

데이터 파싱

정의한 스키마를 기반으로 실제 데이터를 검증할 수 있다.
Zod는 parse()와 safeParse() 두 가지 방식으로 유효성 검사를 제공한다.

parse()

parse()는 유효성 검사에 실패하면 에러를 throw한다.
따라서 try/catch와 함께 사용하는 것이 일반적이다.

import { z } from 'zod';

const UserSchema = z.object({
  username: z.string().min(3, 'Username must be at least 3 characters'),
  email: z.string().email('Invalid email format'),
  age: z.number(),
});

const validUserData = {
  username: 'Donggyu',
  email: 'contact@dong-gyu.com',
  age: 29,
};

try {
  const user = UserSchema.parse(validUserData);
  console.log('Valid user data:', user);
} catch (error) {
  console.error('Validation error:', error);
}

parse의 특징은 실패 시, 예외 발생, 서버 로직에서 사용하기 적합, 잘못된 데이터는 즉시 중단 가능이다.

safeParse()

safeParse()는 에러를 throw하지 않고 결과 객체를 반환한다.

import { z } from 'zod';

const UserSchema = z.object({
  username: z.string().min(3, 'Username must be at least 3 characters'),
  email: z.string().email('Invalid email format'),
  age: z.number(),
});

const invalidUserData = {
  username: 'Do', // 최소 길이 3 미만
  email: 'invalid-email', // 이메일 형식 아님
  age: '20', // number 타입 아님
};

const result = UserSchema.safeParse(invalidUserData);

if (result.success) {
  console.log('Validation successful:', result.data);
} else {
  console.error('Validation failed:', result.error.flatten().fieldErrors);
}

타입 추론

Zod는 런타임 스키마 정의로부터 TypeScript 타입을 자동으로 생성할 수 있다.
이를 통해 타입 정의와 유효성 검사 로직을 중복 작성할 필요가 없다.

import { z } from 'zod';

const ProductSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(1),
  price: z.number().positive(),
  description: z.string().optional(),
});

// 스키마로부터 타입 추론
type Product = z.infer<typeof ProductSchema>;

const myProduct: Product = {
  id: 'a1b2c3d4-e5f6-7890-1234-567890abcdef',
  name: 'Donggyu Kim',
  price: 99.99,
};

description은 optional로 정의했기 때문에 TypeScript에서는 string | undefined로 추론된다.

myProduct.description = 123;
Type 'number' is not assignable to type 'string | undefined'

주요 스키마 타입 및 유효성 검사

Zod는 다양한 내장 스키마 타입과 유효성 검사 메서드를 제공한다.

원시 타입 (Primitives)

기본적인 JavaScript/TypeScript 타입을 위한 스키마이다.

import { z } from 'zod';

const myString = z.string();
const myNumber = z.number();
const myBoolean = z.boolean();
const myDate = z.date();
const myBigInt = z.bigint();
const mySymbol = z.symbol();

const myUndefined = z.undefined();
const myNull = z.null();
const myVoid = z.void();
const myAny = z.any();
const myUnknown = z.unknown();
const myNever = z.never();

문자열

import { z } from 'zod';

const usernameSchema = z.string().min(3, '최소 3자 이상이어야 합니다.').max(20, '최대 20자까지 가능합니다.');
const emailSchema = z.string().email('유효한 이메일 형식이 아닙니다.');
const urlSchema = z.string().url('유효한 URL 형식이 아닙니다.');
const uuidSchema = z.string().uuid('유효한 UUID 형식이 아닙니다.');
const regexSchema = z.string().regex(/^[A-Z]+$/, '대문자만 허용됩니다.');

// 변환 메서드
const trimmedString = z.string().trim(); // 앞뒤 공백 제거
const lowercasedString = z.string().toLowerCase(); // 소문자로 변환
const uppercasedString = z.string().toUpperCase(); // 대문자로 변환

이외에도 숫자, 객체, 배열, 열거형(Enums), 유니온(Unions), 고급 변환 등 다양한 형태로 제공되고 있다.

이중 실무에서 많이 사용되는건 React Hook Form과의 통합이다.

React hook form & Zod 조합

Zod는 React Hook Form과 함께 자주 사용된다.
@hookform/resolvers/zod 패키지를 사용하면 Zod 스키마를 React Hook Form의 유효성 검사 시스템과 쉽게 연결할 수 있다.

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

// 폼 데이터에 대한 Zod 스키마 정의
const LoginFormSchema = z.object({
  email: z.string().email('유효한 이메일 주소를 입력해주세요.'),
  password: z.string().min(6, '비밀번호는 최소 6자 이상이어야 합니다.'),
});

type LoginFormInputs = z.infer<typeof LoginFormSchema>;

function LoginForm() {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<LoginFormInputs>({
    resolver: zodResolver(LoginFormSchema), // Zod 스키마를 resolver로 연결
  });

  const onSubmit = (data: LoginFormInputs) => {
    console.log('폼 제출 데이터:', data);
  };
}
// ...

zodResolver는 Zod 스키마를 React Hook Form의 validation resolver 형식으로 변환해주는 어댑터 역할을 한다.
이를 통해 다음과 같은 장점을 얻을 수 있다.

유효성 검사 규칙을 Zod 스키마 하나로 통합 관리
타입 추론과 폼 검증 로직의 일관성 유지
Zod에 정의한 에러 메시지를 그대로 활용 가능
클라이언트와 서버에서 동일한 스키마 재사용 가능

마치며

Zod는 프로젝트에서 데이터 유효성 검사를 간결하게 작성하면서도 타입 안정성을 유지할 수 있도록 돕는 도구이다. 1 런타임 검증과 TypeScript 타입 추론을 하나의 스키마로 통합할 수 있다는 점은 특히 큰 장점이다.

다양한 내장 스키마 타입과 풍부한 유효성 검사 메서드, 그리고 React Hook Form과 같은 인기 라이브러리와의 쉬운 통합은 Zod를 실무에서 매우 강력한 선택지로 만들어준다.

특히 클라이언트와 서버에서 동일한 스키마를 재사용할 수 있어,
타입과 검증 로직의 불일치를 방지하고 코드의 일관성을 유지할 수 있다.

Zod 사용하는 이유와 사용법 공부