Zod 사용법: 타입스크립트 유효성 검사를 쉽게 하는 방법 (1)

Zod 라이브러리로 타입스크립트 유효성 검사를 간단하게 설정하는 방법을 알아봅니다.

Zod 사용법: 타입스크립트 유효성 검사를 쉽게 하는 방법

1. Zod란 무엇인가?

Zod는 타입스크립트와 함께 사용하기 좋은 유효성 검사 및 스키마 정의 라이브러리입니다. 간단한 문법으로 데이터를 정의하고, 타입 검증을 통해 런타임 오류를 예방할 수 있습니다. 특히 타입스크립트와의 자연스러운 통합이 가능해 타입 안전성을 극대화하는 데 도움을 줍니다.

1.1. Zod를 사용하는 이유

TypeScript 자체는 정적 타입 검사를 제공하지만, 런타임에서 데이터를 확인하지 않습니다. Zod를 사용하는 이유는 다음과 같습니다:

1. 유효성 검사 (Validation): API 요청이나 외부 데이터(예: 사용자 입력, 서버 응답 등)를 받을 때 데이터의 형식을 유효성 검사하기 위해 사용합니다. Zod는 런타임에서 데이터를 검증하고, 원하는 타입이 맞는지 확인할 수 있습니다. 이는 잘못된 데이터로 인해 발생할 수 있는 오류를 줄이는 데 도움이 됩니다.
2. 타입 안전성 (Type Safety): Zod는 스키마를 정의하면서 TypeScript 타입도 생성할 수 있습니다. 즉, Zod 스키마를 작성하면 해당 스키마에서 자동으로 TypeScript 타입이 유추되기 때문에, 별도로 타입 정의와 유효성 검사를 관리하지 않아도 됩니다. 이렇게 하면 중복 코드가 줄어들고, 타입 안전성을 유지하기 쉬워집니다.
3. 런타임 타입 검증: TypeScript는 컴파일 타임에 타입 검사를 하지만, 런타임에 실제 데이터의 타입을 확인하지는 않습니다. Zod는 이러한 런타임 상황에서 데이터가 예상하는 구조인지 확인하는 기능을 제공합니다. 이를 통해 서버와 클라이언트 간의 데이터 교환 시 안전성을 높일 수 있습니다.
4. 개발자 경험: Zod는 직관적이고 사용하기 쉬운 API를 제공하며, TypeScript와 잘 통합되어 있어 개발자 경험을 개선시킵니다. 스키마를 정의하고 이를 기반으로 데이터의 유효성을 검증하는 과정이 명확하고 간결합니다.

1.2. Zod의 주요 특징

• 직관적인 API: 코드가 간결하고 직관적이어서 쉽게 배울 수 있습니다.
• 타입스크립트 통합: 타입스크립트와의 완벽한 호환성을 제공합니다.
• 커스텀 유효성 검사: 개발자가 필요에 따라 커스텀 유효성 검사를 추가할 수 있습니다.

2. Zod 설치 및 시작하기

2.1. Zod 설치하기

Zod를 사용하기 위해서는 먼저 프로젝트에 설치해야 합니다. 설치는 간단히 npm을 이용하여 할 수 있습니다:

npm install zod

2.2. 기본 사용 예제

설치가 완료되었다면, Zod의 사용법을 알아보겠습니다. 아래는 문자열을 검증하는 기본 예제입니다:

import { z } from 'zod';

const nameSchema = z.string();
nameSchema.parse('John Doe');  // 성공: 문자열 입력
nameSchema.parse(123);         // 오류: 입력값이 문자열이 아님

이 코드에서 nameSchema는 문자열 타입을 검증하는 스키마입니다. parse() 메서드를 사용하여 값의 유효성을 확인할 수 있습니다. 만약 타입이 맞지 않으면 오류가 발생하여 런타임에서 안전성을 확보할 수 있습니다.

3. 다양한 Zod 스키마 예제

타입스크립트에서 유효성 검사를 구현하기 위해 다양한 데이터 구조에 대한 스키마 정의가 필요합니다. Zod는 이를 간단하고 직관적으로 구현할 수 있도록 다양한 유효성 검사 기능을 제공하는데, 이번 섹션에서는 객체, 배열, 복합 데이터 타입을 정의하고 검증하는 여러 예제를 자세히 살펴보겠습니다.

3.1 객체 스키마 정의

객체는 개발에서 가장 자주 사용하는 데이터 구조 중 하나입니다. Zod를 사용하면 객체의 각 필드에 대해 세밀한 검증이 가능하여, 예상치 못한 오류를 미리 방지할 수 있습니다. 여기서는 사용자 정보를 포함하는 객체를 정의하는 예제를 다뤄 보겠습니다.

3.1.1 사용자 객체 정의

아래와 같은 구조의 사용자 객체가 있다고 가정해봅시다. 이 객체는 name, age, email을 포함하고 있으며 각각 문자열, 숫자, 이메일 형식이어야 합니다.

const userSchema = z.object({
  name: z.string(),
  age: z.number().min(18, { message: "나이는 최소 18세 이상이어야 합니다." }),
  email: z.string().email({ message: "유효한 이메일 주소여야 합니다." }),
});

try {
  userSchema.parse({
    name: "Alice",
    age: 25,
    email: "alice@example.com",
  });
  console.log("유효한 사용자 데이터입니다.");
} catch (e) {
  console.error(e.errors);
}

• name은 반드시 문자열이어야 합니다.
• age는 18세 이상이어야 하며, 그렇지 않을 경우 오류 메시지를 표시합니다.
• email은 이메일 형식이어야 하며, 잘못된 형식일 경우 관련 메시지를 보여줍니다.

이러한 구조를 통해 객체의 모든 필드에 대해 세밀한 유효성 검사를 수행할 수 있습니다.

3.1.2 선택적 필드와 기본값

필요에 따라 객체의 필드를 선택적으로 만들거나 기본값을 지정할 수 있습니다. 예를 들어, 사용자의 nickname 필드는 선택적으로 설정할 수 있고 기본값을 지정하려면 다음과 같이 할 수 있습니다:

const extendedUserSchema = userSchema.extend({
  nickname: z.string().optional().default("Anonymous"),
});

extendedUserSchema.parse({
  name: "Bob",
  age: 30,
  email: "bob@example.com",
}); // ni

이렇게 하면 nickname 필드가 없을 경우 자동으로 "Anonymous"가 할당되어 사용됩니다.

3.2 배열 스키마 정의

배열 데이터 구조에 대해서도 Zod를 사용하면 쉽게 스키마를 정의할 수 있습니다. 예를 들어 숫자의 배열을 정의하고, 각 요소가 양수인지 검증하는 예제를 살펴보겠습니다.

3.2.1 기본 배열 검증

const numberArraySchema = z.array(z.number().positive());

try {
  numberArraySchema.parse([1, 2, 3]); // 성공
  numberArraySchema.parse([1, -2, 3]); // 오류: 배열에 음수가 포함됨
} catch (e) {
  console.error(e.errors);
}

 

• z.array(z.number().positive())를 통해 배열의 각 요소가 양수인지 검증합니다.
• 만약 음수가 포함되어 있다면 parse() 함수는 오류를 발생시키며, 오류 내용은 e.errors에 담깁니다.

3.2.2 배열의 길이 제한

배열의 길이를 제한하는 것도 가능합니다. 예를 들어, 최대 5개의 요소를 허용하는 배열을 정의하려면 다음과 같이 작성할 수 있습니다.

const limitedArraySchema = z.array(z.string()).max(5, { message: "배열은 최대 5개의 요소를 가질 수 있습니다." });

try {
  limitedArraySchema.parse(["a", "b", "c", "d", "e", "f"]); // 오류 발생
} catch (e) {
  console.error(e.errors);
}

 

이 예제에서는 배열의 최대 길이를 제한하고, 초과할 경우 사용자에게 명확한 오류 메시지를 제공합니다.

3.3 복합 스키마 정의

객체와 배열이 혼합된 데이터 구조를 검증할 때 Zod는 매우 유용합니다. 예를 들어 사용자의 친구 목록을 포함하는 복합 데이터 구조를 정의해 보겠습니다.

3.3.1 객체 내 배열

사용자 객체에 friends라는 배열이 추가된 복합 스키마를 만들어보겠습니다. 각 친구는 name과 age를 포함하는 객체로 정의됩니다.

const userWithFriendsSchema = z.object({
  name: z.string(),
  age: z.number().min(18),
  friends: z.array(
    z.object({
      name: z.string(),
      age: z.number().min(0),
    })
  ),
});

try {
  userWithFriendsSchema.parse({
    name: "Charlie",
    age: 28,
    friends: [
      { name: "Dave", age: 27 },
      { name: "Eve", age: 25 },
    ],
  });
  console.log("유효한 사용자와 친구 목록입니다.");
} catch (e) {
  console.error(e.errors);
}

• friends 필드는 배열이며, 각 요소는 name과 age 필드를 갖는 객체로 구성됩니다.
• 이렇게 하면 복잡한 데이터 구조를 유효하게 검증할 수 있습니다.

3.4 중첩된 스키마와 재사용성

Zod는 복합적인 스키마를 정의할 때 재사용성을 높일 수 있는 구조를 제공합니다. 특정 스키마를 여러 곳에서 재사용하고 싶을 때, 다음과 같이 정의할 수 있습니다.

const friendSchema = z.object({
  name: z.string(),
  age: z.number().min(0),
});

const userWithReusableFriendsSchema = z.object({
  name: z.string(),
  age: z.number().min(18),
  friends: z.array(friendSchema),
});

이렇게 하면 friendSchema를 정의하고 이를 다른 객체에서 재사용하여 유지보수성을 높이고, 코드의 가독성을 향상시킬 수 있습니다.

 

위에서 살펴본 다양한 Zod 스키마 예제들은 복잡한 데이터 구조의 유효성 검증을 쉽고 명확하게 구현할 수 있도록 도와줍니다. Zod는 직관적인 문법과 유연한 스키마 설정을 통해 타입 안전성을 높입니다. 다음 글에서는 Zod의 다양한 메소드에 대해서 좀 더 알아보겠습니다.

 

다음글: https://johnny-developer-story.tistory.com/46

Zod 사용법: 타입스크립트 유효성 검사를 쉽게 하는 방법 (2)

참고: https://www.daleseo.com/zod-schema/

Zod를 통한 타입스크립트 친화적인 스키마 정의