Axios 설정

14.1.1. Axios 인스턴스 생성

• API 클라이언트는 axios.create()를 사용하여 전용 인스턴스를 생성합니다.
• 전역 axios 객체를 직접 사용하지 않습니다. 전역 설정 오염을 방지하기 위함입니다.
• 인스턴스 정의 파일은 src/api/client.ts에 작성합니다.
• 하나의 프로젝트에서 여러 API 서버와 통신해야 하는 경우, 서버별로 별도의 인스턴스를 생성합니다.

// src/api/client.ts
import axios from 'axios'
import type { AxiosInstance } from 'axios'

const apiClient: AxiosInstance = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  timeout: 30000,
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
})

export default apiClient

---

14.1.2. baseURL 환경별 설정

• baseURL은 하드코딩하지 않습니다. 반드시 환경 변수를 통해 주입합니다.
• Vite 환경 변수 규칙에 따라 VITE_ 접두사를 사용합니다.
• 환경별 .env 파일을 분리하여 관리합니다.

파일	용도	예시 값
.env.development	로컬 개발	http://localhost:8080/api
.env.staging	스테이징 배포	https://staging-api.example.com
.env.production	프로덕션 배포	https://api.example.com

• import.meta.env.VITE_API_BASE_URL로 접근하며, 타입 안전성을 위해 env.d.ts에 타입을 선언합니다.

// src/env.d.ts
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_BASE_URL: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

---

14.1.3. 기본 헤더

• Content-Type은 application/json을 기본값으로 설정합니다.
• Accept 헤더는 application/json을 기본값으로 설정합니다.
• 파일 업로드 등 Content-Type이 달라야 하는 요청은 개별 요청에서 오버라이드합니다.

// 파일 업로드 시 Content-Type 오버라이드 예시
await apiClient.post('/files/upload', formData, {
  headers: {
    'Content-Type': 'multipart/form-data',
  },
})

• 커스텀 헤더가 필요한 경우 인터셉터를 통해 동적으로 주입합니다. 인스턴스 생성 시점에 정적 값만 설정합니다.

---

14.1.4. 타임아웃 설정

• 기본 타임아웃은 30,000ms (30초) 로 설정합니다.
• 장시간 소요되는 요청은 개별 요청 옵션에서 타임아웃을 오버라이드합니다.
• 타임아웃 값은 상수로 관리합니다.

// src/api/constants.ts
export const API_TIMEOUT = {
  DEFAULT: 30000,
  UPLOAD: 120000,
  REPORT: 60000,
} as const

// 대용량 파일 업로드 시 타임아웃 오버라이드
await apiClient.post('/files/upload', formData, {
  timeout: API_TIMEOUT.UPLOAD,
  headers: {
    'Content-Type': 'multipart/form-data',
  },
})

요청 유형	타임아웃	비고
일반 API 요청	30,000ms	기본값
파일 업로드	120,000ms	요청별 오버라이드
리포트 생성	60,000ms	요청별 오버라이드

• 타임아웃 초과 시 AxiosError의 code 속성이 ECONNABORTED로 설정됩니다. 이를 기반으로 사용자에게 적절한 안내 메시지를 표시해야 합니다.