[React, Next.js] Zod 라이브러리 추가하고 코드 작성해보자

 

 

 

사용자 선택 옵션을 검사하고
로또 결과 응답을 검증하기 위해
Zod 라이브러리를 추가했다.
Zod가 어떤 라이브러리인지 알아보고
코드 작성을 해보자

 

 

 

 

 

- 로또 번호 생성 마법진

로또 번호 생성 마법진

 

 

 

 

 

 

1. Zod

• TypeScript를 위한 스키마 선언 및 데이터 검증 라이브러리이다.
• 데이터가 우리가 원하는 형태와 규칙을 정확히 갖추고 있는지 검사해주는 도구이다.
• TypeScript는 컴파일 타임에만 타입을 검사해준다.
• 코드가 변환되어 실제로 웹브라우저나 서버에서 실행될 때는 순수한 JavaScript로 동작하기 때문에 타입 검사가 불가하다.
• 만약 서버 API에서 숫자를 보내주기로 했는데 실수로 문자를 보냈을 경우, TypeScript만으로는 실행 중에 앱이 고장나는 것을 막을 수 없다.
• 그래서 Zod는 이 프로그램 실행 중에 데이터가 올바른지 검사해주는 역할을 한다.
• Zod 사용 예시 : 외부 API 응답 데이터 검증, 사용자 입력 폼 검증, 백엔드 API 요청 검증, 환경 변수 검사 등이 있다.

 

 

 

---

 

 

 

 

2. 라이브러리 설치

npm install zod

 

 

 

 

---

 

 

 

 

 

3. lottoApi.ts

import { z } from 'zod';

z는 Zod의 기능을 모아둔 객체이다. import하면 아래의 것들을 만들 수 있다.

z.string()
z.number()
z.object(...)
z.array(...)​

이 중에 z.string은 이 데이터는 문자열이어야 한다는 걸 선언할 때 사용한다. 

 

export const LottoOptionsResponseSchema = z.object({
    options: z.array(z.string()),
});

서버에서 로또 옵션 목록을 받아올 때의 응답 모양을 검사하는 스키마이다. 

{
  options: ['개꿈', '행운', '내돈']
}​

이런 데이터만 통과하도록 한다. 왜냐면 z.object 때문인데, z.object는 이 데이터는 객체여야한다는 의미이다. 그래서 { } 이런 형태여야 한다.

Zod는 코드가 직관적이다. 보면 z.object는 { }을 의미하고 options가 있어야하며 그 안에는 문자열로 이뤄진 배열이 와야한다고 정의하고 있다. 그래서 실제로 받아올 때 응답 모양을 살펴보면 options: ['문자열1', '문자열2', '문자열3'] 이런 배열 구조가 된다.

 

export const DrawLottoRequestSchema = z.object({
    selectedOptions: z.array(z.string()).length(3),
});

로또 번호를 뽑을 때 서버로 보내는 요청 데이터의 모양이다. 위의 코드와 다른 점은  lengh(3)이 붙은 것이다. 배열의 길이가 정확히 3개여야 한다고 의미한다. 만약 2개나 4개의 배열이 온다면 그건 실패한다.

 

export const LottoDrawResponseSchema = z.object({
    numbers: z
        .array(z.number().int().min(1).max(45))
        .length(6)
        .refine(
            (numbers) => new Set(numbers).size === numbers.length,
            {
                message: '로또 번호는 중복될 수 없습니다.',
            }
        ),

    luckScore: z.number().int().min(0).max(100),
    luckMessage: z.string(),
    selectedOptions: z.array(z.string()).length(3),

    spellNumber: z.number().int().min(1).max(9),
    spellImageUrl: z.string(),
});

서버는 아래와 같은 모양으로 응답을 해야한다.

{
  numbers: [3, 11, 18, 24, 36, 42],
  luckScore: 87,
  luckMessage: '우주 통신 연결 완료',
  selectedOptions: ['개꿈', '행운', '내돈'],
  spellNumber: 5,
  spellImageUrl: '/images/spell5.png'
}

 

왜 이렇게 되는지 코드를 자세히 살펴보자.

numbers: z
    .array(z.number().int().min(1).max(45))
    .length(6)
    .refine(...)

로또 번호 6개를 검사한다. numbers는 배열 구조이면서, 1부터 45까지 이뤄진 숫자로 정수만 허용한다. 배열 전체 길이는 정확히 6개여야 한다. 

.refine(
    (numbers) => new Set(numbers).size === numbers.length,
    {
        message: '로또 번호는 중복될 수 없습니다.',
    }
)

.refine( )은 Zod가 기본으로 제공하는 검사만으로 부족할 때 직접 조건을 추가하는 기능이다. 여기서 중복 번호가 없어야한다는 규칙을 직접 만들었다.(로또는 중복 번호가 없으니) numbers에는 앞에서 검증된 배열이 들어온다. 이 배열을 new Set으로 바꾸면 중복이 제거된다. 만약 [1,2,3,4,5,5]가 들어왔다고 가정하자. set으로 바뀌면 [1,2,3,4,5]가 된다. 그래서 결국 size(5)가 number.length(6)와 맞지 않게되어서 검증에 실패하게된다.

그 다음 코드는 비슷한 구조이니 넘어가겠다.

 

export type LottoOptionsResponse = z.infer<typeof LottoOptionsResponseSchema>;
export type DrawLottoRequest = z.infer<typeof DrawLottoRequestSchema>;
export type LottoDrawResponse = z.infer<typeof LottoDrawResponseSchema>;

이 부분은 Zod 스키마를 TypeScript 타입으로 바꿔주는 코드가 된다. z.infer<typeof Schema>를 사용하면 스키마 정의에서 정적 TypeScript 타입을 추출할 수 있다고 한다. 

export const DrawLottoRequestSchema = z.object({
    selectedOptions: z.array(z.string()).length(3),
});​

 

이 코드를 Zod가 TypeScript 타입으로 만들어서 아래와 비슷한 타입이 된다.

type DrawLottoRequest = {
  selectedOptions: string[];
}​

Zod의 큰 장점은 스키마를 고치면 알아서 타입이 자동으로 따라 고쳐진다는 것이다. 

 

// Primses는 나중에 결과가 들어오는 곳으로
// 쉽게 설명하면 나중에 결과 줄게 하고 약속하는 느낌으로 사용해서 Promise를 반환한다.
// 왜 나중에 받냐? fetch 때문이다.
// 서버 응답은 바로 오지 않아서, 응답이 올 때까지 멈춰있지 않고 Promise로 예약을 걸어둔다.
export async function getLottoOptions(): Promise<LottoOptionsResponse> {
    const response = await fetch(createApiUrl('/api/lotto/options'));

    if (!response.ok) {
        const message = await getErrorMessage(response);
        throw new Error(message);
    }

    const data = await response.json();

    return LottoOptionsResponseSchema.parse(data);
}

여기서 Zod가 실제로 일을 한다.

    const data = await response.json();​

서버에서 받은 JSON을 JavaScript 객체로 바꿔준다. 그런데 이때의 data는 믿을 수 없는 데이터이다. 그래서 이제 이 코드를 검사해야한다.

LottoOptionsResponseSchema.parse(data)

.parse( )는 입력값을 스키마에 맞게 검증하고 맞은면 타입이 보장된 값을 반환한다. 검증에 실패하면 ZodError를 던진다.

 

 

- lottoApi.ts 전체 코드

lotto-magic-frontend/lib/api/lottoApi.ts at main · hyeong-ing/lotto-magic-frontend

 

 

 

 

---

 

 

 

 

4. ResultPage.tsx

import {
    LottoDrawResponseSchema,
    type LottoDrawResponse,
} from '@/lib/api/lottoApi';

ResultPage는 Zod와 이렇게 연결시켰다. 아까 만들었던 lottoApi에서 Zod 스키마와 Zod로 만든 타입을 가져와서 사용할 것이다.

 

    useEffect(() => {
        // 결과를 잠깐 sessionStorage로 저장한다.
        // 새로고침해도 같은 화면이 보이도록 했다.
        const savedResult = sessionStorage.getItem('lotto-result');
        
        // 저장된 결과가 없으면 토스트 나타나고
        // 루트 화면으로 이동시킨다.
        if (!savedResult) {
            showMagicToast('저장된 결과가 없어요.');
            router.replace('/');
            return;
        }

        try {
            // 
            const parsedJson = JSON.parse(savedResult);
            const safeResult = LottoDrawResponseSchema.parse(parsedJson);

            setResult(safeResult);
        } catch (error) {
            // 에러 발생시 콘솔에 어떤 에러인지 보여준다.
            console.error(error);
            
            // 그리고 sessionStorage에 저장된 결과값을 지운다.
            sessionStorage.removeItem('lotto-result');
            // 토스트로 사용자에게 보여주고
            showMagicToast('결과 정보를 읽지 못했어요.');
            // 루트 화면으로 보낸다.
            router.replace('/');
        }
    }, [router]);

const parsedJson = JSON.parse(savedResult);
const safeResult = LottoDrawResponseSchema.parse(parsedJson);

setResult(safeResult);

Zod가 실제로 동작하는 부분은 위의 코드이다. sessionStorage에 저장된 데이터는 문자열이다.

'{"numbers":[1,2,3,4,5,6],"luckScore":80,...}'

대충 이런식으로 저장되어 있을 것이다. 이는 객체처럼 보여도 문자열이다. 

const parsedJson = JSON.parse(savedResult);

그래서 JavaScript 객체로 바꾸기 위해 위의 코드를 작성했다. JSON.parse( ) 메서드는 JSON 문자열의 구문을 분석하고 그 결과에서 JavaScript 값이나 객체를 생성한다. 

const safeResult = LottoDrawResponseSchema.parse(parsedJson);

이 코드에서 Zod 스키마로 검사가 이뤄진다. parsedJson이 LottoDrawResponseSchema 규칙에 맞는지 검사하고, 맞으면 safeResult에 올바른 로또 결과 데이터가 들어간다.

 

 

 

- JSON.parse( )

JSON.parse() - JavaScript | MDN

 

 

 

- ResultPage.tsx 전체코드

lotto-magic-frontend/components/result/ResultPage.tsx at main · hyeong-ing/lotto-magic-frontend