FSD + TanStack Query + Next.js App Router: queryKey와 revalidateTag를 entities에서 단일 진실 공급원으로 관리하는 법

app/ → pages/ → widgets/ → features/ → entities/ → shared/

['users']                                    // 모든 user 관련 캐시
['users', 'list']                            // user 목록 전체
['users', 'list', { status: 'active' }]      // 필터된 목록
['users', 'detail', userId]                  // 특정 user 상세

// v5 이전 — key와 fn이 분리되어 중복 발생
const userDetailKey = (id: string) => ['users', 'detail', id]
const { data } = useQuery({
  queryKey: userDetailKey(id),
  queryFn: () => fetchUser(id),
})
 
// v5 이후 — queryOptions로 묶어서 재사용
const userDetailOptions = (id: string) =>
  queryOptions({
    queryKey: ['users', 'detail', id],
    queryFn: () => fetchUser(id),
    staleTime: 10 * 60 * 1000, // 10분간 fresh로 간주
  })
 
// 동일한 객체를 여러 곳에서 재사용 가능
const { data } = useQuery(userDetailOptions(id))
await queryClient.prefetchQuery(userDetailOptions(id))
queryClient.getQueryData(userDetailOptions(id).queryKey) // 타입 안전

// Server Component — 태그를 붙여서 fetch
const users = await fetch('/api/users', {
  next: { tags: ['users'] }
})
 
// Server Action — 데이터가 바뀌면 태그로 무효화
'use server'
async function updateUser(id: string, data: UpdateUserDto) {
  await api.updateUser(id, data)
  revalidateTag('users') // Next.js 서버 캐시 무효화
}

// entities/user/api/queries.ts
 
import { queryOptions } from '@tanstack/react-query'
import { fetchUser, fetchUsers } from './fetch'
import type { UserFilters } from '../model/types'
 
// userKeys는 내부 구현 — 외부에 직접 노출하지 않습니다
const userKeys = {
  all: ['users'] as const,
  lists: () => [...userKeys.all, 'list'] as const,
  list: (filters?: UserFilters) => [...userKeys.lists(), filters] as const,
  details: () => [...userKeys.all, 'detail'] as const,
  detail: (id: string) => [...userKeys.details(), id] as const,
}
 
export const userQueries = {
  list: (filters?: UserFilters) =>
    queryOptions({
      queryKey: userKeys.list(filters),
      queryFn: () => fetchUsers(filters),
      staleTime: 5 * 60 * 1000,
    }),
  detail: (id: string) =>
    queryOptions({
      queryKey: userKeys.detail(id),
      queryFn: () => fetchUser(id),
      staleTime: 10 * 60 * 1000,
    }),
}
 
// invalidateQueries에서 사용할 key prefix를 명시적으로 노출
export const userQueryKeys = userKeys

// entities/user/index.ts — 공개 API만 외부로 노출
 
export { userQueries, userQueryKeys } from './api/queries'
export type { User, UserFilters } from './model/types'
export { UserCard } from './ui/UserCard'
export { UserAvatar } from './ui/UserAvatar'
// fetch.ts의 내부 구현은 export하지 않습니다

// ✅ 권장: queryKey를 명시적으로 꺼내서 사용
queryClient.invalidateQueries({ queryKey: userQueryKeys.lists() })
queryClient.invalidateQueries({ queryKey: userQueryKeys.detail(userId) })
 
// ❌ 주의: queryOptions 객체를 InvalidateQueryFilters 자리에 직접 넘기면 타입 에러 가능
queryClient.invalidateQueries(userQueries.list())

// shared/config/cache-tags.ts
 
export const CACHE_TAGS = {
  USERS: 'users',
  USER_DETAIL: (id: string) => `user-${id}`,
  POSTS: 'posts',
  POST_DETAIL: (id: string) => `post-${id}`,
} as const

// entities/user/api/fetch.ts — Server Component용 fetch 함수
// 참고: 실제 프로젝트에선 shared/api에 API 클라이언트 추상화가 있다면 그쪽을 사용하는 것이
// FSD 원칙에 더 부합합니다. 여기서는 개념 전달을 위해 fetch를 직접 사용합니다.
 
import { CACHE_TAGS } from '@/shared/config/cache-tags'
 
export async function fetchUsersWithCache() {
  const res = await fetch('/api/users', {
    next: { tags: [CACHE_TAGS.USERS] }, // 상수 참조
  })
  return res.json()
}
 
export async function fetchUserWithCache(id: string) {
  const res = await fetch(`/api/users/${id}`, {
    next: { tags: [CACHE_TAGS.USERS, CACHE_TAGS.USER_DETAIL(id)] },
  })
  return res.json()
}

// features/user-edit/api/mutations.ts
 
'use server'
 
import { revalidateTag } from 'next/cache'
import { CACHE_TAGS } from '@/shared/config/cache-tags'
import { apiClient } from '@/shared/api/client'
import type { UpdateUserDto } from '@/entities/user'
 
export async function updateUserAction(id: string, data: UpdateUserDto) {
  const updated = await apiClient.patch(`/users/${id}`, data)
 
  // 서버 캐시 무효화 — 예시 2에서 만든 CACHE_TAGS 상수 사용
  revalidateTag(CACHE_TAGS.USERS)
  revalidateTag(CACHE_TAGS.USER_DETAIL(id))
 
  return updated
}

// features/user-edit/ui/UserEditForm.tsx
 
'use client'
 
import { useState } from 'react'
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { userQueryKeys } from '@/entities/user' // 예시 1에서 노출한 key prefix
import { updateUserAction } from '../api/mutations'
import type { UpdateUserDto } from '@/entities/user'
 
interface Props {
  userId: string
  defaultValues?: { name: string; email: string }
}
 
export function UserEditForm({ userId, defaultValues }: Props) {
  const queryClient = useQueryClient()
  const [name, setName] = useState(defaultValues?.name ?? '')
  const [email, setEmail] = useState(defaultValues?.email ?? '')
 
  const mutation = useMutation({
    mutationFn: (data: UpdateUserDto) => updateUserAction(userId, data),
    onSuccess: () => {
      // 클라이언트 캐시 무효화 — 예시 1에서 노출한 userQueryKeys 사용
      queryClient.invalidateQueries({ queryKey: userQueryKeys.lists() })
      queryClient.invalidateQueries({ queryKey: userQueryKeys.detail(userId) })
    },
    onError: () => {
      // 에러 시에는 캐시를 건드리지 않습니다 — 기존 데이터가 그대로 유지됩니다
    },
  })
 
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault()
        mutation.mutate({ name, email })
      }}
    >
      <input
        value={name}
        onChange={(e) => setName(e.target.value)}
        placeholder="이름"
      />
      <input
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="이메일"
      />
      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? '저장 중...' : '저장'}
      </button>
    </form>
  )
}

features/user-edit/
  api/
    mutations.ts     # Server Action — revalidateTag 호출
  ui/
    UserEditForm.tsx # 클라이언트 컴포넌트 — invalidateQueries 호출
  model/
    schema.ts        # Zod 검증 스키마
  index.ts

// entities/post/api/queries.ts
 
import { createQueryKeys } from '@lukemorales/query-key-factory'
import { fetchPosts, fetchPost } from './fetch'
import type { PostFilters } from '../model/types'
 
export const postKeys = createQueryKeys('posts', {
  all: null,
  list: (filters: PostFilters) => ({
    queryKey: [filters],
    queryFn: () => fetchPosts(filters),
  }),
  detail: (id: string) => ({
    queryKey: [id],
    queryFn: () => fetchPost(id),
  }),
})

// features/post-publish/ui/PostPublishButton.tsx
 
'use client'
 
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { postKeys } from '@/entities/post'
import { publishPostAction } from '../api/mutations'
 
export function PostPublishButton({ postId }: { postId: string }) {
  const queryClient = useQueryClient()
 
  const mutation = useMutation({
    mutationFn: () => publishPostAction(postId),
    onSuccess: () => {
      // _def를 사용하면 필터 조건에 상관없이 모든 list 쿼리가 무효화됩니다
      queryClient.invalidateQueries({ queryKey: postKeys.list._def })
      queryClient.invalidateQueries({ queryKey: postKeys.detail(postId).queryKey })
    },
    onError: () => {
      // 에러 시에는 캐시를 건드리지 않습니다
    },
  })
 
  return (
    <button onClick={() => mutation.mutate()} disabled={mutation.isPending}>
      {mutation.isPending ? '발행 중...' : '발행'}
    </button>
  )
}