zod로 타입검증과 런타임 유효성 검사하기

프로젝트 개발 중 데이터 유효성 검사와 타입 안전성이 중요한 요구사항으로 떠올랐습니다. 특히, 서버에서 전달받는 데이터의 구조와 타입이 정확히 일치하는지 확인하는 작업은 프론트엔드의 안정성과 신뢰성을 높이는 데 매우 중요합니다. 이를 위해 Zod를 도입했으며, Zod를 활용한 방식과 기존 TypeScript만 사용했을 때의 차이점, 그리고 Zod의 장점에 대해 정리해보겠습니다.

TypeScript는 정적 타입 검사와 인터페이스, 타입을 통해 데이터의 구조를 정의하고 타입 안전성을 제공합니다. 예를 들어, 서버에서 받아오는 데이터를 TypeScript 타입으로 정의하는 방식은 다음과 같았습니다.

type DrugOverview = {
  id: number;
  type: "VITAMIN" | "ETC_MEDICINE" | "OTC_MEDICINE";
  imageUrl: string | null;
  classificationOrManufacturer: string;
  name: string;
  categories: string[];
};

이 방식은 개발 중 데이터 타입을 명확히 정의할 수 있는 장점이 있지만, 런타임에서는 타입 검증이 불가능하다는 치명적인 단점이 있었습니다. 서버로부터 잘못된 데이터가 전달되어도 코드 상에서 이를 인지하지 못해 예기치 않은 오류가 발생할 가능성이 있었습니다.

Zod는 런타임에서의 데이터 유효성 검사를 지원하는 TypeScript 친화적인 스키마 선언 및 검증 라이브러리입니다. TypeScript만 사용할 때의 한계를 보완하며, 다음과 같은 이유로 도입하게 되었습니다

1. 런타임 데이터 검증 TypeScript는 정적 타입 검사만 가능하지만, Zod는 서버에서 전달받은 데이터를 런타임에서 검증할 수 있어 데이터의 신뢰성을 높입니다.
2. 타입 정의와 유효성 검사를 한 번에 관리 Zod 스키마를 정의하면 타입 정의와 유효성 검사를 동시에 처리할 수 있어 코드 중복을 줄이고 일관성을 유지할 수 있습니다.
3. 간단하고 직관적인 API Zod의 API는 선언적이고 간결하여 빠르게 익히고 적용할 수 있었습니다.

Zod를 사용하면 데이터 스키마를 선언하고, 이를 기반으로 타입을 추론할 수 있습니다. 예를 들어, 아래는 약물 정보 데이터에 대한 스키마 정의와 타입 추론 방식입니다.

import { z } from "zod";

// 약물 개요 정보 스키마
export const DrugOverviewDtoSchema = z.object({
  id: z.number(),
  type: z.enum(["VITAMIN", "ETC_MEDICINE", "OTC_MEDICINE"]),
  imageUrl: z.string().nullable(),
  classificationOrManufacturer: z.string(),
  name: z.string(),
  categories: z.array(z.string()),
});

// 데이터 리스트와 페이지 정보 스키마
export const DrugOverviewListDtoSchema = z.object({
  pageInfo: z.object({
    totalPage: z.number(),
    currentPage: z.number(),
    totalCnt: z.number(),
    currentCnt: z.number(),
  }),
  drugs: z.array(DrugOverviewDtoSchema),
});

// TypeScript 타입 추론
export type DrugOverviewListDto = z.infer<typeof DrugOverviewListDtoSchema>;
export type DrugOverview = z.infer<typeof DrugOverviewDtoSchema>;

Zod의 가장 큰 장점 중 하나는 런타임 유효성 검사입니다. 이를 더욱 자동화하기 위해 Axios의 Response Interceptor에 Zod의 parse 메서드를 등록하여 모든 API 응답 데이터를 검증하도록 설정했습니다. 이 방식은 다음과 같은 장점을 제공합니다:

1. 검증 자동화 모든 API 응답에 대해 Zod 검증을 자동으로 수행하므로, 추가적인 검증 로직을 작성하지 않아도 됩니다.
2. 코드 중복 제거 각 요청별로 개별 검증 코드를 작성할 필요가 없어, 코드가 간결하고 유지 보수하기 쉬워집니다.
3. 신뢰성 강화 응답 데이터가 예상한 구조와 다를 경우, 즉시 오류를 발생시켜 디버깅을 용이하게 하고 데이터 무결성을 유지합니다.

1. 런타임 유효성 검사 Zod 스키마를 통해 서버로부터 전달받은 데이터를 검증할 수 있습니다. Interceptor와 함께 사용하면 응답 데이터를 일관되게 검증할 수 있습니다.
2. 타입 안전성 향상 Zod 스키마에서 추론된 타입은 TypeScript 타입과 완벽히 호환됩니다. 따라서 별도의 타입 정의 없이도 스키마에서 타입을 생성하고 안전하게 사용할 수 있습니다.
3. 코드 중복 감소 기존 방식에서는 타입 정의와 별도로 유효성 검사 로직을 작성해야 했지만, Zod는 스키마를 통해 이 두 가지를 한 번에 처리할 수 있어 코드 중복이 크게 줄어들었습니다.

기존 TypeScript 방식과의 비교

특징	기존 TypeScript	Zod
타입 정의	지원	지원
유효성 검사	미지원	지원
런타임 검증	불가능	가능
코드 중복 여부	있음	없음
복잡한 데이터 구조 관리	제한적	직관적 선언 가능

Zod와 Axios Interceptor를 결합하여 데이터 검증 과정을 자동화하면서 런타임 타입 안전성을 강화할 수 있었습니다. 이를 통해 코드의 일관성을 유지하면서도 데이터 검증에 대한 신뢰성을 높였습니다.

데이터 구조가 복잡하거나 서버와의 데이터 통신에서 타입 안전성이 중요한 프로젝트라면, Zod와 Interceptor를 활용한 이 접근법은 강력한 솔루션이 될 것입니다.