API 응답과 뷰 모델: 서버 필드가 바뀌어도 화면 계약을 지키려면

export const PRODUCT_RESPONSE_BEFORE = {
  product_id: 'note-1',
  title: '불변 업데이트 노트',
  price_won: 12900,
  availability: 'in_stock',
}
 
export const PRODUCT_RESPONSE_CURRENT = {
  id: 'note-1',
  display_name: '불변 업데이트 노트',
  price: {
    amount: 12900,
    currency: 'KRW',
  },
  inventory: {
    status: 'available',
  },
}
 
const RESPONSE_VERSION = 'current' // 'before' | 'current'
 
export async function fetchProductResponse() {
  await Promise.resolve()
  return RESPONSE_VERSION === 'before'
    ? PRODUCT_RESPONSE_BEFORE
    : PRODUCT_RESPONSE_CURRENT
}

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
 
createRoot(document.getElementById('root')).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      {SHOW_BAD_CARD ? <ProductCardBad /> : <ProductCard />}
    </QueryClientProvider>
  </StrictMode>,
)

import { useQuery } from '@tanstack/react-query'
import { fetchProductResponse } from './product-api'
 
export default function ProductCardBad() {
  const productQuery = useQuery({
    queryKey: ['product', 'note-1'],
    queryFn: fetchProductResponse,
  })
 
  if (productQuery.isPending) return <p>불러오는 중</p>
  if (productQuery.isError) return <p>상품을 불러오지 못했습니다.</p>
 
  const product = productQuery.data
  const priceText = `${Number(product.price_won).toLocaleString('ko-KR')}원`
  const canBuy = product.availability === 'in_stock'
 
  return (
    <article>
      <h2>{product.title}</h2>
      <p>{priceText}</p>
      <button disabled={!canBuy}>{canBuy ? '구매하기' : '구매 불가'}</button>
    </article>
  )
}

export function toProductCardViewModel(productResponse) {
  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 { useQuery, useQueryClient } from '@tanstack/react-query'
import { fetchProductResponse } from './product-api'
import { toProductCardViewModel } from './product-card-view-model'
 
const PRODUCT_QUERY_KEY = ['product', 'note-1']
 
export default function ProductCard() {
  const queryClient = useQueryClient()
  const productQuery = useQuery({
    queryKey: PRODUCT_QUERY_KEY,
    queryFn: fetchProductResponse,
    select: toProductCardViewModel,
  })
 
  if (productQuery.isPending) return <p>불러오는 중</p>
  if (productQuery.isError) return <p>상품을 불러오지 못했습니다.</p>
 
  const product = productQuery.data
 
  function logModels() {
    console.log('캐시 원본:', queryClient.getQueryData(PRODUCT_QUERY_KEY))
    console.log('화면 모델:', product)
  }
 
  return (
    <article>
      <h2>{product.name}</h2>
      <p>{product.priceText}</p>
      <p>{product.availabilityText}</p>
      <button disabled={!product.canBuy}>구매하기</button>
      <button type="button" onClick={logModels}>캐시와 화면 모델 기록</button>
    </article>
  )
}

캐시에 API 응답을 유지       화면마다 select로 서로 다른 뷰 모델을 파생
캐시에 공통 모델을 유지      queryFn 또는 데이터 계층에서 검증·변환 후 저장

import { useEffect, useState } from 'react'
import { toProductCardViewModel } from './product-card-view-model'
 
function ProductCardWithDuplicateState({ productResponse }) {
  const [viewModel, setViewModel] = useState(() =>
    toProductCardViewModel(productResponse),
  )
 
  useEffect(() => {
    setViewModel(toProductCardViewModel(productResponse))
  }, [productResponse])
 
  return <p>{viewModel.name}</p>
}

import { expect, test } from 'vitest'
import { PRODUCT_RESPONSE_CURRENT } from './product-api'
import { toProductCardViewModel } from './product-card-view-model'
 
test('현재 상품 응답을 카드 표시 계약으로 바꾼다', () => {
  expect(toProductCardViewModel(PRODUCT_RESPONSE_CURRENT)).toEqual({
    id: 'note-1',
    name: '불변 업데이트 노트',
    priceText: '12,900원',
    canBuy: true,
    availabilityText: '구매 가능',
  })
})

pnpm exec vitest run src/product-card-view-model.test.js

문제       API 응답의 필드·중첩·열거값을 JSX가 직접 해석함
잘못된 판단 타입이 있는 응답 객체를 그대로 props로 쓰면 변경에도 안전함
관찰       가짜 응답 함수와 Query 성공 뒤에도 제목 없음, NaN원, 구매 불가가 표시됨
원인       네트워크 전송 계약과 화면 표시 계약의 변경 이유를 하나로 묶음
행동       순수 mapper로 뷰 모델을 만들고 캐시 전후 위치를 명시적으로 선택
검증       API fixture, 뷰 모델 계약, 캐시 원본과 실제 화면을 각각 확인