Zod로 입력값·API 응답 스키마 유효성 검사하기

안녕하세요! 36기 YB 엄경호입니다. 😊😊

이번 과제에서는 숫자야구 입력값 검증을 if/else로 처리하고, GitHub API 응답 검증도 구현했었습니다.

 

이때 케이스가 늘어나거나 예외 조건이 복잡해질수록 코드 관리가 어려워질 수 있다고 생각했습니다.

 

오늘은 선언형 스키마 방식의 Zod를 도입해 검증 로직을 단순화하는 방법에 대해 알아보려 합니다!

Zod가 필요한 이유

Zod를 도입해야 하는 이유는 TypeScript만으로는 런타임 단계에서의 타입 검증을 보장할 수 없기 때문입니다.

 

TypeScript는 컴파일 시점에만 타입 에러를 잡아주고, 실행 시점의 JavaScript에서는 타입 정보가 모두 사라집니다.

 

게다가 TypeScript는 number 타입만 지정할 수 있을 뿐, 특정 문자열 패턴이나 숫자 범위, 정수/실수 구분 같은 세밀한 조건을 강제하기 어렵습니다.

 

이러한 한계를 보완하기 위해 선언형 스키마 기반의 Zod 검증 라이브러리를 사용합니다.

1. Zod란?

✅ 개념

• TypeScript 지원하는 런타임 검증 라이브러리
• 스키마 선언 후 parse, safeParse로 검증
• 검증 결과에 따라 타입 보장 + 에러 메시지 제공

2. 과제 적용 예시

2-1. 숫자야구 입력값 검증

import { z } from 'zod'

const BaseballInputSchema = z.string()
  .length(3, '3자리 숫자 입력 필요')
  .regex(/^[0-9]+$/, '숫자만 입력 가능')
  .refine(val => new Set(val).size === 3, '중복 숫자 불가')

const input = '123'
const parseResult = BaseballInputSchema.safeParse(input)
if (!parseResult.success) {
  console.error(parseResult.error.issues)
}

2-2. GitHub API 응답 검증

import { z } from 'zod'

const UserSchema = z.object({
  login: z.string(),
  id: z.number(),
  avatar_url: z.string().url(),
  name: z.string().nullable(),
  bio: z.string().nullable(),
  html_url: z.string().url(),
  followers: z.number(),
  following: z.number(),
})

async function fetchUser(user: string) {
  const res = await fetch(`https://api.github.com/users/${user}`)
  const json = await res.json()
  const result = UserSchema.safeParse(json)
  if (!result.success) {
    console.error(result.error.issues)
    return
  }
  return result.data
}

3. 장단점

✅ 장점

• 선언적 스키마로 코드 가독성↑
  • 스키마 선언만 보면 유효성 규칙을 한눈에 파악할 수 있어서 코드 읽기와 유지보수가 쉬워집니다.
• z.infer로 타입 자동 추론
  • 별도 인터페이스 작성 없이 스키마 기반으로 타입을 생성하므로 오타나 타입 불일치 위험을 줄입니다.
• 에러 메시지 자동 생성
  • 스키마 위반 시 Zod가 제공하는 이슈 객체(issues)로부터 구체적인 에러 정보를 얻어 사용자에게 직관적인 피드백을 제공할 수 있습니다.
• 일관된 에러 처리 가능
  • parse, safeParse 동일 API를 사용해 검증·에러를 처리하므로 전체 예외 처리 흐름을 통일할 수 있습니다.

❌ 단점

• 런타임 검증에 따른 퍼포먼스 오버헤드
  • 대용량 데이터나 빈번한 검증이 필요한 상황에서 실행 시간이 늘어나 렌더링 성능에 부담이 될 수 있습니다.
• 번들 크기 증가
  • Zod 라이브러리를 포함하면 클라이언트 번들 용량이 커져 초기 로딩 속도가 느려질 가능성이 있습니다.
• 학습 곡선 존재
  • Zod 스키마 작성 방식과 API를 익히는 과정이 필요해 팀 도입 초기 진입 장벽이 있을 수 있습니다.

---

참고하면 좋은 자료 !

• Zod 공식 문서
  • https://zod.dev/
• Zod GitHub
  • https://github.com/colinhacks/zod