Zod로 유효성 검사 구현에 생산성을 더해보아요

date

Aug 27, 2024

slug

zod

author

status

Public

tags

Etc

summary

type

Post

thumbnail

category

updatedAt

Aug 3, 2025 02:07 PM

TypeScript를 사용하는데 왜 별도의 데이터 유효성 검사 라이브러리가 필요할까요?

TypeScript의 한계: 정적 타입 검사만 제공

컴파일 후 dist/ 폴더에 생성되는 파일은 전부 .js 확장자이며, 타입 정보는 포함되어 있지 않습니다.

💥 문제는 런타임에 발생합니다

• API가 예기치 않게 스펙을 바꾸었을 때

• 사용자가 예상치 못한 입력을 했을 때

• 타 시스템에서 전송된 데이터가 손상되었을 때

이러한 경우 런타임 오류가 발생하고, 이는 운영상의 장애로 이어질 수 있습니다.

그래서 필요한 것이 런타임 유효성 검사

1. 직접 검증 함수 구현

2. 유효성 검사 라이브러리 사용

런타임 데이터에 대한 유효성 검사를 구현하는데 생산성을 높여주는 라이브러리들

joi와 Avj는 우선 건너뜁시다

라이브러리 비교: Yup vs Zod

Yup

• 장점
• 스키마 정의 유연함
• Formik과의 높은 호환성 (공식 문서에서 추천) ‣
• 역사가 깊다 - yup은 Jun 25, 2016 / zod는 Apr 5, 2020
• repository star 22.7k

• 단점
• 타입스크립트와의 정적 타입 추론 부족
• then 기반의 체이닝 처리 → 코드 가독성 낮음
• strict()을 명시하지 않으면 암묵적 타입 변환 허용

import * as yup from 'yup';

const schema = yup.string();

schema.isValid(123).then(console.log); // ✅ true (숫자도 통과)

• 장점
• TS와 완벽한 통합 (타입 추론 가능)
• 의존성 없음 (경량)
package.lock.json을 보면 dependencies필드가 없는 것을 볼 수 있음.

//package.lock.json

		"node_modules/zod": {
			"version": "3.23.8",
			"resolved": "https://registry.npmjs.org/zod/-/zod-3.23.8.tgz",
			"integrity": "sha512-XBx9AXhXktjUqnepgTiE5flcKIYWi/rme0Eaj+5Y0lftuGBq+jyRu/md4WnuxqgP1ubdpNCsYEYPxrzVHD8d6g==",
			"funding": {
				"url": "https://github.com/sponsors/colinhacks"
			}
		}

• API 구문이 간결하고 직관적
• parse, safeParse API 제공 (에러 핸들링 분리)
• React Hook Form과의 강력한 조합
• release가 잦으며 업데이트 + 관리가 잘 되고있다. 현재 최신 version v3.23.8
• 검사에 더해 데이터 형변환도 지원
• repository star 33k

• 단점
• 스키마 정의 유연성은 Yup보다 약간 떨어질 수 있음

Zod를 선택한 이유

yup.string().isValid(333).then(console.log); // true

반면 Zod는 기본적으로 엄격한 타입 검사를 적용합니다. 실수로 숫자를 문자열로 받는 일을 미연에 방지할 수 있죠.

직접 검증 함수 구현하기 vs Zod

const emailValidation = (email: string) => {
  const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return regex.test(email);
};

Zod로 구현한 예

import { z } from 'zod';

const emailSchema = z.string().email({ message: "이메일 형식이 아닙니다." });

const result = emailSchema.safeParse(userInput);

if (!result.success) {
  console.error(result.error.format());
}

• emailSchema를 타입으로도 바로 사용할 수 있어 스키마와 타입 정의 일치

• safeParse를 사용해 런타임에서도 안전하게 검사 및 에러 핸들링 가능

Zod의 parse vs safeParse 언제, 왜 사용해야 할까?

팁

• parse()는 테스트 코드, seed 데이터, 내부 시스템 간 통신에서 주로 사용

• safeParse()는 사용자 입력 폼, 외부 API 응답, 클라이언트-서버 통신의 입력 처리 등 안전성이 필요한 영역에서 사용

코드 예시 비교

// 예외 발생 → try/catch 필요
try {
  const value = z.string().email().parse("not-an-email");
} catch (e) {
  console.error("유효하지 않은 이메일:", e);
}

// 조건 분기 → 흐름 제어가 깔끔함
const result = z.string().email().safeParse("not-an-email");
if (!result.success) {
  console.error("입력 오류:", result.error.format());

타입 따로 선언할 필요 없음! Zod의 타입 추론 활용

const userSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

// 타입 자동 추론
type User = z.infer<typeof userSchema>;

Zod 에러 메시지 커스터마이징과 format() 활용

const userSchema = z.object({
  email: z.string().email({ message: '이메일 형식이 아닙니다.' }),
  password: z.string().min(8, { message: '비밀번호는 최소 8자 이상이어야 합니다.' }),
});

const result = userSchema.safeParse(formData);

// 결과가 실패했을 경우, 각 필드별 메시지를 구조화된 형태로 제공
if (!result.success) {
  const errors = result.error.format();
  console.log(errors.email?._errors[0]); // "이메일 형식이 아닙니다."
}

이 구조는 react-hook-form과 연동할 때도 그대로 쓸 수 있어 UX 개선에 도움이 됩니다.

입력값 가공(Transform)도 가능

const schema = z.string().transform((val) => val.trim().toLowerCase());

const result = schema.safeParse("  ExAmPlE@Email.Com  ");
console.log(result.data); // "example@email.com"

• 이를 통해 입력값 정규화(standardization) 를 쉽게 처리할 수 있어 API 요청 전 데이터를 항상 일관된 상태로 유지 가능

merge, extend, partial, pick, omit 같은 스키마 조작 API

const baseUser = z.object({
  name: z.string(),
  email: z.string().email(),
});

const updateUser = baseUser.partial(); // 모든 필드를 선택적으로 바꿈
const createUser = baseUser.extend({
  password: z.string().min(8),
});

실무에서 어떻게 활용했을까?

• 특정 필드에 대한 검증 정책이 변경되었지만, 일부 입력값이 여전히 잘못된 형식으로 서버에 전송됨

• 필수 항목 누락 상태로 등록 시도가 이루어짐

• 그 결과, 운영팀이 직접 데이터를 수정해야 하는 수작업 업무가 지속적으로 발생

• 검증 로직이 여러 곳에 중복되어 변경사항을 반영하기 어려움

• 에러 메시지가 일관되지 않아 사용자 피드백이 불명확

• 테스트와 유지보수에 시간이 점점 더 많이 소요됨

🛠 그래서 어떻게 개선했나?

• Zod로 각 입력값에 대한 스키마를 명확하게 정의

• safeParse()를 사용해 검증 결과를 안전하게 분기 처리

• 실패한 경우, error.format()을 활용해 필드별 에러 메시지를 구조화하여 UI에 표시

// 실제 코드는 아닙니다.
const userSchema = z.object({
  email: z.string().email({ message: '이메일 형식이 아닙니다.' }),
  password: z.string().min(8, { message: '비밀번호는 최소 8자 이상이어야 합니다.' }),
});

const result = userSchema.safeParse(formData);

if (!result.success) {
  const errors = result.error.format();
  // errors.email._errors[0] 이런 식으로 UI에 표시 가능
}

• 모든 입력 검증 로직을 일원화 → 변경 시에도 한 곳만 수정하면 됨

• 검증 실패 메시지를 UI에 정확하고 일관되게 출력

• 클라이언트에서 잘못된 데이터가 아예 서버에 도달하지 않음 → 운영 리소스 절감

🔚 결론

• 타입스크립트와 완전히 통합된 스키마 정의

• safeParse, format() 등을 통한 UI와 자연스럽게 연동되는 에러 처리

• .transform(), .merge(), .partial() 등으로 복잡한 폼 스키마도 선언적으로 구성

• API 요청 전 단계에서 데이터 정합성을 강제할 수 있는 구조