C-6: 서버 상태 ① — Axios·useQuery로 가져온다

 오늘의 여정

 1. 배열을 걷어낸다            손으로 짜보고 아픈 곳을 센다
        ↓
 2. fetch 는 404 에 안 던진다   그래서 Axios 를 쓴다
        ↓
 3. 주소와 껍데기를 한 곳에      단일 인스턴스와 인터셉터
        ↓
 4. 토큰도 인터셉터가            401 이면 갱신하고 다시 보낸다
        ↓
 5. 서버 값은 낡는다            지금까지 다룬 값과 성질이 다르다
        ↓
 6. 세 갈래가 한 줄로           useQuery
        ↓
 7. 키가 캐시의 이름표          무엇을 달라고 했는지가 들어간다
        ↓
 8. 두 시간                    얼마나 믿을지 · 얼마나 남길지

node apps/api-stub/server.mjs

 GET /api/posts

 {
   "success": true,
   "data": [ { "id": 1, "username": "jaehoon", ... }, ... ],
   "message": null
 }

// apps/web-spa/src/routes/HomePage.tsx (고치기 전)
import { feedPosts } from '../data/feed';

export function HomePage() {
  const { posts, likedCount, ... } = useFeed(feedPosts);

// apps/web-spa/src/components/FeedSection.tsx
interface FeedSectionProps {
  posts: Post[];
}

// 게시물을 이미 손에 쥔 다음부터의 일만 맡는다.
// 가져오는 일은 이 컴포넌트를 그리는 쪽이 한다.
export function FeedSection({ posts: initialPosts }: FeedSectionProps) {
  const { posts, likedCount, toast, toggleLike, reachBottom, dismissToast } = useFeed(initialPosts);
  ...
}

// apps/web-spa/src/routes/HomePage.tsx
const FEED_URL = 'http://localhost:8090/api/posts';

export function HomePage() {
  // 세 갈래를 손으로 들고 있어야 한다. 데이터·기다림·실패.
  const [posts, setPosts] = useState<Post[] | null>(null);
  const [errorMessage, setErrorMessage] = useState<string | null>(null);

  useEffect(() => {
    // 늦게 온 응답이 이미 떠난 화면을 덮어쓰지 않게 표시를 남긴다
    let cancelled = false;

    fetch(FEED_URL)
      .then((response) => response.json())
      .then((body) => {
        if (cancelled) {
          return;
        }

        // fetch 는 404 든 500 이든 성공으로 친다. 봉투를 열어봐야 안다.
        if (body.success === false) {
          setErrorMessage(body.message);
          return;
        }

        setPosts(body.data);
      })
      .catch(() => {
        if (cancelled) {
          return;
        }

        setErrorMessage('피드를 불러오지 못했어요');
      });

    return () => {
      cancelled = true;
    };
  }, []);

// apps/web-spa/src/routes/HomePage.tsx
  if (errorMessage !== null) {
    return <p className="text-sm text-danger-strong">{errorMessage}</p>;
  }

  // 게시물이 도착한 뒤에야 피드를 그린다.
  if (posts === null) {
    return <p className="text-sm text-faint">피드를 불러오는 중이에요…</p>;
  }

  return <FeedSection posts={posts} />;
}

// ⚠️ 이렇게 하면 화면이 영영 비어 있습니다
export function HomePage() {
  const [posts, setPosts] = useState<Post[]>([]);
  useEffect(() => { /* 가져와서 setPosts */ }, []);

  const { posts: shown, likedCount, ... } = useFeed(posts);
  ...
}

// apps/web-spa/src/hooks/useFeed.ts
export function useFeed(initialPosts: Post[]) {
  const [state, dispatch] = useReducer(feedReducer, createFeedState(initialPosts));

// fetch 는 404 든 500 이든 성공으로 친다. 봉투를 열어봐야 안다.
if (body.success === false) {

 상태 번호: 404
 본문: { "success": false, "data": null, "message": "게시물을 찾을 수 없습니다" }

try {
  await fetch('http://localhost:8090/api/posts/999');
  console.log('여기까지 옵니다');
} catch {
  console.log('여기는 안 옵니다');
}

const response = await fetch('http://localhost:8090/api/posts/999');

response.ok;      // false
response.status;  // 404

const body = await response.json();   // await 이 한 번 더 필요합니다

import axios from 'axios';

try {
  await axios.get('http://localhost:8090/api/posts/999');
} catch (error) {
  // 여기로 옵니다
  error.response.status;        // 404
  error.response.data.message;  // '게시물을 찾을 수 없습니다'
}

const response = await axios.get('http://localhost:8090/api/posts');
response.data.success;  // true — .json() 을 부를 필요가 없습니다

axios.defaults.validateStatus;
// 200 → true · 299 → true · 300 → false · 404 → false · 500 → false

// 404 도 성공으로 받고 싶을 때
await axios.get(url, { validateStatus: (status) => status < 500 });

npm install axios

 HomePage 가 알고 있는 것

 · 서버 주소가 localhost:8090 이라는 것
 · 응답에 success · data · message 껍데기가 씌워져 있다는 것
 · 실패했을 때 message 를 꺼내 보여줘야 한다는 것

// apps/web-spa/src/api/client.ts
import axios, { AxiosError } from 'axios';

// 주소를 한 곳에만 적는다. 화면은 '/posts' 처럼 뒷부분만 안다.
export const API_BASE_URL = 'http://localhost:8090/api';

export const api = axios.create({
  baseURL: API_BASE_URL,
  timeout: 10_000,
});

// apps/web-spa/src/api/client.ts
api.interceptors.response.use(
  (response) => {
    const envelope = response.data as ApiEnvelope<unknown>;

    // 200 으로 오면서 봉투만 실패인 경우도 있다. 그것도 실패로 만든다.
    if (envelope.success === false) {
      throw new ApiError(envelope.message ?? CONNECTION_FAILED, response.status);
    }

    // 여기서 봉투를 벗긴다. 이 뒤로는 아무도 .data.data 를 안 쓴다.
    response.data = envelope.data;

    return response;
  },
  ...
);

// apps/web-spa/src/api/client.ts
/** 서버가 "안 됐다" 고 말했을 때 던지는 것 */
export class ApiError extends Error {
  readonly status: number | null;

  constructor(message: string, status: number | null) {
    super(message);
    this.name = 'ApiError';
    this.status = status;
  }
}

// apps/web-spa/src/api/client.ts
  (error: unknown) => {
    if (error instanceof AxiosError) {
      // 응답이 아예 없으면 서버까지 못 간 것이다.
      // 이때 Axios 가 주는 말은 'Network Error' — 영어라서 화면에 그대로 못 쓴다.
      if (error.response === undefined) {
        throw new ApiError(CONNECTION_FAILED, null);
      }

      // 4xx·5xx 에도 서버는 사유를 봉투에 담아 보낸다. 그 말을 그대로 쓴다.
      const envelope = error.response.data as ApiEnvelope<unknown> | undefined;

      throw new ApiError(envelope?.message ?? CONNECTION_FAILED, error.response.status);
    }

    throw new ApiError(CONNECTION_FAILED, null);
  },

// apps/web-spa/src/api/posts.ts
import type { Post } from '../types/instagram';
import { api } from './client';

// 봉투는 인스턴스가 이미 벗겨준다. 그래서 제네릭에 적는 것은
// 봉투가 아니라 안에 들어 있던 것이다.
export async function fetchFeed(): Promise<Post[]> {
  const response = await api.get<Post[]>('/posts');

  return response.data;
}

export async function fetchPostById(id: number): Promise<Post> {
  const response = await api.get<Post>(`/posts/${id}`);

  return response.data;
}

// apps/web-spa/src/routes/HomePage.tsx
    fetchFeed()
      .then((loaded) => {
        if (cancelled) {
          return;
        }

        setPosts(loaded);
      })
      .catch((error: unknown) => {
        if (cancelled) {
          return;
        }

        // 봉투를 여는 일은 인스턴스가 끝냈다. 화면은 사유만 받는다.
        setErrorMessage(error instanceof ApiError ? error.message : '피드를 불러오지 못했어요');
      });

 상태 번호: 401
 본문: { "success": false, "data": null, "message": "로그인이 필요합니다" }

 accessToken   요청마다 들고 가는 출입증. 금방 만료된다.
 refreshToken  출입증을 새로 받아올 때만 쓰는 것. 오래 산다.

// apps/web-spa/src/lib/tokens.ts
const ACCESS_KEY = 'instagram.accessToken';
const REFRESH_KEY = 'instagram.refreshToken';

export const tokenStore = {
  access(): string | null {
    return window.localStorage.getItem(ACCESS_KEY);
  },

  refresh(): string | null {
    return window.localStorage.getItem(REFRESH_KEY);
  },

  save({ accessToken, refreshToken }: TokenPair): void {
    window.localStorage.setItem(ACCESS_KEY, accessToken);
    window.localStorage.setItem(REFRESH_KEY, refreshToken);
  },

  ...
};

// apps/web-spa/src/api/client.ts
// 보내는 쪽 — 토큰이 있으면 모든 요청에 붙는다.
// 화면 어디에도 Authorization 을 적는 곳이 없다.
api.interceptors.request.use((config) => {
  const accessToken = tokenStore.access();

  if (accessToken !== null) {
    config.headers.Authorization = `Bearer ${accessToken}`;
  }

  return config;
});

// apps/web-spa/src/api/client.ts
    // 액세스 토큰이 만료된 것뿐이라면, 갱신하고 그 요청을 다시 보낸다.
    // 화면은 실패한 줄도 모른다.
    if (error.response.status === 401 && config !== undefined && config.retried !== true) {
      config.retried = true;

      try {
        await startRefresh();
      } catch {
        tokenStore.clear();
        throw new ApiError(LOGIN_AGAIN, 401);
      }

      return api.request(config);
    }

 좋아요 한 번을 눌렀을 때

 POST /api/posts/1/like     → 401  (출입증이 만료됐다)
 POST /api/auth/refresh     → 200  (새 출입증을 받는다)
 POST /api/posts/1/like     → 200  (다시 보낸다)

// apps/web-spa/src/api/client.ts
async function refreshAccessToken(): Promise<string> {
  const refreshToken = tokenStore.refresh();

  if (refreshToken === null) {
    throw new ApiError(LOGIN_AGAIN, 401);
  }

  // 갱신 요청은 인터셉터가 없는 맨 axios 로 보낸다.
  // api 로 보내면 이 응답의 401 이 다시 여기로 돌아온다.
  const response = await axios.post<ApiEnvelope<{ accessToken: string }>>(
    `${API_BASE_URL}/auth/refresh`,
    { refreshToken },
  );

  ...
  tokenStore.saveAccess(next);

  return next;
}

// apps/web-spa/src/api/client.ts
// 갱신은 한 번에 하나만 돈다. 동시에 401 을 받은 요청들이 같은 약속을 기다린다.
let refreshing: Promise<string> | null = null;

function startRefresh(): Promise<string> {
  refreshing ??= refreshAccessToken().finally(() => {
    refreshing = null;
  });

  return refreshing;
}

 useState 로 담은 값       우리가 setState 를 부르기 전에는 안 변한다
 주소에 적힌 값            우리가 옮기기 전에는 안 변한다
 store 에 담은 값          우리가 set 을 부르기 전에는 안 변한다

 먼저 연 화면      좋아요 1240개
 나중에 연 화면    좋아요 1241개

 같은 게시물인데 두 화면의 숫자가 다르다

 · 이 값을 받아온 지 얼마나 됐나
 · 지금 다시 물어봐야 하나, 아직 믿어도 되나
 · 다른 화면이 이미 받아둔 것이 있나
 · 다시 물어보는 동안 무엇을 보여줘야 하나

 값의 종류        어디에 두나              누가 주인인가
 ─────────────────────────────────────────────────────
 화면 안 값       useState                우리
 여러 화면 공용   store (Zustand)         우리
 주소에 담을 값   useSearchParams         우리
 서버가 가진 값   → 오늘부터              서버

npm install @tanstack/react-query

// apps/web-spa/src/queries/queryClient.ts
import { QueryClient } from '@tanstack/react-query';

// 캐시를 들고 있는 사람. React 바깥에서 한 번 만든다.
// 컴포넌트 안에서 만들면 다시 그려질 때마다 캐시가 새로 생긴다
// (main.tsx 의 라우터와 같은 이유다).
export const queryClient = new QueryClient();

// apps/web-spa/src/AppProviders.tsx
  return (
    // 캐시도 라우터보다 바깥이다. 화면을 옮겨 다녀도 받아둔 것이 살아 있어야 한다.
    <QueryClientProvider client={queryClient}>
      <ThemeProvider>
        <ThemeColorMeta />
        {children}
        {/* 확인 상자는 감쌀 것이 없다. 앱에 한 번 그려두기만 하면 된다. */}
        <ConfirmDialog />
      </ThemeProvider>
    </QueryClientProvider>
  );

// apps/web-spa/src/queries/posts.ts
import { useQuery } from '@tanstack/react-query';
import { fetchFeed } from '../api/posts';

// 키는 이 데이터의 이름이다. 캐시에서 이 이름으로 찾는다.
// 문자열이 아니라 배열인 이유는 Step 7 에서 파라미터가 붙기 때문이다.
export const feedKey = ['posts'] as const;

export function useFeedQuery() {
  return useQuery({
    queryKey: feedKey,
    queryFn: fetchFeed,
  });
}

// apps/web-spa/src/routes/HomePage.tsx
export function HomePage() {
  // 세 갈래를 손으로 들고 있던 자리가 한 줄로 줄었다.
  const { data: posts, isPending, error } = useFeedQuery();

  if (error !== null) {
    return (
      <p className="text-sm text-danger-strong">
        {error instanceof ApiError ? error.message : '피드를 불러오지 못했어요'}
      </p>
    );
  }

  if (isPending) {
    return <p className="text-sm text-faint">피드를 불러오는 중이에요…</p>;
  }

  return <FeedSection posts={posts} />;
}

 재본 것                        Step 1        Step 6
 ─────────────────────────────────────────────────────
 화면 하나를 열 때 요청 수       2             1
 같은 피드를 두 곳에서 그릴 때   2             1
 늦게 온 데이터가 화면에         안 들어감      들어감
 떠났다 돌아왔을 때             처음부터       기다림 없음

// apps/web-spa/src/api/posts.ts
export async function fetchFeed(tag?: string): Promise<Post[]> {
  // params 를 주면 Axios 가 물음표 뒤를 만들어 붙인다.
  // 한글 태그도 여기서 알아서 인코딩된다.
  const response = await api.get<Post[]>('/posts', {
    params: tag === undefined ? undefined : { tag },
  });

  return response.data;
}

// apps/web-spa/src/queries/posts.ts
// 키는 이 데이터의 이름이다. 캐시에서 이 이름으로 찾는다.
//
// 무엇을 달라고 했는지가 키에 함께 들어가야 한다.
// tag 를 빼놓으면 태그를 바꿔도 캐시는 "같은 것" 이라고 판단한다.
export function feedKey(tag?: string) {
  return tag === undefined ? (['posts'] as const) : (['posts', { tag }] as const);
}

export function useFeedQuery(tag?: string) {
  return useQuery({
    queryKey: feedKey(tag),
    queryFn: () => fetchFeed(tag),
  });
}

 feedKey()          →  ['posts']
 feedKey('카페')     →  ['posts', { tag: '카페' }]
 feedKey('한강')     →  ['posts', { tag: '한강' }]

 서로 다른 이름 = 창고에서 서로 다른 칸

// apps/web-spa/src/routes/ExplorePage.tsx
  // 주소에 적힌 값이 그대로 키의 일부가 된다.
  // 태그가 바뀌면 키가 바뀌고, 키가 바뀌면 새로 물어본다.
  const { data: shown, isPending, error } = useFeedQuery(tag ?? undefined);
  const { data: tags = [] } = useTagsQuery();

 전체를 열었다        GET /api/posts
 카페를 눌렀다        GET /api/posts?tag=카페
 한강을 눌렀다        GET /api/posts?tag=한강

// ⚠️ 반례 — tag 가 바뀌어도 키는 그대로다
  const { data = [], isPending } = useQuery({
    queryKey: ['posts'],
    queryFn: () => fetchFeed(tag ?? undefined),
  });

 staleTime   받아둔 값을 얼마 동안 "쓸 만하다" 고 볼지
             이 시간 안에는 다시 안 물어본다

 gcTime      아무도 안 보는 값을 얼마 동안 창고에 남겨둘지
             이 시간이 지나면 지운다

 화면이 보고 있는 동안        → staleTime 이 "다시 물어볼까" 를 정한다
 화면이 떠난 뒤              → gcTime 이 "언제 버릴까" 를 정한다

// apps/web-spa/src/queries/queryClient.ts
// 받아둔 값을 얼마 동안 "쓸 만하다" 고 볼지.
// 이 시간 안에는 다시 물어보지 않는다.
const STALE_TIME_MS = 30_000;

// 아무도 안 보는 값을 얼마 동안 캐시에 남겨둘지.
// 이 시간이 지나면 캐시에서 지워진다 — 다시 열면 처음부터다.
const GC_TIME_MS = 5 * 60_000;

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: STALE_TIME_MS,
      gcTime: GC_TIME_MS,
    },
  },
});

 전체 → 카페 → 전체 → 카페  (30초 안에)

 staleTime 0 (기본값)      요청 2번   화면은 즉시 채워지고 뒤에서 다시 받는다
 staleTime 30초           요청 0번   30초 안이니 물어볼 이유가 없다

 staleTime 0 · gcTime 5분 으로 두고
 화면을 떠난 뒤 60초를 흘려보냈다

 → 값은 창고에 그대로 있다
 → 다시 열면 그 낡은 값을 먼저 보여주고, 동시에 새로 물어본다

 거의 안 바뀌는 것        길게
 (태그 목록, 프로필 기본 정보)

 자주 바뀌는 것           짧게
 (좋아요 수, 댓글 수, 알림 개수)

 지금 이 순간이 중요한 것  0
 (재고 수량, 남은 좌석)