Axios 사용법: React Next.js에서 API 요청 구조 잡는 법

실습 경로: 현재 ZIP → 전체 코드. 먼저 설명에서 지정한 파일만 읽고, 설정·테스트 파일은 필요한 때 확인하세요.

목표: Axios 인스턴스·HTTP 오류·취소를 React의 로딩 상태와 연결합니다. 선수 지식은 Promise, HTTP, React Effect입니다.

Axios와 fetch를 요구에 따라 선택합니다

Axios는 HTTP 요청 라이브러리입니다. 인스턴스 공통 설정과 인터셉터가 필요한 프로젝트에서 사용할 수 있으며 React·Next.js에 필수인 패키지는 아닙니다. Next.js 서버 fetch의 캐시 옵션은 Axios에 자동 적용되지 않습니다. TanStack Query는 서버 상태 관리 도구로 Axios 또는 fetch와 별도로 선택합니다.

응답과 오류의 구조를 구분합니다

Axios의 response.data는 응답 본문이고 status는 상태 코드입니다. 기본 validateStatus는 2xx를 성공으로 보지만 이를 변경하면 404도 resolve할 수 있습니다. axios.isAxiosError로 좁힌 뒤 response가 있으면 HTTP 응답, request만 있으면 응답 미수신, 그 밖에는 설정·코드 오류를 살펴봅니다. 브라우저 CORS 차단과 서버 중단은 error.message만으로 확정할 수 없습니다.

하나의 인스턴스에서 조회 함수를 만듭니다

lib/api.ts는 브라우저의 같은 출처 /api를 baseURL로 사용합니다. 상대 baseURL을 그대로 Node.js에서 호출하는 독립 스크립트에 복사하지 마세요. 서버에서 사용하려면 서버용 절대 URL과 인증 전달 정책을 따로 만듭니다. 이 실습에는 토큰 주입이 필요하지 않습니다. 공용 테스트 API에 실제 토큰을 보내는 인터셉터를 작성하지 않습니다.

Effect 종료 시 취소와 UI 갱신을 함께 막습니다

아래 전체 프로젝트는 1번·2번·없는 글을 선택합니다. 선택이 바뀌면 새 AbortController를 만들고 이전 Effect의 active를 false로 바꾼 뒤 abort합니다. 이미 완료된 Promise callback이 늦게 실행되더라도 이전 결과가 현재 화면을 덮지 않게 합니다. 이전 요청의 finally가 새로운 로딩 상태를 끄는 패턴은 쓰지 않습니다.

취소는 사용자에게 실패 오류로 표시하지 않습니다. CancelToken은 deprecated이므로 새 예제는 signal을 사용합니다. abort는 클라이언트의 대기를 취소하며 이미 서버에서 처리한 저장 작업을 되돌리는 트랜잭션은 아닙니다.

직접 확인할 결과

npm install, npm run build, npm run start 후 /를 엽니다. 1은 첫 글, 2는 둘째 글, 99는 글이 없습니다가 기대 결과입니다. Network에서 느린 연결로 바꾸고 빠르게 1→2를 선택해 오래된 응답이 화면을 되돌리지 않는지 보세요. 연결을 끊으면 일반 오류가 표시되어야 합니다. 이 브라우저 조작은 별도 확인 과제이며 로컬 HTTP 응답 검사와 구분합니다.

POST와 인터셉터로 확장할 때

api.post(‘/posts’, values)는 서버 POST 구현이 있을 때 추가합니다. 현재 실습은 읽기 전용이므로 POST는 405가 정상입니다. JSONPlaceholder 같은 공개 모의 API의 성공 응답은 실제 저장을 뜻하지 않습니다. 인터셉터를 컴포넌트에서 등록한다면 반환 ID를 보관해 cleanup에서 eject해야 중복 등록을 피할 수 있습니다. 401 자동 갱신은 재시도 횟수와 동시 요청을 별도로 설계합니다.

관련 학습 자료

• 공식 문서 보기
• Next.js App Router 학습 순서: 라우팅, 렌더링, SEO, 배포까지
• Next.js 보안 패치 기준: v16.2.5 릴리스로 영향 범위 점검하기
• Firebase 초기화 구조: Next.js firebase.ts 설계 기준

# Axios 요청과 취소

Node.js 20.9 이상(검증24.19.0). npm install → npm run build → npm run start. 개발은 npm run dev.
/ 화면에서 1·2·없는 글 선택. /api/posts/1·2는200, /api/posts/99는404. 저장·인증·외부 API 없음.
Axios 1.20.0, Next.js16.3.5, React19.3.0. 로컬 HTTP·build 검증, 브라우저 빠른 선택·네트워크 차단은 별도 확인.

"use client";
import { useEffect, useState } from "react";
import axios from "axios";
import { getPost, type Post } from "../lib/api";
type State =
  | { status: "loading" }
  | { status: "error"; message: string }
  | { status: "success"; post: Post };
export default function PostPanel() {
  const [id, setId] = useState(1);
  const [state, setState] = useState<State>({ status: "loading" });
  useEffect(() => {
    const controller = new AbortController();
    let active = true;
    setState({ status: "loading" });
    getPost(id, controller.signal)
      .then((post) => {
        if (active) setState({ status: "success", post });
      })
      .catch((error) => {
        if (!active || axios.isCancel(error)) return;
        const message =
          axios.isAxiosError(error) && error.response?.status === 404
            ? "글이 없습니다."
            : "요청에 실패했습니다.";
        setState({ status: "error", message });
      });
    return () => {
      active = false;
      controller.abort();
    };
  }, [id]);
  return (
    <section>
      <label>
        글 번호{" "}
        <select
          value={id}
          onChange={(event) => setId(Number(event.target.value))}
        >
          <option value={1}>1</option>
          <option value={2}>2</option>
          <option value={99}>없는 글</option>
        </select>
      </label>
      {state.status === "loading" ? (
        <p role="status">불러오는 중</p>
      ) : state.status === "error" ? (
        <p role="alert">{state.message}</p>
      ) : (
        <h2>{state.post.title}</h2>
      )}
    </section>
  );
}

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ id: string }> },
) {
  const { id } = await params;
  if (!["1", "2"].includes(id))
    return Response.json({ message: "글이 없습니다." }, { status: 404 });
  return Response.json({
    id: Number(id),
    title: id === "1" ? "첫 글" : "둘째 글",
  });
}

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <body>{children}</body>
    </html>
  );
}

import PostPanel from "./PostPanel";
export default function Page() {
  return (
    <main>
      <h1>Axios 요청과 취소</h1>
      <PostPanel />
    </main>
  );
}

import axios from "axios";
export const api = axios.create({ baseURL: "/api", timeout: 5000 });
export type Post = { id: number; title: string };
export async function getPost(id: number, signal: AbortSignal) {
  const response = await api.get<Post>("/posts/" + id, { signal });
  return response.data;
}

/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/types/routes.d.ts";
import "./.next/types/root-params.d.ts";

// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

{
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build --webpack",
    "start": "next start",
    "typecheck": "next typegen && tsc --noEmit"
  },
  "engines": {
    "node": ">=20.9.0"
  },
  "dependencies": {
    "next": "16.3.5",
    "react": "19.3.0",
    "react-dom": "19.3.0",
    "axios": "1.20.0"
  },
  "devDependencies": {
    "typescript": "7.0.2",
    "@types/react": "19.3.0",
    "@types/react-dom": "19.3.0",
    "@types/node": "22.20.2"
  }
}

{
  "compilerOptions": {
    "target": "ES2017",
    "lib": ["dom", "esnext"],
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "react-jsx",
    "plugins": [
      {
        "name": "next"
      }
    ],
    "allowJs": true,
    "incremental": true
  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    ".next/types/**/*.ts",
    ".next/dev/types/**/*.ts"
  ],
  "exclude": ["node_modules"]
}

실제 검증: next build exit 0; 로컬 API 1·2 200/없는글404/POST405 확인. 브라우저 취소 경합은 확인 과제. 코드 뷰어와 ZIP의 모든 파일을 바이트/복사 텍스트로 대조했습니다.

공식 자료 재확인: 2026-09-12. 이 글의 실행하지 않은 브라우저/배포 점검은 독자 확인 과제로 구분합니다.

• https://axios-http.com/docs/handling_errors
• https://axios-http.com/docs/cancellation
• https://axios-http.com/docs/interceptors
• https://react.dev/reference/react/useEffect