런타임 입력 검증: TypeScript 타입만으로 API 응답을 믿을 수 없는 이유

pnpm add [email protected]
pnpm add -D [email protected] @types/[email protected] @types/[email protected]

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "jsx": "react-jsx",
    "strict": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "noEmit": true
  },
  "include": ["src"]
}

export const VALID_PRODUCT_PAYLOAD = {
  id: 'note-1',
  display_name: '불변 업데이트 노트',
  price: { amount: 12900, currency: 'KRW' },
  inventory: { status: 'available' },
}
 
const INVALID_PRODUCT_PAYLOAD = {
  id: 'note-1',
  display_name: '불변 업데이트 노트',
  price: { amount: '12900', currency: 'KRW' },
  inventory: null,
}
 
const RESPONSE_VERSION: string = 'invalid'
 
export interface JsonResponse {
  ok: boolean
  status: number
  json(): Promise<unknown>
}
 
export async function fakeFetchProduct(): Promise<JsonResponse> {
  return {
    ok: true,
    status: 200,
    async json() {
      return RESPONSE_VERSION === 'valid'
        ? VALID_PRODUCT_PAYLOAD
        : INVALID_PRODUCT_PAYLOAD
    },
  }
}

import { fakeFetchProduct, type JsonResponse } from './fake-product-server'
 
type ProductResponse = {
  id: string
  display_name: string
  price: { amount: number; currency: 'KRW' }
  inventory: { status: 'available' | 'sold_out' }
}
 
type ProductRequest = () => Promise<JsonResponse>
 
export async function fetchProductResponseBad(
  request: ProductRequest = fakeFetchProduct,
): Promise<ProductResponse> {
  const response = await request()
  if (!response.ok) throw new Error(`HTTP ${response.status}`)
 
  return (await response.json()) as ProductResponse
}

import { useQuery } from '@tanstack/react-query'
import { fetchProductResponseBad } from './product-api-bad'
import { toProductCardViewModel } from './product-card-view-model'
 
export default function ProductCardBad() {
  const productQuery = useQuery({
    queryKey: ['product', 'note-1', 'bad'],
    queryFn: () => fetchProductResponseBad(),
    retry: false,
  })
 
  if (productQuery.isPending) return <p>불러오는 중</p>
  if (productQuery.isError) return <p>상품을 불러오지 못했습니다.</p>
 
  const product = toProductCardViewModel(productQuery.data)
 
  return <p>{product.name}</p>
}

const input: unknown = await response.json()
 
// input.inventory.status
// 오류: input은 아직 unknown이다.

import * as z from 'zod'
 
export const ProductResponseSchema = z.object({
  id: z.string().min(1),
  display_name: z.string().min(1),
  price: z.object({
    amount: z.number().int().nonnegative(),
    currency: z.literal('KRW'),
  }),
  inventory: z.object({
    status: z.enum(['available', 'sold_out']),
  }),
})
 
export type ProductResponse = z.infer<typeof ProductResponseSchema>

import type { ProductResponse } from './product-response'
 
export type ProductCardViewModel = {
  id: string
  name: string
  priceText: string
  canBuy: boolean
  availabilityText: string
}
 
export function toProductCardViewModel(
  productResponse: ProductResponse,
): ProductCardViewModel {
  const canBuy = productResponse.inventory.status === 'available'
 
  return {
    id: productResponse.id,
    name: productResponse.display_name,
    priceText: `${productResponse.price.amount.toLocaleString('ko-KR')}원`,
    canBuy,
    availabilityText: canBuy ? '구매 가능' : '구매 불가',
  }
}

import * as z from 'zod'
import { fakeFetchProduct, type JsonResponse } from './fake-product-server'
import { ProductResponseSchema } from './product-response'
 
type ProductRequest = () => Promise<JsonResponse>
 
export class ProductContractError extends Error {
  readonly issues: Array<{ path: string; code: string }>
 
  constructor(error: z.ZodError) {
    super('상품 응답 형식이 예상과 다릅니다.')
    this.name = 'ProductContractError'
    this.issues = error.issues.map((issue) => ({
      path: issue.path.join('.'),
      code: issue.code,
    }))
  }
}
 
export async function fetchProductResponse(
  request: ProductRequest = fakeFetchProduct,
) {
  const response = await request()
  if (!response.ok) throw new Error(`HTTP ${response.status}`)
 
  const input: unknown = await response.json()
  const result = ProductResponseSchema.safeParse(input)
 
  if (!result.success) {
    throw new ProductContractError(result.error)
  }
 
  return result.data
}

import { useQuery } from '@tanstack/react-query'
import {
  fetchProductResponse,
  ProductContractError,
} from './product-api'
import { toProductCardViewModel } from './product-card-view-model'
 
export default function ProductCard() {
  const productQuery = useQuery({
    queryKey: ['product', 'note-1'],
    queryFn: () => fetchProductResponse(),
    select: toProductCardViewModel,
    retry: false,
  })
 
  if (productQuery.isPending) return <p>불러오는 중</p>
 
  if (productQuery.isError) {
    const message = productQuery.error instanceof ProductContractError
      ? '상품 정보를 확인하고 있습니다. 잠시 후 다시 시도해 주세요.'
      : '상품을 불러오지 못했습니다.'
 
    return <p>{message}</p>
  }
 
  const product = productQuery.data
 
  return (
    <article>
      <h2>{product.name}</h2>
      <p>{product.priceText}</p>
      <p>{product.availabilityText}</p>
      <button disabled={!product.canBuy}>구매하기</button>
    </article>
  )
}

retry(failureCount, error) {
  if (error instanceof ProductContractError) return false
  return failureCount < 2
}

응답 본문 unknown
    ↓ ProductResponseSchema.safeParse
검증된 ProductResponse
    ↓ toProductCardViewModel
ProductCardViewModel
    ↓ React Render
화면

import { describe, expect, test } from 'vitest'
import {
  fetchProductResponse,
  ProductContractError,
} from './product-api'
import { ProductResponseSchema } from './product-response'
 
const validProduct = {
  id: 'note-1',
  display_name: '불변 업데이트 노트',
  price: { amount: 12900, currency: 'KRW' },
  inventory: { status: 'available' },
}
 
describe('ProductResponseSchema', () => {
  test('현재 상품 응답을 허용한다', () => {
    expect(ProductResponseSchema.safeParse(validProduct).success).toBe(true)
  })
 
  test('문자열 가격을 price.amount에서 거절한다', () => {
    const result = ProductResponseSchema.safeParse({
      ...validProduct,
      price: { amount: '12900', currency: 'KRW' },
    })
 
    expect(result.success).toBe(false)
    if (result.success) return
    expect(result.error.issues[0]?.path).toEqual(['price', 'amount'])
  })
 
  test('null 재고를 inventory에서 거절한다', () => {
    const result = ProductResponseSchema.safeParse({
      ...validProduct,
      inventory: null,
    })
 
    expect(result.success).toBe(false)
    if (result.success) return
    expect(result.error.issues[0]?.path).toEqual(['inventory'])
  })
 
  test('API 경계에서 안전한 issue 경로와 코드만 남긴다', async () => {
    expect.assertions(2)
 
    try {
      await fetchProductResponse(async () => ({
        ok: true,
        status: 200,
        async json() {
          return {
            ...validProduct,
            price: { amount: '12900', currency: 'KRW' },
            inventory: null,
          }
        },
      }))
    } catch (error) {
      expect(error).toBeInstanceOf(ProductContractError)
      if (!(error instanceof ProductContractError)) return
      expect(error.issues).toEqual([
        { path: 'price.amount', code: 'invalid_type' },
        { path: 'inventory', code: 'invalid_type' },
      ])
    }
  })
})

import { expect, test } from 'vitest'
import { VALID_PRODUCT_PAYLOAD } from './fake-product-server'
import { toProductCardViewModel } from './product-card-view-model'
import { ProductResponseSchema } from './product-response'
 
test('검증된 상품 응답을 카드 표시 계약으로 바꾼다', () => {
  const result = ProductResponseSchema.safeParse(VALID_PRODUCT_PAYLOAD)
 
  expect(result.success).toBe(true)
  if (!result.success) return
  expect(toProductCardViewModel(result.data)).toEqual({
    id: 'note-1',
    name: '불변 업데이트 노트',
    priceText: '12,900원',
    canBuy: true,
    availabilityText: '구매 가능',
  })
})

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import ProductCardBad from './product-card-bad'
import ProductCard from './product-card'
 
const queryClient = new QueryClient()
const SHOW_BAD_CARD = true
const rootElement = document.getElementById('root')
 
if (!rootElement) {
  throw new Error('root 요소를 찾지 못했습니다.')
}
 
createRoot(rootElement).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      {SHOW_BAD_CARD ? <ProductCardBad /> : <ProductCard />}
    </QueryClientProvider>
  </StrictMode>,
)

<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>

pnpm exec tsc --noEmit
pnpm exec vitest run src/product-response.test.ts src/product-card-view-model.test.ts
pnpm exec vitest run

문제       200 응답의 실제 JSON이 선언한 ProductResponse와 다름
잘못된 판단 as ProductResponse가 실행 중 형식도 확인해 준다고 생각함
관찰       Query 성공 뒤 mapper가 null의 status를 읽으며 화면이 무너짐
원인       컴파일 전 타입 검사와 실행 중 외부 입력 검증을 같은 보장으로 봄
행동       unknown 입력을 스키마로 검증하고 계약 오류를 queryFn에서 던짐
검증       정상·문자열 가격·null 재고 fixture와 실제 오류 UI를 각각 확인