유효성 체크 방법(3.0)

X2BEE 솔루션에서 Zod 라이브러리를 사용해 데이터 유효성을 검증하는 방법에 대해 안내합니다. 본 가이드는 스키마 정의, 필드별 유효성 검증, 전체 데이터 검증, 데이터 가공 및 타입 추론을 효율적으로 구현할 수 있는 방법을 설명합니다.

1. Zod 스키마 정의 방법

Zod 는 TypeScript를 우선으로 하는 스키마 선언 및 유효성 검증 라이브러리 이며, 중복된 유형 선언을 제거하기 위해 사용되는 라이브러리 입니다. Zod 를 통해 유효성 검사를 하고 Typescript 유형을 추론할 수 있습니다.

import {z} from 'zod'
/**
  기본적인 zod 객체 선은은 내부에 object 함수를 이용하여 객체를 생성하고 반환해줄 수 있습니다.
  Argument 로 객체를 던져주면 상수 형태의 zod schema 를 사용할 수 있게 됩니다.
  Argument 로 전달하는 객체의 경우 각 필드를 정의하고 타입을 zod 의 타입으로 정의해줘야 합니다.
**/
const zodExampleSchema = z.object({
  name: z.string(),
  userId: z.string(),
  password: z.string(),
  phone: z.number()
})

2. 각 필드별 유효성 체크 방법

zod 만으로는 단순 유효성 검사를 하는데 제한이 발생되기 때문에 각 항목에 대해서 자유도 있는 유효성 검사를 진행이 되어야 합니다. 모든 검사를 담을 수 없지만 기본적인 빈값을 체크하는 검증 방식은 아래와 같습니다.

import {z} from 'zod'
/**
  min, max... 등 다양한 기본 검증 방식들이 존재하지만, 자유도 있는 검증을 위해서 zod 내부에
  지원하고 있는 함수 refine 을 이용해서 필드에 들어온 데이터에 대해서 검증이 가능합니다.
  refine 에 Argument 는 첫번째 인자로는 검증 통과 여부이며, 두번째 인자로는 refine option 으로
  기본적으로 메시지 처리에 관련된 옵션을 전달 합니다.
**/
const zodExampleSchema = z.object({
  name: z.string().refine(
    (data) => !!data,                   // data 은 name 필드의 값을 의미한다. ( boolean 반환 )
    {
      message: "이름을 입력해주세요."        // message 값 전달
    }
  ),
  userId: z.string(),
  password: z.string(),
  phone: z.number()
})

3. 전체 필드를 대상으로 한 유효성 체크 방법

각 필드만 유효성 검사하는 경우 다른 값을 참조할 수 없는 이슈가 있습니다. 예를 들어 비밀번호 필드를 검증하는데 비밀번호 확인 필드를 참조하여 검증을 해야한다면 refine 만으로는 해당 검증을 할 수 없습니다. 그래서 사용하는 기능이 zod 에서 지원하는 superRefine 기능으로 사용 방법은 아래와 같습니다.

import {z} from 'zod'
/**
  superRefine 의 경우 각 객체에 적용하는 것이 아닌 zod object 를 대상으로 설정하는 것으로,
  아래와 같이 z.object 에 추가 옵션으로 superRefine 을 적용할 수 있습니다.
   Parameter 로 첫번째 인자는 전체 필드의 데이터를 갖고 있는 객체이며, 두번째 인자는 zod 에
   context 를 Parameter 로 전달받게 됩니다. 해당 항목을 통화여 검증 통과 여부를 boolean 형으로
   반환하게 됩니다.
**/
const zodExampleSchema = z.object({
  userId: z.string(),
  password: z.string(),
  rePassword: z.string()
}).superRefine((data, ctx) => {
  if(data.password !== data.rePassword) {
    ctx.addIssue({
      message: "비밀번호가 일치하지 않습니다.",
      code: z.ZodIssueCode.custom,
      path: ['password']
    })
    return false
  }
  return true
})

4. 최종 스키마 데이터 가공 방법

zod 검증 후 formData 로 전달이 되는 과정에서 데이터 변환 및 추가 부분이 발생할 수 있습니다. 그럴때 쓰는 기능으로 zod 에 transform 을 사용할 수 있으며, 검증 후 데이터를 스키마에서 반환할 때 최종값으로 볼 수 있습니다. 물론 검증 전에 데이터를 가공한 다음 superRefine 을 이용하여 유효성 검증도 가능합니다. transform 사용 방법은 아래와 같습니다.

import {z} from 'zod'
/**
  superRefine 의 경우 각 객체에 적용하는 것이 아닌 zod object 를 대상으로 설정하는 것으로,
  아래와 같이 z.object 에 추가 옵션으로 superRefine 을 적용할 수 있습니다.
   Parameter 로 첫번째 인자는 전체 필드의 데이터를 갖고 있는 객체이며, 두번째 인자는 zod 에
   context 를 Parameter 로 전달받게 됩니다. 해당 항목을 통화여 검증 통과 여부를 boolean 형으로
   반환하게 됩니다.
**/
const zodExampleSchema = z.object({
  userId: z.string().refine(
    (data) => !!data,
    {
      message: "아이디를 입력해주세요."
    }
  ),
  password: z.string(),
  rePassword: z.string()
}).superRefine((data, ctx) => {
  if(data.password !== data.rePassword) {
    ctx.addIssue({
      message: "비밀번호가 일치하지 않습니다.",
      code: z.ZodIssueCode.custom,
      path: ['password']
    })
    return false
  }
  return true
}).transform((data) => {
  return {
    userId: data.userId,
    password: data.password
  }
})

5. 타입 추론 방법

zod 에 스키마를 Typescript 로 변환하는 기능을 제공하고 있으며, 방법은 아래와 같습니다.

import {z} from 'zod'
/**
  Typescript 변환은 아래와 같습니다.
**/
const zodExampleSchema = z.object({
  ...
})
// Typescript
type zodExampleType = z.infer<typeof zodExampleSchema>