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

Zod의 다양한 스키마 유틸리티 메소드 사용법

Zod는 유효성 검사를 위한 스키마 라이브러리로, 다양한 유틸리티 메소드를 통해 타입스크립트의 데이터 검증을 더욱 간편하게 수행할 수 있습니다. 이번 포스트에서는 Zod의 pick() 메소드를 중심으로, omit(), extend(), merge() 등 여러 메소드를 사용해 유연하게 스키마를 조작하는 방법을 알아보겠습니다.

1. Zod의 Pick 메소드란?

pick() 메소드는 기존 스키마에서 특정 필드만을 선택하여 새로운 스키마를 생성할 때 사용됩니다. 이는 기존의 스키마를 재사용하면서 필요한 부분만 가져올 때 매우 유용합니다.

1.1 기본 사용 예제

아래는 사용자 정보를 정의한 userSchema에서 일부 필드만 선택하여 새로운 스키마를 만드는 예제입니다:

import { z } from 'zod';

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

const basicUserSchema = userSchema.pick({
  name: true,
  email: true,
});

basicUserSchema.parse({
  name: "Alice",
  email: "alice@example.com",
}); // 성공

• userSchema: 전체 사용자 정보를 포함하는 기본 스키마입니다.
• basicUserSchema: name과 email 필드만을 선택하여 새로운 스키마를 만듭니다.

pick() 메소드를 사용하면 필요한 정보만 추출해 새 스키마를 정의할 수 있어, 여러 상황에서 반복적인 스키마 정의를 줄일 수 있습니다.

2. Zod의 Omit 메소드

omit() 메소드는 기존 스키마에서 특정 필드를 제외하고 나머지 필드로 새로운 스키마를 생성하는 데 사용됩니다. pick()과 반대로 동작하며, 불필요하거나 보안상 문제가 될 수 있는 필드를 제거할 때 유용합니다.

2.1 기본 사용 예제

다음은 userSchema에서 address 필드를 제외하고 나머지 필드로 새로운 스키마를 만드는 예제입니다:

const userWithoutAddressSchema = userSchema.omit({
  address: true,
});

userWithoutAddressSchema.parse({
  name: "Charlie",
  age: 30,
  email: "charlie@example.com",
}); // 성공

• omit() 메소드를 사용하여 address 필드를 제외한 스키마를 생성합니다.
• 보안 또는 기타 이유로 특정 데이터를 포함하지 않도록 스키마를 간편하게 재사용할 수 있습니다.

2.2 활용 사례: 관리자와 일반 사용자 스키마 구분

관리자 계정과 일반 사용자 계정이 서로 다른 필드를 필요로 할 때, omit() 메소드를 통해 이러한 요구사항을 충족할 수 있습니다:

const adminUserSchema = userSchema.omit({
  age: true,  // 나이 정보가 관리자에는 필요 없을 수 있음
});

이처럼 특정 필드를 제외하여 관리자가 다룰 수 있는 데이터 범위를 제한하는 식으로 사용할 수 있습니다.

3. Zod의 Extend 메소드

extend() 메소드는 기존 스키마에 새로운 필드를 추가하는 데 사용됩니다. 기존 스키마를 바탕으로 확장된 스키마를 정의할 때 매우 유용합니다.

3.1 기본 사용 예제

다음은 사용자 스키마에 role 필드를 추가하여 관리자를 정의하는 예제입니다:

const adminSchema = userSchema.extend({
  role: z.enum(["admin", "user"]),
});

adminSchema.parse({
  name: "David",
  age: 35,
  email: "david@example.com",
  address: "123 Main St",
  role: "admin",
}); // 성공

• extend()를 사용하여 role 필드를 추가함으로써 사용자 스키마를 더욱 확장했습니다.
• 이 방식으로 스키마를 확장하여 다양한 역할 또는 권한을 정의할 수 있습니다.

4. Zod의 Merge 메소드

merge() 메소드는 두 개의 스키마를 합치는 기능을 제공합니다. 서로 다른 두 데이터 구조를 하나로 합쳐야 할 때 유용합니다.

4.1 기본 사용 예제

다음은 사용자 정보와 직장 정보를 합쳐 하나의 스키마로 만드는 예제입니다:

const workSchema = z.object({
  company: z.string(),
  position: z.string(),
});

const userWithWorkSchema = userSchema.merge(workSchema);

userWithWorkSchema.parse({
  name: "Eve",
  age: 28,
  email: "eve@example.com",
  address: "456 Another St",
  company: "TechCorp",
  position: "Engineer",
}); // 성공

• **merge()**를 사용하여 userSchema와 workSchema를 합칩니다.
• 두 스키마의 필드를 모두 포함한 새로운 스키마를 만들어 다양한 데이터 구조를 하나로 관리할 수 있습니다.

5. Zod의 Partial과 Strict

5.1 Partial: 선택적 필드로 변경

partial() 메소드는 모든 필드를 선택적으로 만드는 데 사용됩니다. 이를 통해 전체 필드를 필수로 지정할 필요 없이 필요에 따라 선택적으로 입력할 수 있도록 합니다.

const partialUserSchema = userSchema.partial();

partialUserSchema.parse({
  email: "partial@example.com",
});

5.2 Strict: 필드 엄격 제어

반면, strict() 메소드는 정의되지 않은 필드가 포함될 경우 오류를 발생시킵니다. 이는 데이터의 무결성을 엄격하게 유지하고자 할 때 유용합니다.

const strictUserSchema = userSchema.strict();

try {
  strictUserSchema.parse({
    name: "Frank",
    age: 29,
    email: "frank@example.com",
    unknownField: "should not be here", // 오류 발생
  });
} catch (e) {
  console.error(e.errors); // 오류: 정의되지 않은 필드 포함
}

• **strict()**를 통해 예상치 못한 필드가 포함되지 않도록 보장할 수 있습니다.

6. 요약

Zod의 다양한 유틸리티 메소드 (pick(), omit(), extend(), merge(), partial(), strict())는 복잡한 데이터 구조를 손쉽게 정의하고 조작할 수 있도록 도와줍니다. 각 메소드는 특정 상황에서 데이터의 유효성을 더욱 유연하게 관리하는 데 유용하며, 이를 통해 개발자는 코드의 반복을 줄이고 유지보수성을 높일 수 있습니다.

• pick(): 필요한 필드만 선택하여 새로운 스키마 생성
• omit(): 특정 필드를 제외한 스키마 생성
• extend(): 스키마에 새로운 필드 추가
• merge(): 두 스키마를 합쳐 새로운 구조 생성
• partial(): 모든 필드를 선택적으로 변경
• strict(): 정의되지 않은 필드를 허용하지 않음

Zod의 이러한 기능들은 타입스크립트와의 통합을 통해 런타임 안전성을 높이며, 데이터를 효율적으로 관리하는 데 큰 도움이 됩니다. 다음 글에서는 Zod로 커스텀 유효성 검사를 만드는 방법에 대해서 알아봅니다.

 

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

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

 

참고: https://zod.dev/

GitHub - colinhacks/zod: TypeScript-first schema validation with static type inference