시스매

Zod를 사용해야 하는 상황과 TypeScript 타입 연계 핸드북

11 min read

Zod를 사용해야 하는 상황과 TypeScript 타입 연계 핸드북

주요 권고사항

Zod는 런타임 유효성 검증이 필요한 상황에서 사용하며, TypeScript의 컴파일 타임 타입 검사를 보완하는 역할을 한다. 기존 TypeScript 인터페이스와 완전히 호환되며, 단일 스키마에서 타입을 추론하거나 타입에서 스키마를 생성하는 양방향 연계가 가능하다.

1. Zod를 사용해야 하는 핵심 상황

1.1 런타임 데이터 검증이 필요한 경우123

외부 API 응답 검증

// ❌ TypeScript만 사용 - 런타임 안전성 없음
interface ApiResponse {
  user: {
    id: number;
    name: string;
    email: string;
  };
}
 
async function fetchUser(): Promise<ApiResponse> {
  const response = await fetch('/api/user');
  const data = await response.json();
  return data; // 타입 단언만으로는 실제 데이터 보장 불가
}
 
// ✅ Zod 사용 - 런타임 검증
import { z } from 'zod';
 
const UserSchema = z.object({
  user: z.object({
    id: z.number(),
    name: z.string(),
    email: z.string().email()
  })
});
 
async function fetchUserSafe() {
  const response = await fetch('/api/user');
  const data = await response.json();
  return UserSchema.parse(data); // 런타임에서 실제 검증
}

사용자 입력 데이터 검증43

const UserRegistrationSchema = z.object({
  username: z.string()
    .min(3, "사용자명은 3자 이상이어야 합니다")
    .max(20, "사용자명은 20자 이하여야 합니다"),
  email: z.string().email("올바른 이메일 형식이 아닙니다"),
  password: z.string()
    .min(8, "비밀번호는 8자 이상이어야 합니다")
    .regex(/[A-Z]/, "대문자가 포함되어야 합니다")
    .regex(/[0-9]/, "숫자가 포함되어야 합니다"),
  age: z.number().min(13, "13세 이상만 가입 가능합니다")
});
 
// 폼 데이터 검증
function validateUserInput(formData: FormData) {
  const result = UserRegistrationSchema.safeParse({
    username: formData.get('username'),
    email: formData.get('email'),
    password: formData.get('password'),
    age: Number(formData.get('age'))
  });
 
  if (!result.success) {
    return { errors: result.error.flatten().fieldErrors };
  }
  
  return { data: result.data };
}

1.2 환경 변수 및 설정 검증35

const EnvSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']),
  DATABASE_URL: z.string().url(),
  API_KEY: z.string().min(32),
  PORT: z.string().regex(/^\d+$/).transform(Number).default('3000'),
  REDIS_URL: z.string().url().optional()
});
 
// 애플리케이션 시작 시 환경 변수 검증
export const env = EnvSchema.parse(process.env);

1.3 TypeScript 타입 시스템의 한계 보완267

컴파일 타임 vs 런타임의 차이28

// TypeScript는 컴파일 타임에만 타입 검사
interface Product {
  id: number;
  name: string;
  price: number;
}
 
// 이 함수는 컴파일 시에는 문제없지만 런타임에서 오류 발생 가능
function processProduct(product: Product) {
  return product.name.toUpperCase(); // product.name이 실제로 string인지 보장 불가
}
 
// API에서 받은 데이터가 실제로는 다른 형태일 수 있음
const apiData = await fetch('/api/product').then(res => res.json());
processProduct(apiData); // 런타임 오류 가능성

Zod로 런타임 안전성 확보

const ProductSchema = z.object({
  id: z.number(),
  name: z.string(),
  price: z.number().positive()
});
 
function processProductSafe(rawData: unknown) {
  const product = ProductSchema.parse(rawData); // 런타임 검증
  return product.name.toUpperCase(); // 타입 안전성 보장
}

2. TypeScript 타입과 Zod 스키마 연계 방법

2.1 Zod 스키마에서 TypeScript 타입 추론91011

기본 타입 추론

import { z } from 'zod';
 
// 스키마 정의
const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  isActive: z.boolean(),
  metadata: z.record(z.string()).optional()
});
 
// 타입 자동 추론 - 단일 진실 소스(Single Source of Truth)
type User = z.infer<typeof UserSchema>;
// 결과: {
//   id: number;
//   name: string;
//   email: string;
//   isActive: boolean;
//   metadata?: Record<string, string> | undefined;
// }
 
// 타입 사용
const createUser = (userData: User): User => {
  return UserSchema.parse(userData);
};

중첩 객체와 배열 타입 추론11

const BlogPostSchema = z.object({
  id: z.string().uuid(),
  title: z.string(),
  content: z.string(),
  author: z.object({
    id: z.number(),
    name: z.string(),
    email: z.string().email()
  }),
  tags: z.array(z.string()),
  publishedAt: z.date(),
  comments: z.array(z.object({
    id: z.number(),
    content: z.string(),
    authorName: z.string()
  }))
});
 
// 복잡한 중첩 타입도 자동 추론
type BlogPost = z.infer<typeof BlogPostSchema>;
 
// 특정 부분만 추출
type Author = BlogPost['author'];
type Comment = BlogPost['comments'][number];

2.2 기존 TypeScript 인터페이스와 Zod 스키마 동기화1213

satisfies 연산자를 활용한 타입 검증12

// 기존 TypeScript 인터페이스
interface User {
  id: string;
  name: string;
  age: number;
  email?: string;
}
 
// 스키마 타입 헬퍼
type SchemaFromInterface<T> = {
  [K in keyof T]-?: undefined extends T[K] 
    ? z.ZodOptional<z.ZodType<NonNullable<T[K]>>>
    : z.ZodType<T[K]>
};
 
// Zod 스키마가 인터페이스와 일치하는지 검증
const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  age: z.number(),
  email: z.string().email().optional(),
}) satisfies z.ZodType<User>;
 
// 또는 더 정확한 검증
const UserSchemaStrict = z.object({
  id: z.string(),
  name: z.string(),
  age: z.number(),
  email: z.string().email().optional(),
}) satisfies SchemaFromInterface<User>;

타입과 스키마 일치성 보장13

interface ApiConfig {
  baseUrl: string;
  timeout: number;
  retries: number;
  headers?: Record<string, string>;
}
 
const ApiConfigSchema = z.object({
  baseUrl: z.string().url(),
  timeout: z.number().positive(),
  retries: z.number().int().nonnegative(),
  headers: z.record(z.string()).optional()
}) satisfies z.ZodType<ApiConfig>;
 
// 컴파일 타임에 타입 불일치 검사
type ConfigFromSchema = z.infer<typeof ApiConfigSchema>;
type TypesMatch = ApiConfig extends ConfigFromSchema 
  ? ConfigFromSchema extends ApiConfig 
    ? true 
    : false 
  : false; // true여야 함

2.3 TypeScript 타입에서 Zod 스키마 생성141516

수동 변환 패턴14

// 기존 TypeScript 타입
type Status = 'active' | 'inactive' | 'pending';
 
interface Product {
  id: string;
  name: string;
  price: number;
  status: Status;
  description?: string;
  categories: string[];
}
 
// Zod 스키마로 변환
const StatusSchema = z.enum(['active', 'inactive', 'pending']);
 
const ProductSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(1),
  price: z.number().positive(),
  status: StatusSchema,
  description: z.string().optional(),
  categories: z.array(z.string())
});
 
// 타입 일치성 검증
type ProductFromSchema = z.infer<typeof ProductSchema>;

자동 변환 도구 활용1517

# ts-to-zod 사용
npm install --save-dev ts-to-zod
npx ts-to-zod src/types.ts src/schemas.ts
 
# VSCode Transform Tool 확장 사용
# JSON/TypeScript → Zod 스키마 변환

3. 고급 연계 패턴

3.1 조건부 타입과 스키마1819

// 기본 스키마
const BaseUserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email()
});
 
// 역할별 확장 스키마
const AdminUserSchema = BaseUserSchema.extend({
  role: z.literal('admin'),
  permissions: z.array(z.string())
});
 
const RegularUserSchema = BaseUserSchema.extend({
  role: z.literal('user'),
  preferences: z.object({
    theme: z.enum(['light', 'dark']),
    notifications: z.boolean()
  })
});
 
// 유니온 스키마
const UserSchema = z.discriminatedUnion('role', [
  AdminUserSchema,
  RegularUserSchema
]);
 
// 조건부 타입 추론
type User = z.infer<typeof UserSchema>;
// 결과: 
// | { id: string; name: string; email: string; role: 'admin'; permissions: string[]; }
// | { id: string; name: string; email: string; role: 'user'; preferences: {...}; }

3.2 변환과 타입 분리1910

const UserInputSchema = z.object({
  name: z.string(),
  email: z.string().email(),
  birthDate: z.string() // 입력은 문자열
}).transform(data => ({
  ...data,
  birthDate: new Date(data.birthDate), // 출력은 Date 객체
  createdAt: new Date()
}));
 
// 입력/출력 타입 분리
type UserInput = z.input<typeof UserInputSchema>;   // birthDate: string
type UserOutput = z.output<typeof UserInputSchema>; // birthDate: Date, createdAt: Date

4. 실전 활용 전략

4.1 프로젝트 구조화189

// schemas/user.ts
export const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string().min(1)
});
 
export type User = z.infer<typeof UserSchema>;
 
// schemas/api.ts
export const CreateUserRequestSchema = UserSchema.omit({ id: true });
export const UpdateUserRequestSchema = UserSchema.partial();
 
export type CreateUserRequest = z.infer<typeof CreateUserRequestSchema>;
export type UpdateUserRequest = z.infer<typeof UpdateUserRequestSchema>;

4.2 에러 처리와 타입 안전성45

function processUserData<T extends z.ZodSchema>(
  schema: T,
  data: unknown
): { success: true; data: z.infer<T> } | { success: false; errors: string[] } {
  const result = schema.safeParse(data);
  
  if (result.success) {
    return { success: true, data: result.data };
  }
  
  return {
    success: false,
    errors: result.error.errors.map(err => err.message)
  };
}
 
// 사용
const result = processUserData(UserSchema, unknownData);
if (result.success) {
  // result.data는 User 타입으로 자동 추론
  console.log(result.data.name);
}

5. 베스트 프랙티스

5.1 성능 고려사항2021

// ✅ 스키마를 모듈 레벨에서 정의 (재사용)
const UserSchema = z.object({
  id: z.string(),
  name: z.string()
});
 
// ❌ 함수 내부에서 스키마 생성 (매번 새로 생성)
function validateUser(data: unknown) {
  const schema = z.object({ id: z.string(), name: z.string() }); // 비효율적
  return schema.parse(data);
}

5.2 타입 추론 최적화2223

// ✅ 명시적 타입 export
export const UserSchema = z.object({
  id: z.string(),
  name: z.string()
});
 
export type User = z.infer<typeof UserSchema>;
 
// ❌ 타입만 export (Zod 의존성 생성)
export type User = z.infer<typeof UserSchema>; // 다른 프로젝트에서 Zod 필요

결론

Zod는 TypeScript의 컴파일 타임 타입 검사를 런타임 검증으로 확장하는 핵심 도구이다. 외부 데이터 검증, 사용자 입력 처리, 환경 설정 검증 등 런타임 안전성이 필요한 모든 상황에서 필수적이다.

기존 TypeScript 타입 시스템과의 완벽한 호환성을 제공하며, 스키마에서 타입 추론 또는 타입에서 스키마 생성의 양방향 연계가 가능하다. 이를 통해 단일 진실 소스를 유지하면서도 컴파일 타임과 런타임 모두에서 타입 안전성을 보장할 수 있다.

특히 현대적인 웹 개발에서 API 통신, 폼 처리, 환경 설정 등 다양한 외부 데이터 소스를 다룰 때, Zod는 TypeScript 만으로는 불가능한 런타임 타입 안전성을 제공하여 더욱 견고한 애플리케이션 개발을 가능하게 한다.

⁂

Footnotes

  1. https://numeric.substack.com/p/how-we-doubled-zod-performance-to ↩

  2. https://stevekinney.com/courses/full-stack-typescript/type-safety-vs-runtime-validation ↩ ↩2 ↩3

  3. https://www.linkedin.com/pulse/bridging-gap-between-typescript-runtime-validation-madhan-kumar-xltlc ↩ ↩2 ↩3

  4. https://www.dhiwise.com/post/comparing-zod-and-yup-the-ultimate-showdown ↩ ↩2

  5. https://www.wisp.blog/blog/validating-typescript-types-in-runtime-using-zod ↩ ↩2

  6. https://stackoverflow.com/questions/74733718/why-is-runtime-type-checking-so-important-in-ts ↩

  7. https://dev.to/narasimha1997/the-most-common-misconception-about-typescript-3f2a ↩

  8. https://www.reddit.com/r/react/comments/1iu00tm/why_use_zod_or_yup_when_you_have_typescript/ ↩

  9. https://www.allthingstypescript.dev/p/using-zod-schemas-as-source-of-truth ↩ ↩2

  10. https://www.totaltypescript.com/tutorials/zod/zod-section/infer/solution ↩ ↩2

  11. https://stackoverflow.com/questions/73043223/infer-type-from-key-of-object-inside-an-array-zod ↩ ↩2

  12. https://github.com/colinhacks/zod/issues/2807 ↩ ↩2

  13. https://stackoverflow.com/questions/75886482/check-zod-types-are-equivalent-to-a-typescript-interface ↩ ↩2

  14. https://edkool.com/articles/establishing-validation-by-converting-typescript-code-to-zod-schemas ↩ ↩2

  15. https://www.npmjs.com/package/ts-to-zod ↩ ↩2

  16. https://transform.tools/typescript-to-zod ↩

  17. https://dev.to/osonwa/convert-api-json-responses-to-typescript-types-and-zod-schemas-in-vscode-3d3p ↩

  18. https://blog.bitsrc.io/7-powerful-use-cases-for-zod-schemas-b6df6d77bebc ↩ ↩2

  19. https://www.open200.com/post/typesafe-everything-with-zod-by-example ↩ ↩2

  20. https://dev.to/nicklucas/typescript-runtime-validators-and-dx-a-type-checking-performance-analysis-of-zodsuperstructyuptypebox-5416 ↩

  21. https://dev.to/dzakh/zod-v4-17x-slower-and-why-you-should-care-1m1 ↩

  22. https://www.reddit.com/r/typescript/comments/10f8kah/is_using_zod_as_the_primary_source_of_truth_for/ ↩

  23. https://www.reddit.com/r/typescript/comments/15a8n6a/question_about_zod_inferred_types/ ↩

그래프 뷰

백링크