[TypeScript] Zod 시작하기, 타입스크립트 Validation 라이브러리

TypeScript를 사용하면서 가장 흔히 겪는 문제 중 하나는 외부에서 들어오는 데이터(API 응답, 사용자 입력 등)의 타입을 보장할 수 없다는 점인데. TypeScript의 타입 시스템은 컴파일 타임에만 작동하기 때문입니다.

이러한 문제를 해결하고 런타임에서도 데이터의 무결성을 완벽하게 보장해주는 라이브러리가 바로 Zod 입니다.

 

1. Zod란?

Zod는 TypeScript-first 스키마 선언 및 검증 라이브러리로.

단순히 데이터를 검사하는 것을 넘어, 정의한 스키마로부터 TypeScript 타입을 자동으로 추론할 수 있다는 점이 가장 큰 특징입니다.

https://zod.dev/

Intro | Zod

 

 

2. 설치

npm install zod       # npm
yarn add zod          # yarn
pnpm add zod          # pnpm

 

 

 

3. 기본 사용법 - 스키마 정의와 검증

 

Zod의 기본 흐름은 스키마 정의 → 데이터 검증 → 데이터 사용 의 순서로 이루어집니다.

① 스키마 정의

가장 많이 사용되는 z.object를 이용해 객체의 형태를 정의.

import { z } from "zod";

const UserSchema = z.object({
  id: z.number(),
  username: z.string().min(2, "이름은 최소 2자 이상이어야 합니다."),
  email: z.string().email("유효한 이메일 형식이 아닙니다."),
  role: z.enum(["admin", "user"]),
  createdAt: z.date().default(() => new Date()), // 기본값 설정
});

 

② 데이터 검증 (parse vs safeParse)

데이터를 검증하는 방법은 두 가지로.

• parse(): 검증 실패 시 에러를 던짐. (try-catch 필요)
• safeParse(): 에러를 던지지 않고 성공 여부와 결과를 객체로 반환.

const data = {
  id: 1,
  username: "Zod",
  email: "test@example.com",
  role: "user"
};

// 1. parse 사용
try {
  const user = UserSchema.parse(data);
  console.log("검증 성공:", user);
} catch (e) {
  console.error("검증 실패:", e);
}

// 2. safeParse 사용 (더 권장되는 방식)
const result = UserSchema.safeParse(data);
if (result.success) {
  console.log("데이터:", result.data);
} else {
  console.error("에러 메시지:", result.error.issues);
}

 

 

 

 

4. Zod의 핵심 - 타입 추론 (Type Inference)

 

Zod를 사용하면 인터페이스나 타입을 중복해서 선언할 필요가 없습니다. z.infer를 사용하면 스키마가 곧 타입이 됩니다.

type User = z.infer<typeof UserSchema>;

// 위 코드는 아래와 같은 TypeScript 타입을 생성한 것과 같다.
/*
type User = {
  id: number;
  username: string;
  email: string;
  role: "admin" | "user";
  createdAt: Date;
}
*/

 

 

 

 

5. 유용한 고급 기능들

.refine(): 커스텀 검증

기본 메서드만으로 부족할 때, 개발자가 직접 로직을 짤 수 있음. (예: 비밀번호 확인)

const SignupSchema = z.object({
  password: z.string(),
  confirmPassword: z.string(),
}).refine((data) => data.password === data.confirmPassword, {
  message: "비밀번호가 일치하지 않습니다.",
  path: ["confirmPassword"], // 에러가 발생할 필드 지정
});

 

.partial() & .pick() / .omit()

기존 스키마를 재사용하여 새로운 스키마를 생성할 수 있음.

const UpdateUserSchema = UserSchema.partial(); // 모든 필드를 optional로 변경
const EmailOnlySchema = UserSchema.pick({ email: true }); // email 필드만 선택

 

 

 

---

마치며

Zod는 TypeScript 환경에서 데이터 안정성을 확보하기 위한 필수 도구로 자리 잡았습니다.

특히 React Hook Form과 같은 라이브러리와의 자주 쓰이며, 백엔드와 프론트엔드 간의 데이터 규격을 맞출 때 효과적입니다.