Nextjs 실행 컨텍스트

┌─────────────────────────────────────────────────────────────┐
│                        Next.js 앱                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  클라이언트 ──→ [Middleware] ──→ [Route Handler/Page]          │
│                     │                    │                  │
│                     │              ┌─────┴─────┐            │
│                     │              │           │            │
│                     │        [Server      [Client           │
│                     │        Component]   Component]        │
│                     │              │           │            │
│                     │              └─────┬─────┘            │
│                     │                    │                  │
│                     │            [Server Action]            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    Next.js App Router                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Server Component (기본값)        Client Component               │
│   ─────────────────────────        ────────────────             │
│                                                                 │
│   • 'use client' 없으면 자동         • 'use client' 선언 필요        │
│   • 서버에서만 실행                   • 서버 + 브라우저에서 실행          │
│   • async/await 사용 가능           • useState, useEffect 사용      │
│   • 환경변수 안전하게 사용             • 이벤트 핸들러 사용 가능           │
│   • JS 번들에 포함 안됨              • JS 번들에 포함됨                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

'use client'

// ❌ 흔한 오해: "이 컴포넌트는 브라우저에서만 실행된다"
// ✅ 실제 의미: "이 컴포넌트는 클라이언트 번들에 포함되고, hydration을 위해 브라우저로 전송된다"

export default function Counter() {
  // 실제로는:
  // 1. 서버에서 초기 HTML 생성을 위해 한번 실행 (SSR)
  // 2. 브라우저에서 hydration을 위해 또 실행
  // 3. 이후 상호작용 시 브라우저에서 실행
  
  console.log('렌더링됨')  // 서버 로그에도, 브라우저 콘솔에도 찍힌다!
  
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>
}

// 'use server' 선언된 함수 = Server Action
'use server'

export async function getProducts() {
  // 이 함수는 항상 서버에서 실행된다
  // 클라이언트에서 호출해도 서버에서 실행된다!
  const res = await fetch('https://api.example.com/products', {
    headers: { 'Authorization': `Bearer ${process.env.API_SECRET_KEY}` }
  })
  return res.json()
}

'use server'

// 조회 (GET 용도)
export async function getProducts() {
  const res = await fetch('https://api.example.com/products')
  return res.json()
}

// 생성 (POST 용도)
export async function createProduct(data: CreateProductInput) {
  const res = await fetch('https://api.example.com/products', {
    method: 'POST',
    body: JSON.stringify(data)
  })
  return res.json()
}

// 삭제 (DELETE 용도)
export async function deleteProduct(id: string) {
  const res = await fetch(`https://api.example.com/products/${id}`, {
    method: 'DELETE'
  })
  return res.json()
}

// Server Component에서
const products = await getProducts()  // 직접 실행

// Client Component에서
const products = await getProducts()  // 내부적으로 서버 요청 후 실행

┌─────────────────────────────────────────────────────────┐
│                                                         │
│  "Server Action 자체가 호출될 때" = 항상 POST                │
│  "Server Action 내부에서 외부 API 호출" = GET이든 자유         │
│                                                         │
└─────────────────────────────────────────────────────────┘

'use server'
export async function getProducts() {
  // 이 안에서는 GET 요청 완전히 가능하다!
  const res = await fetch('https://api.example.com/products', {
    method: 'GET'  // 또는 생략 (기본값이 GET)
  })
  return res.json()
}

브라우저에서 getProducts() 호출
    │
    │  POST /_next/server-action/...  ← 여기가 POST!
    ▼
Next.js 서버에서 getProducts 함수 실행
    │
    │  GET https://api.example.com/products  ← 여기는 GET!
    ▼
외부 API에서 데이터 반환
    │
    ▼
브라우저로 결과 전달

원본 코드 (개발자가 작성)
──────────────────────────
'use server'
export async function getProducts() {
  const res = await fetch('https://api.example.com/products')
  return res.json()
}

↓ Next.js 빌드 ↓

서버용 코드 (서버에 남음)
──────────────────────────
// 실제 로직이 여기서 실행된다
async function getProducts() {
  const res = await fetch('https://api.example.com/products')
  return res.json()
}

클라이언트용 코드 (브라우저로 전송)
────────────────────────────────
// 실제 로직은 없다! 서버 호출 함수로 대체된다
async function getProducts() {
  return fetch('/_next/server-action/abc123', {
    method: 'POST',
    body: JSON.stringify({ actionId: 'getProducts' })
  }).then(res => res.json())
}

┌──────────────────────────────────────────────────────────┐
│                                                          │
│  Client Component에서 Server Action을 import하면,           │
│  실제 코드가 아니라 "서버에 요청하는 함수"가 import됨               │
│                                                          │
│  그래서 API 키 같은 환경변수가 브라우저에 절대 노출 안됨!            │
│  🔐 보안 완벽!                                              │
│                                                          │
└──────────────────────────────────────────────────────────┘

// 일반 서버 코드 (❌ Client Component에서 import 불가)
// lib/api.ts ('use server' 없음)
export async function getProducts() {
  return await fetch('https://api.example.com/products')
    .then(res => res.json())
}

// Client Component에서:
'use client'
import { getProducts } from '@/lib/api'  // ❌ 에러!
// → 서버 코드가 클라이언트 번들에 포함되려고 함
// → 빌드 에러 또는 런타임 에러 😱
// Server Action (✅ 어디서든 import 가능)
// app/actions/products.ts
'use server'  // ← 이 한 줄이 마법!

export async function getProducts() {
  return await fetch('https://api.example.com/products')
    .then(res => res.json())
}

// Server Component에서:
import { getProducts } from '@/app/actions/products'  // ✅ OK!
const products = await getProducts()

// Client Component에서:
'use client'
import { getProducts } from '@/app/actions/products'  // ✅ OK!
// → 프록시 함수가 import된다 (실제 로직 아님)

Next.js 앱 내부에서 호출 → Server Action ✅
───────────────────────────────────────────
• Server Component에서 호출
• Client Component에서 호출
• 둘 다 Server Action으로 충분!

Next.js 앱 외부에서 호출 → Route Handler 필요
───────────────────────────────────────────
• 모바일 앱 (React Native, Flutter)
• 다른 백엔드 서버
• Webhook (결제 콜백, 알림 등)

"외부 API 호출"의 두 가지 의미:
───────────────────────────────────────────────────────────────

1️⃣ 우리 코드가 외부 API를 호출하는 것 (Server Action으로 OK)

   Next.js 앱 ─────▶ 외부 백엔드 API
   
   예: Server Action에서 https://api.example.com 호출
   → Server Action으로 충분하다!


2️⃣ 외부에서 우리 API를 호출하는 것 (Route Handler 필요)

   모바일 앱 ─────▶ 우리 Next.js 앱
   
   예: React Native 앱이 우리 서버에 요청
   → Route Handler가 필요하다!

// lib/orders.ts - 공유 비즈니스 로직
export async function createOrderLogic(user: User, items: CartItem[]) {
  const order = await db.orders.create({ userId: user.id, items })
  return order
}

// app/actions/orders.ts - 내부용 Server Action
'use server'
export async function createOrderAction(items: CartItem[]) {
  const user = await getCurrentUser()
  return createOrderLogic(user, items)
}

// app/api/orders/route.ts - 외부용 Route Handler
export async function POST(request: Request) {
  const user = await authenticateRequest(request)
  const { items } = await request.json()
  return NextResponse.json(await createOrderLogic(user, items))
}

// ❌ Client Component만 사용
'use client'

function ProductsPage() {
  const [products, setProducts] = useState([])
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    getProducts().then(data => {
      setProducts(data)
      setLoading(false)
    })
  }, [])

  if (loading) return <div>로딩중...</div>  // 😢 사용자가 이걸 본다

  return <ul>...</ul>
}

// page.tsx (서버 컴포넌트)
export default async function Page() {
  const products = await getProducts()  // 서버에서 호출은 했는데...

  return (
    <Suspense fallback={<Spinner />}>
			<ProductList />{/* 결과를 전달 안 함! */}
		</Suspense>
  )
}

// product-list.tsx (클라이언트 컴포넌트)
'use client'
export default function ProductList() {
  const { data: products } = useSuspenseQuery({
    queryKey: ['products'],
    queryFn: getProducts,
  })

  // 🔴 왜 Suspense fallback(Spinner)이 보이지?
  return <ul>{products.map(...)}</ul>
}

1. 서버: getProducts() 호출 → 결과 받음 → 그런데 버림! 🗑️
2. 서버: ProductList 렌더링 (캐시에 아무것도 없음)
3. 클라이언트: useSuspenseQuery 실행 → 캐시에 없음 → fetch 시작
4. 클라이언트: Suspense가 로딩 감지 → Spinner 표시! 🔴
5. 클라이언트: fetch 완료 → 상품 목록 표시

[안티패턴: 서버에서 호출만 하고 버림]

서버                           브라우저
  │                               │
  │  getProducts() 호출            │
  │  → 결과 버림! 🗑️                │
  │                               │
  │  HTML (빈 껍데기)               │
  │ ─────────────────────────────▶│
  │                               │  Spinner 표시 😢
  │                               │  useSuspenseQuery → fetch 시작
  │                               │
  │  서버 액션 응답                  │
  │ ─────────────────────────────▶│
  │                               │  그제서야 상품 표시

총 왕복: 2번 (느림!)


[권장 패턴: prefetchQuery + HydrationBoundary]

서버                           브라우저
  │                               │
  │  prefetchQuery 호출            │
  │  → 캐시에 저장!                  │
  │  → dehydrate로 직렬화           │
  │                               │
  │  HTML (데이터 포함!)             │
  │ ─────────────────────────────▶│
  │                               │  HydrationBoundary가 캐시 복원
  │                               │  useSuspenseQuery → 캐시에 있음!
  │                               │  즉시 상품 표시! ✅

총 왕복: 1번 (초기 로드 시) - 훨씬 빠름! 🚀

// app/products/page.tsx
// 'use client' 없음 = Server Component

export default async function ProductsPage() {
  // 서버에서 실행된다 - 브라우저가 이 코드를 절대 볼 수 없다
  const products = await fetch('https://api.example.com/products')
    .then(res => res.json())

  return (
    <ul>
{products.map(product => (
        <li key={product.id}>{product.name}</li>
      ))}
</ul>
  )
}

// app/actions/products.ts
'use server'

export async function getProducts() {
  const res = await fetch('https://api.example.com/products', {
    headers: { 'Authorization': `Bearer${process.env.API_KEY}` }
  })
  return res.json()
}

// app/products/page.tsx
import { getProducts } from '@/app/actions/products'

export default async function ProductsPage() {
  const products = await getProducts()
  return <ul>{products.map(...)}</ul>
}

// components/ProductList.tsx
'use client'

import { useState, useEffect } from 'react'
import { getProducts } from '@/app/actions/products'

export default function ProductList() {
  const [products, setProducts] = useState([])
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    getProducts()
      .then(setProducts)
      .finally(() => setLoading(false))
  }, [])

  if (loading) return <div>로딩 중...</div>
  return <ul>{products.map(...)}</ul>
}

// components/ProductList.tsx
'use client'

import { useQuery } from '@tanstack/react-query'
import { getProducts } from '@/app/actions/products'

export default function ProductList() {
  const { data: products, error, isLoading } = useQuery({
    queryKey: ['products'],
    queryFn: getProducts,
  })

  if (isLoading) return <div>로딩 중...</div>
  if (error) return <div>에러 발생</div>

  return <ul>{products.map(...)}</ul>
}

// app/actions/products.ts
'use server'

import { IApiDefaultRes } from '@/types/api.type'
import { IProduct, ICategory, IUser, ICart } from '@/types/main.type'
import { apiIns } from '@/lib/api-ins'

export const mainAction = {
  getProducts: async function getProducts() {
    return await apiIns('mainApi')<IApiDefaultRes<IProduct[]>>('/api/products', {
      method: 'GET',
      cache: 'no-store',
      next: {
        tags: ['products'],
      },
    })
  },

  getCategories: async function getCategories() {
    return await apiIns('mainApi')<IApiDefaultRes<ICategory[]>>('/api/categories', {
      method: 'GET',
      cache: 'no-store',
    })
  },

  getCurrentUser: async function getCurrentUser() {
    return await apiIns('userApi')<IApiDefaultRes<IUser>>('/api/user/me',{
      method: 'GET',
      cache: 'no-store',
    })
  },

  getCart: async function getCart(){
    return await apiIns('userApi')<IApiDefaultRes<ICart>>('/api/cart',{
      method: 'GET',
      cache: 'no-store',
      next: {
        tags: ['cart'],
      },
    })
  },

  // mutation 예시
  addToCart: async function addToCart(body: IAddCartBody){
    return await apiIns('userApi')<IApiDefaultRes>('/api/cart',{
      method: 'POST',
      cache: 'no-store',
      body,
    })
  },
}

// lib/query-client.ts
import { QueryClient } from '@tanstack/react-query'

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000,  // 1분간 fresh
      },
    },
  })
}

let browserQueryClient: QueryClient | undefined = undefined

export function getQueryClient() {
  if (typeof window === 'undefined') {
    // 서버: 항상 새로 만들기 (요청 간 공유 방지)
    return makeQueryClient()
  } else {
    // 브라우저: 싱글톤으로 재사용
    if (!browserQueryClient) browserQueryClient = makeQueryClient()
    return browserQueryClient
  }
}

// app/products/page.tsx (Server Component)
import { dehydrate, HydrationBoundary } from '@tanstack/react-query'
import { getQueryClient } from '@/lib/query-client'
import { getProducts, getCategories, getCurrentUser, getCart } from '@/app/actions/products'
import { Suspense } from 'react'
import { ErrorBoundary } from 'react-error-boundary'
import Header from '@/components/Header'
import Sidebar from '@/components/Sidebar'
import ProductList from '@/components/ProductList'

export default async function ProductsPage() {
  const queryClient = getQueryClient()

  // 여러 데이터를 병렬로 prefetch
  await Promise.all([
    queryClient.prefetchQuery({
      queryKey: ['products'],
      queryFn: getProducts,
    }),
    queryClient.prefetchQuery({
      queryKey: ['categories'],
      queryFn: getCategories,
    }),
    queryClient.prefetchQuery({
      queryKey: ['user', 'me'],
      queryFn: getCurrentUser,
    }),
    queryClient.prefetchQuery({
      queryKey: ['cart'],
      queryFn: getCart,
    }),
  ])

  // dehydrate 한 번으로 모든 캐시가 직렬화됨!
  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
			<ErrorBoundary fallback={<div>에러가 발생했습니다</div>}>
				<Suspense fallback={<ProductSkeleton />}>
					<Header />{/* user, cart 사용 - props 없음! */}
					<Sidebar />{/* categories 사용 - props 없음! */}
					<ProductList />{/* products 사용 - props 없음! */}
				</Suspense>
			</ErrorBoundary>
		</HydrationBoundary>
  )
}

// components/Header.tsx
'use client'

import { useSuspenseQuery } from '@tanstack/react-query'
import { getCurrentUser, getCart } from '@/app/actions/products'

export function Header() {
  const { data: user } = useSuspenseQuery({
    queryKey: ['user', 'me'],
    queryFn: getCurrentUser,
  })

  const { data: cart } = useSuspenseQuery({
    queryKey: ['cart'],
    queryFn: getCart,
  })

  return (
    <header>
			<span>{user.name}님</span>
			<CartIcon count={cart.items.length} />
		</header>
  )
}

Server Action = "데이터를 어디서 가져올지" (서버 실행, 보안)
TanStack Query = "클라이언트에서 어떻게 관리할지" (캐싱, 상태, 자동 갱신)

// 😩 Server Action만 쓰면...
const [products, setProducts] = useState([])
const [loading, setLoading] = useState(true)

useEffect(() => {
  getProducts().then(setProducts).finally(() => setLoading(false))
}, [])

// 탭 포커스 시 자동 갱신? 직접 구현해야 함
// 여러 컴포넌트에서 같은 데이터? 각각 요청 나감
// 로딩/에러 상태? 매번 useState 3개...

// ✅ TanStack Query로 감싸면!
const { data: products } = useSuspenseQuery({
  queryKey: ['products'],
  queryFn: getProducts,  // Server Action을 그냥 넘기면 됨
})

// 탭 포커스 시 자동 갱신? ✅ 기본 제공
// 여러 컴포넌트에서 같은 queryKey로 호출? ✅ 캐시 공유!
// 로딩/에러 상태? ✅ Suspense/ErrorBoundary가 처리!

서버에서:
┌─────────────────────────────────────────┐
│  QueryClient 캐시                        │
│                                         │
│  ['products']    → { data: [...] }      │
│  ['categories']  → { data: [...] }      │
│  ['user', 'me']  → { data: {...} }      │
│  ['cart']        → { data: {...} }      │
│                                         │
└─────────────────────────────────────────┘
              │
              │ dehydrate()
              ▼
┌─────────────────────────────────────────┐
│  JSON 직렬화된 상태 (HTML에 포함)            │
└─────────────────────────────────────────┘
              │
              │ 브라우저로 전송
              ▼
┌─────────────────────────────────────────┐
│  HydrationBoundary가 복원                 │
│                                         │
│  → 각 컴포넌트에서 useSuspenseQuery로        │
│    해당 키의 데이터 즉시 사용!                │
└─────────────────────────────────────────┘

// app/products/[id]/page.tsx
export default async function ProductDetailPage({
  params
}: {
  params: { id: string }
}) {
  const queryClient = getQueryClient()

  await Promise.all([
    queryClient.prefetchQuery({
      queryKey: ['product', params.id],
      queryFn: () => getProduct(params.id),
    }),
    queryClient.prefetchQuery({
      queryKey: ['reviews', params.id],
      queryFn: () => getReviews(params.id),
    }),
    queryClient.prefetchQuery({
      queryKey: ['related-products', params.id],
      queryFn: () => getRelatedProducts(params.id),
    }),
  ])

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
			<ErrorBoundary fallback={<에러 />}>
				<Suspense fallback={<스켈레톤 />}>
					<ProductDetail id={params.id} />
				</Suspense>
			</ErrorBoundary>
		</HydrationBoundary>
  )
}

Server Action + Server Component + Client Component + TanStack Query
───────────────────────────────────────────────────────────────

1. Server Action으로 로직 정의 → 환경변수 안전 (보안 ✅)
2. Server Component에서 prefetch → 데이터가 HTML에 포함 (SEO ✅)
3. dehydrate로 캐시 직렬화 → 클라이언트에 전달
4. HydrationBoundary가 캐시 복원 → Prop Drilling 없음!
5. TanStack Query 훅 호출 → 캐시에 이미 있음! → 로딩 없음
6. 이후 갱신은 TanStack Query가 자동 관리

결과:
• SEO ✅ (초기 HTML에 데이터 포함)
• 빠른 초기 로드 ✅ (로딩 스피너 없음)
• 실시간 갱신 ✅ (TanStack Query)
• 환경변수 안전 ✅ (Server Action)
• 타입 안전 ✅ (useSuspenseQuery면 data가 undefined 아님)
• Prop Drilling 없음 ✅ (HydrationBoundary)

// app/products/page.tsx
export default async function Page() {
  const products = await getProducts()
  const categories = await getCategories()
  const user = await getCurrentUser()

  return (
    <ProductsPage
      initialProducts={products}
      initialCategories={categories}
      initialUser={user}
    />
  )
}

// components/ProductsPage.tsx
'use client'
function ProductsPage({ initialProducts, initialCategories, initialUser }) {
  const { data: products } = useQuery({
    queryKey: ['products'],
    queryFn: getProducts,
    initialData: initialProducts,
  })

  // 하위 컴포넌트에 또 전달해야 함...
  return (
    <Header user={initialUser} />
    <Sidebar categories={initialCategories} />
    <ProductList products={products} />
  )
}

page.tsx
  └─ ProductsPage (initialUser={...}, initialCategories={...}, initialProducts={...})
       └─ Container (user={...})
            └─ Header (user={...})
                 └─ UserMenu (user={...})
                      └─ ProfileDropdown (user={...})

// app/products/page.tsx
export default async function Page() {
  const queryClient = getQueryClient()

  await Promise.all([
    queryClient.prefetchQuery({ queryKey: ['products'], queryFn: getProducts }),
    queryClient.prefetchQuery({ queryKey: ['categories'], queryFn: getCategories }),
    queryClient.prefetchQuery({ queryKey: ['user'], queryFn: getCurrentUser }),
  ])

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
{/* props 없음! */}
<Container>
<Header />
<Sidebar />
<ProductList />
</Container>
</HydrationBoundary>
  )
}

// components/Header.tsx - 5단계 아래에서도 직접 접근!
'use client'
function ProfileDropdown() {
  // props 받을 필요 없이 직접 접근!
  const { data: user } = useSuspenseQuery({
    queryKey: ['user'],
    queryFn: getCurrentUser,
  })
  return <span>{user.name}</span>
}

Next.js의 캐시들
───────────────────────────────────────────────────────────────

1️⃣ Data Cache (서버)
   • fetch() 결과 캐시
   • revalidateTag(), revalidatePath()로 무효화

2️⃣ Router Cache (클라이언트)
   • 방문한 페이지 캐시
   • router.refresh()로 무효화

3️⃣ TanStack Query 캐시 (클라이언트)
   • 라이브러리가 관리하는 캐시
   • invalidateQueries()로 무효화

// Server Action 내부
'use server'
export async function deleteProduct(id: string) {
  await fetch(`${API_URL}/products/${id}`, { method: 'DELETE' })
  revalidateTag('products')  // 1. Data Cache (서버)
}

// Client Component
'use client'
const queryClient = useQueryClient()
const router = useRouter()

const mutation = useMutation({
  mutationFn: deleteProduct,
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ['products'] })  // 2. TanStack Query
    router.refresh()                                           // 3. Router Cache
  },
})

// ❌ useSuspenseQuery는 enabled 옵션이 없다!
const { data } = useSuspenseQuery({
  queryKey: ['user', userId],
  queryFn: () => getUser(userId),
  // enabled: !!userId  ← 없음!
})

// ✅ 조건부 fetch는 useQuery 사용
const { data, isLoading } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => getUser(userId),
  enabled: !!userId,  // userId 있을 때만 fetch
})

if (isLoading) return <Spinner />
if (!data) return <div>사용자를 선택하세요</div>
return <div>{data.name}</div>

// SWR 방식
import { SWRConfig } from 'swr'

export default async function Page() {
  const products = await getProducts()

  return (
    <SWRConfig value={{
      fallback: {
        '/api/products': products  // 키: 초기값
      }
    }}>
<ProductList />
</SWRConfig>
  )
}

// 하위 컴포넌트
function ProductList() {
  const { data } = useSWR('/api/products', fetcher)
  // fallback에서 초기값을 찾아서 사용
  return <ul>{data.map(...)}</ul>
}

"이 키('/api/products')로 요청하면,
 일단 이 초기값(products)을 써.
 나중에 실제로 fetch하면 그걸로 대체할게."

// TanStack Query 방식
import { dehydrate, HydrationBoundary } from '@tanstack/react-query'

export default async function Page() {
  const queryClient = getQueryClient()

  // 1. 서버에서 prefetch (캐시에 저장됨)
  await queryClient.prefetchQuery({
    queryKey: ['products'],
    queryFn: getProducts,
  })

  // 2. 캐시 상태 전체를 직렬화
  const dehydratedState = dehydrate(queryClient)

  return (
    // 3. 직렬화된 상태를 HTML에 포함시켜 전송
    <HydrationBoundary state={dehydratedState}>
<ProductList />
</HydrationBoundary>
  )
}

"서버에서 QueryClient에 데이터를 미리 채워놨어.
 이 캐시 상태 전체를 JSON으로 직렬화해서 브라우저로 보낼게.
 브라우저에서 이걸 복원하면 마치 이미 fetch한 것처럼 돼."

SWR fallback:
┌─────────────────────────────────┐
│  키: '/api/products'             │
│  값: [{ id: 1, name: '상품' }]    │  ← 단순히 "값"만 전달
└─────────────────────────────────┘

TanStack Query dehydrate:
┌─────────────────────────────────────────────────┐
│  queryKey: ['products']                         │
│  data: [{ id: 1, name: '상품' }]                 │
│  dataUpdatedAt: 1704067200000                   │  ← 언제 fetch했는지
│  state: 'success'                               │  ← 상태 정보
│  fetchStatus: 'idle'                            │
│  ... (메타데이터 전부)                              │
└─────────────────────────────────────────────────┘

// SWR: 초기값만 있으면 "이게 언제 가져온 건지" 몰라
// → staleTime 계산이 부정확할 수 있음

// TanStack Query: dataUpdatedAt까지 전달
// → "서버에서 10:00에 가져왔으니까,
//    staleTime 5분이면 10:05까지 fresh야"
// → 정확한 캐시 만료 계산 가능

<!-- TanStack Query가 생성하는 HTML -->
<script>
  window.__REACT_QUERY_STATE__ = {
    "mutations": [],
    "queries": [
      {
        "queryKey": ["products"],
        "queryHash": "[\"products\"]",
        "state": {
          "data": [{"id":1,"name":"맥북"}],
          "dataUpdatedAt": 1704067200000,
          "error": null,
          "errorUpdatedAt": 0,
          "fetchFailureCount": 0,
          "fetchStatus": "idle",
          "status": "success"
        }
      }
    ]
  }
</script>

실무에서 자주 필요한 기능들:
───────────────────────────────────────────────────────────────

1️⃣ Mutation 후 캐시 갱신
   SWR: mutate() 직접 호출, 로직 분산
   TanStack Query: useMutation의 onSuccess에서 한 번에 처리 ✅

2️⃣ 디버깅
   SWR: console.log 찍어보기...
   TanStack Query: DevTools에서 캐시 상태 한눈에! 🔧

3️⃣ 서버 데이터 Hydration
   SWR: SWRConfig fallback (간단하지만 제한적)
   TanStack Query: HydrationBoundary + prefetchQuery (강력) ✅

4️⃣ Optimistic Update
   SWR: 직접 구현 (코드 많음)
   TanStack Query: useMutation 옵션으로 간단하게 ✅

데이터가 필요한가?
    │
    ├─ 초기 페이지 로드에 필요
    │         │
    │     실시간 갱신 필요?
    │         │
    │    Yes ─┼─ No
    │     │       │
    │     ▼       ▼
    │   Server prefetch     Server Component만
    │   + TanStack Query
    │
    └─ 사용자 인터랙션 후 필요
              │
        조건부 fetch?
              │
         Yes ─┼─ No
          │       │
          ▼       ▼
      useQuery   useSuspenseQuery
     (enabled)   (권장)

데이터 변경 후 이 3가지를 기억하자!
───────────────────────────────────────────────────────────────

1️⃣ Server Action 내부
   revalidateTag('products')

2️⃣ Client Component에서
   queryClient.invalidateQueries({ queryKey: ['products'] })

3️⃣ 페이지 갱신
   router.refresh()