Vue 3 + Vite에서 Axios API 구조 완벽 가이드

 

Vue 3 (Composition API) + Vite 기반 프로젝트에서 Axios 인스턴스를 구성하고,

기능별로 API 디렉터리를 모듈화 하여 관리하는 실전적인 구조에 대해 알아보겠습니다.

이 글에서는 axios 설정부터 인터셉터 활용, API 모듈 분리, 컴포넌트 연동, 환경 변수(. env) 사용 팁,

확장 포인트, 그리고 팀 협업 관점의 적용 사례까지 폭넓게 다룹니다.

Composition API 문법과 마크다운 형식으로 작성되었으며, 예제 코드는 Vue 3 기준으로 설명합니다.

---

1. Axios 인스턴스를 구성하는 이유와 인터셉터 원리

Axios 인스턴스를 별도로 생성하여 사용하는 것은 대규모 Vue 프로젝트에서 반복 코드를 줄이고,

설정을 일원화하기 위해 매우 유용합니다. Axios 인스턴스를 사용하면 다음과 같은 이점이 있습니다:

• 공통 설정의 중앙관리: baseURL, timeout, 공통 headers 등 기본 설정을 한 곳에서 정의해 두고 앱 전체에서 재사용할 수 있습니다. 이를 통해 여러 컴포넌트나 모듈에서 일일이 설정을 반복하지 않아도 됩니다. 예를 들어 API 서버 주소를 axios.defaults.baseURL 또는 인스턴스 생성시에 지정해 두면, 개별 요청에서 해당 주소를 생략해도 됩니다.
• 환경별 설정 분기: 개발(dev), 스테이징(staging), 운영(prod) 환경마다 API 서버 주소나 설정이 다를 경우, 빌드 모드별로 다른. env.env 값이나 설정을 적용할 수 있습니다. 하나의 인스턴스에 환경 변수로 baseURL 등을 주입하면 배포 환경에 따라 자동으로 올바른 URL을 사용하게 됩니다 (자세한 내용은 뒤 .env 섹션에서 다룹니다).
• 인증 및 공통 헤더 처리: 인증 토큰(JWT 등)을 모든 요청 헤더에 자동 첨부하거나, 특정 헤더를 공통으로 넣어야 할 때 인스턴스 레벨에서 처리할 수 있습니다. 예를 들어, 모든 요청에 Authorization 헤더로 토큰을 보내야 한다면, 인스턴스에 요청 인터셉터를 추가하여 매번 헤더를 설정하는 반복을 없앨 수 있습니다.
• 요청/응답 전처리 및 에러 처리 일원화: Axios의 인터셉터(Interceptor) 기능을 통해 요청이 보내지기 전에, 혹은 응답을 받은 후에 공통 로직을 삽입할 수 있습니다. 이를 활용하면 요청 전에 공통 헤더 설정이나 로딩 상태 표시, 응답 후에 데이터 가공이나 에러 공통 처리 등을 중앙에서 관리할 수 있습니다. 각 컴포넌트마다 중복 코드를 작성하지 않고도, 인터셉터에서 한 번에 처리하도록 설계할 수 있습니다.
• 코드 재사용성과 유지보수성: 위의 사항들이 종합되어, Axios 인스턴스를 사용하면 여러 컴포넌트에서 동일한 설정과 로직을 재사용할 수 있고 설정 변경도 한 곳에서 이루어지므로 유지보수가 훨씬 수월합니다. 예를 들어 토큰 갱신 로직이나 에러 메시지 처리 방식을 수정해야 할 때, 인터셉터 로직만 고치면 전체에 적용되므로 일관성을 유지할 수 있습니다.

인터셉터(Interceptor)의 작동 원리

Axios 인스턴스를 만들었다면,

instance.interceptors 객체를 통해 요청(request)과 응답(response)에 대한 인터셉터를 등록할 수 있습니다.

인터셉터는 미들웨어처럼 동작하여 HTTP 요청이 나가기 전이나

응답이 들어온 직후에 특정 코드를 실행할 수 있게 해줍니다.

기본 문법은 다음과 같습니다:

// Axios 인스턴스 생성 (예: src/api/index.js)
import axios from 'axios';

const api = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL  // 환경변수에서 API 기본 URL 설정
});

// 요청 인터셉터 추가
api.interceptors.request.use(
  config => {
    // 요청 보내기 전에 수행할 작업
    return config;
  }, 
  error => {
    // 요청 에러가 발생했을 때 처리
    return Promise.reject(error);
  }
);

// 응답 인터셉터 추가
api.interceptors.response.use(
  response => {
    // 응답 데이터를 가공하거나 바로 반환
    return response;
  },
  error => {
    // 응답 에러 공동 처리
    return Promise.reject(error);
  }
);

export default api;

위 코드에서 요청 인터셉터는 request.use를 통해 등록되며 요청이 보내지기 직전에 호출됩니다.

여기서 config 객체를 조작하여 헤더를 추가하거나 콘솔 로그를 남기는 등 작업을 한 뒤

수정된 config를 반환하면 실제 네트워크 요청에 반영됩니다.

응답 인터셉터는 response.use를 통해 등록되고,

서버로부터 응답이 도착하면 then/catch로 개별 처리하기 전에 인터셉터가 먼저 실행됩니다.

첫 번째 콜백은 성공 응답에 대한 처리를, 두 번째 콜백은 에러 응답에 대한 처리를 담당합니다.

📌 참고: Axios 인터셉터는 등록된 순서대로 실행됩니다.
또한 여러 개의 인터셉터를 체인처럼 연결할 수도 있습니다.
예를 들어 요청 인터셉터를 2개 등록하면,
먼저 등록된 인터셉터가 실행되고 return config 한 결과를 다음 인터셉터가 이어받아 처리합니다.
응답 인터셉터도 마찬가지로 등록 순으로 적용됩니다.
인터셉터 내부에서 Promise.reject이나 에러를 던지면
그 이후 정상 응답 인터셉터는 건너뛰고 바로 에러 처리가 이루어집니다.

이제 각각 요청 단계와 응답 단계에서 인터셉터를 활용하는 실전 예시와 팁을 알아보겠습니다.

---

2. 요청 인터셉터: 실전 예시 및 보안/UX 처리 전략

요청 인터셉터는 HTTP 요청이 보내지기 전에 호출되므로,

보안 관련 처리나 사용자 경험(UX) 개선 작업을 넣기에 적합합니다. 주요 활용 사례와 전략은 다음과 같습니다:

• 인증 토큰 자동 첨부 (보안): 앞서 언급한 대로, 로그인 후 발급받은 토큰(JWT 등)을 모든 요청 헤더에 넣어야 하는 경우 요청 인터셉터에서 일괄 처리합니다. 예를 들어, localStorage나 Pinia/Vuex 등에 저장된 토큰을 꺼내와 요청 헤더에 추가할 수 있습니다. 이렇게 하면 각 API 함수나 컴포넌트에서 일일이 토큰을 넣지 않아도 되고, 토큰 갱신 시에도 한 곳만 수정하면 되므로 보안 및 편의성이 향상됩니다. 구현 예시는 다음과 같습니다:위 코드처럼 설정하면, authToken이 존재할 때 모든 요청에 Authorization: Bearer <token> 헤더가 자동 첨부됩니다. 토큰이 없거나 만료된 경우에는 헤더가 붙지 않으므로, 백엔드에서 401 Unauthorized 응답을 주면 이후 응답 인터셉터에서 처리하게 됩니다.
• // 요청 인터셉터에서 Authorization 헤더 추가 예시 api.interceptors.request.use(config => { const token = localStorage.getItem('authToken'); // 토큰 저장소에서 가져오기 if (token) { config.headers.Authorization = `Bearer ${token}`; } return config; }, error => Promise.reject(error));
• 요청 로딩 상태 관리 (UX): 사용자에게 로딩 중 피드백을 주기 위해, 요청이 시작될 때 로딩 상태를 표시하고 응답이 완료되면 숨기는 패턴을 사용할 수 있습니다. 예를 들어 전역 상태(store)의 isLoading 값을 요청 인터셉터에서 true로 설정하고, 응답 인터셉터에서 false로 되돌리는 전략을 씁니다. 또는 단순히 document.body에 로딩 스피너를 추가/제거하는 식으로 구현할 수도 있습니다. 이를 통해 API 호출이 지연될 때 사용자가 무작정 기다리기보다 진행 중임을 알 수 있어 UX를 높일 수 있습니다.
• 요청 로그 & 디버깅: 인터셉터를 활용해 모든 요청의 URL, 파라미터 등을 console.debug로 출력하거나, 개발 모드에서만 로그를 남기는 것도 가능합니다. 이는 디버깅에 도움이 되며, 문제 발생 시 어떤 요청이 있었는지 추적할 수 있습니다. 다만, 콘솔 로그는 개발 환경에서만 사용하고, 운영 환경에서는 지나친 정보 노출이 없도록 조건부로 넣는 것이 좋습니다.
• 기타 요청 전 처리: 필요에 따라 요청 데이터를 직렬화/암호화하거나, 특정 API 키를 쿼리 파라미터에 붙이는 작업도 인터셉터에서 할 수 있습니다. 예를 들어 모든 API 요청에 ?lang=ko 같은 파라미터를 붙여 다국어 처리를 하거나, GraphQL같이 특수한 요청 구조를 사용할 때 요청 본문을 변환하는 등의 전처리를 할 수 있습니다.

💡 Tip: 인터셉터 로직이 복잡해지면 별도의 유틸 함수로 분리하는 것이 좋습니다.
예를 들어 토큰 첨부 로직을 attachAuthToken(config) 함수로 뽑아내거나,
로딩 표시 로직을 전역 LoadingService.start()/stop() 형태로 추상화하면 인터셉터 내부를 깔끔하게 유지할 수 있습니다.

---

3. 응답 인터셉터: 실전 예시 및 보안/UX 처리 전략

응답 인터셉터는 서버로부터 응답이 도착한 직후 (컴포넌트에서 .then이나 await로 처리하기 전에) 호출되며,

공통 에러 처리나 응답 데이터 가공, 사용자 알림 등에 활용됩니다.

실전 전략과 예시는 다음과 같습니다:

• 글로벌 에러 처리 및 보안 대응: 가장 흔한 패턴은 인증 만료나 권한 오류 등의 공통 에러를 응답 인터셉터에서 잡아내는 것입니다. 예를 들어, 서버가 401 Unauthorized 상태 코드를 응답하면 토큰 만료로 보고 인터셉터에서 자동으로 로그아웃 처리하거나 로그인 페이지로 리디렉션 할 수 있습니다. 아래는 그런 처리를 하는 코드 예시입니다:위 인터셉터 예시는 공통적인 에러 상황에 대해 선처리하는 모습입니다. 401이면 토큰을 지우고 로그인 화면으로 보내거나, 403이면 권한 없음 안내를 하고, 500대 오류이면 콘솔에 로그를 남기고 사용자에게 일반적인 오류 메시지를 표시합니다. 이런 처리를 하면 각 컴포넌트마다 동일한 에러 처리 코드를 반복하지 않아도 되고, 보안 상 중요한 조치(토큰 만료 시 로그아웃 등)를 빠뜨리지 않도록 중앙에서 관리할 수 있습니다. 필요에 따라 특정 에러 코드에 대한 맞춤 처리도 가능합니다 (예: 백엔드가 커스텀 에러 코드를 내려줄 경우 switch문으로 분기 처리).

api.interceptors.response.use(
  response => {
    // 정상 응답은 그대로 반환
    return response;
  },
  error => {
    if (error.response) {
      const status = error.response.status;

      if (status === 401) {
        // 401 Unauthorized: 인증 만료 처리
        // 예: 스토리지의 토큰 제거 및 로그인 페이지 이동
        localStorage.removeItem('authToken');
        router.push('/login'); // vue-router 사용 가정
      } else if (status === 403) {
        // 403 Forbidden: 권한 없음
        alert('권한이 없습니다. 관리자에게 문의하세요.');
      } else if (status >= 500) {
        // 5xx 서버 오류: 사용자에게 알림
        console.error('Server error:', status);
        alert('서버 오류가 발생했습니다. 잠시 후 다시 시도해주세요.');
      }
    }

    // 위에서 처리 후에도 에러를 다시 던져주어
    // 개별 요청에서도 필요하면 추가 처리 가능
    return Promise.reject(error);
  }
);

• 응답 데이터 가공: API 응답 데이터를 모든 곳에서 일관된 형태로 쓰고 싶다면, 인터셉터에서 가공하여 반환할 수 있습니다. 예를 들어, API가 { data: ..., errorMessage: ... } 형식으로 응답하면, 인터셉터에서 response.data의 data 필드만 추려서 반환하도록 만들 수 있습니다. 이렇게 해두면 실제 컴포넌트에서는 .data까지 접근할 필요 없이 바로 원하는 데이터를 얻을 수 있어 편리합니다. 단, 일괄된 데이터 구조를 갖는 경우에만 사용하는 게 좋고, API마다 응답 형태가 많이 다르면 인터셉터에서 일괄 처리하기 어렵기 때문에 개별 호출부에서 처리하는 편이 나을 수 있습니다.
• 사용자 피드백 처리 (UX): 응답 결과에 따라 사용자 피드백을 주는 것도 고려해 볼 수 있습니다. 예를 들어, 성공 메시지가 필요한 API 요청의 경우 응답 인터셉터에서 상태 코드를 보고 토스트 알림을 띄우는 식입니다. 혹은 404 같은 에러에 대해서 "데이터를 찾을 수 없습니다" 등의 사용자용 알림을 중앙에서 처리하면 UX의 일관성을 줄 수 있습니다. 이런 글로벌 알림은 Vuetify의 Snackbar나 Vue Toast 라이브러리 등을 integrate 하여 구현하는 경우가 많습니다. (예: 401/403 시 인터셉터에서 vue-toastification의 toast.error(...)를 호출하여 사용자에게 팝업 알림을 보여주는 방식도 가능합니다.)
• 토큰 갱신 등 재요청 처리: 좀 더 고급 패턴으로, 토큰이 만료되어 401이 발생했을 때 곧바로 로그인 화면으로 보내는 대신 토큰 갱신 API를 호출하여 자동으로 토큰을 재발급받고 실패했던 요청을 재시도하는 방식을 구현할 수도 있습니다. 이 경우 응답 인터셉터에서 401을 감지하면 갱신 API (/auth/refresh 등)를 호출하고, 새 토큰을 얻은 후 원래 요청을 한 번 더 보내도록 할 수 있습니다. 이 로직은 구현 난이도가 있지만, 사용자는 모르는 사이에 세션이 연장되어 로그인 유지 경험이 개선되는 장점이 있습니다. 다만 refresh 토큰마저 만료되면 최종적으로는 로그아웃을 해야 합니다. 이러한 흐름은 보안과 UX를 모두 잡기 위한 전략이며, 팀에서 정책을 정해 구현하게 됩니다.

⚠️ 주의: 응답 인터셉터에서 에러를 Promise.rejectPromise.reject 하지 않고 먹어버리면(Promise를 reject 하지 않으면)
호출한 컴포넌트 측에서는 해당 에러를 인지하지 못합니다.
글로벌 인터셉터에서 처리한 뒤에도 각 컴포넌트에서 추가 처리가 필요할 수 있다면
Promise.reject(error)를 반환하여 이후 로직으로 에러를 전달해야 합니다.
반대로, 특정 에러를 전역에서 완전히 처리하고 컴포넌트에선 신경 쓰지 않도록 하려면
그 에러를 catch 한 후 Promise.reject를 하지 않거나, 의미 있는 값을 resolve 하도록 처리할 수도 있습니다.

---

4. API 디렉터리 구조 설계 (서비스/도메인 단위 분리)

Axios 인스턴스를 구성했다면, 이를 활용한 API 호출 함수들을 정리하는 구조를 설계해야 합니다.

규모가 작은 앱에서는 컴포넌트 내에서 axios.get('...')을 직접 호출해도 되지만,

앱이 커질수록 API 관리의 일원화와 모듈화가 필요합니다.

API 디렉터리를 만들어 기능별로 분리하면 다음과 같은 이점이 있습니다:

• 관련된 API 엔드포인트들을 한 파일에 모아 관리하여 찾기 쉽고, 수정도 용이합니다. (예: 사용자 관련 API는 userApi.js에, 상품 관련 API는 productApi.js에 정의)
• 컴포넌트들은 API 구현 상세를 알 필요 없이 해당 모듈의 함수만 호출하면 되므로, UI 코드와 데이터 통신 코드가 분리됩니다. 이는 관심사의 분리를 통해 코드의 가독성과 유지보수를 높여줍니다.
• 팀 작업 시 API 모듈별로 담당자를 나누기 좋습니다. 한 사람이 userApi.js를 작업하는 동안 다른 사람은 productApi.js를 작업하는 형태로 병렬 개발이 가능하고, 충돌이 줄어듭니다.
• 백엔드 API 명세 변경이나 공통 로직 수정 시, API 모듈 내부만 수정하면 되므로 영향 범위가 제한적입니다. 또한 API 호출 함수를 재사용함으로써 일관된 방식으로 데이터를 가져오고 처리하게 됩니다.

디렉터리 구조 예시

예를 들어, 다음과 같이 src/api/ 디렉터리를 구성할 수 있습니다:

src/api/
├── index.js         # Axios 인스턴스 생성 및 인터셉터 설정
├── auth.js          # 인증(Auth) 관련 API 함수 모듈
├── user.js          # 사용자(User) 관련 API 함수 모듈
└── product.js       # 상품(Product) 관련 API 함수 모듈

각 모듈 파일에는 해당 도메인(서비스)에 관련된 API 호출 함수들이 들어있고,

공통으로 index.js에서 내보낸 axios 인스턴스(api 등)를 사용합니다. 예시 코드를 통해 살펴보겠습니다.

• src/api/index.js: Axios 인스턴스 설정

// src/api/index.js
import axios from 'axios';

const api = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL, // 환경변수로부터 API 서버 URL 설정
  timeout: 5000, // 요청 타임아웃 5초 (필요시)
});

// 인터셉터 설정 (앞서 설명한 대로)
api.interceptors.request.use(...);
api.interceptors.response.use(...);

export default api;

• src/api/user.js: 사용자 API 모듈 예시

// src/api/user.js
import api from './index';

// 사용자 API 엔드포인트 함수들 정의
export const userAPI = {
  getProfile() {
    return api.get('/user/profile');
  },

  updateProfile(data) {
    return api.put('/user/profile', data);
  },

  uploadAvatar(file) {
    // 예시: 파일 업로드용 별도 인스턴스를 사용할 수도 있음
    return api.post('/user/avatar', file);
  }
};

• src/api/auth.js: 인증 API 모듈 예시

// src/api/auth.js
import api from './index';

export const authAPI = {
  login(credentials) {
    return api.post('/auth/login', credentials);
  },

  logout() {
    return api.post('/auth/logout');
  },

  refreshToken() {
    return api.post('/auth/refresh');
  }
};

 

위 구조에서 index.js의 api 인스턴스를 각 모듈이 import 하여 사용하고 있습니다.

예를 들어 userAPI.getProfile()을 호출하면 내부적으로 api.get('/user/profile')로 요청이 이루어지며,

여기에는 이미 설정된 baseURL이 앞에 붙고, 인터셉터 로직도 자동 적용됩니다.

따라서 컴포넌트에서는 userAPI.getProfile() 함수만 부르면 곧바로 결과를 얻거나 에러 처리가 이루어지게 됩니다.

또한 각 함수는 axios 호출 결과(Promise)를 반환하므로,

호출 측에서. then/. catch를.then/.catch 사용하거나 await으로 받을 수 있습니다.

필요에 따라 응답 데이터만 반환하도록 처리할 수도 있습니다.

(예: return (await api.get('/user/profile')). data처럼 구현하면 이 함수를 호출하는 쪽에서는. data를.data 바로 받게 됩니다.)

변형: 프로젝트 성격에 따라 디렉터리 구조를 더 세분화할 수도 있습니다.

예를 들어 위 예시에서는 모든 API 모듈이 같은 axios 인스턴스를 썼지만,

만약 여러 개의 백엔드 서비스를 호출해야 한다면 api/ 아래에 serviceA/, serviceB/ 폴더를 만들고

각 폴더별로 다른 axios 인스턴스를 가질 수도 있습니다. 또는 파일이 많아지면 modules/ 폴더 아래에 모듈들을 넣고, config/axios.js, utils/errorHandler.js 등의 파일로 나누어 관리할 수도 있습니다.

실제 현업에서는 프로젝트 규모와 팀 선호에 따라 구조를 약간씩 다르게 가져가지만,

핵심은 “axios 인스턴스 설정 파일 + 각 도메인별 API 파일”이라는 점입니다.

이 패턴은 Vue 뿐만 아니라 Nuxt 등 다른 Vue 기반 프레임워크에서도 권장되는 구조입니다.

💡 Tip: API 모듈의 함수 명은 백엔드 엔드포인트와 일치시키거나,
클라이언트에서의 역할을 드러내도록 짓는 것이 좋습니다.
예를 들어 getUserProfile vs getProfile 네이밍은 팀 컨벤션에 따라 선택하면 되고, 일관성을 유지하세요.
또한 API 함수에 JSDoc 코멘트를 붙여서 어떤 요청을 보내고 무엇을 반환하는지 명시해 두면,
다른 개발자들이 사용하거나 수정할 때 도움이 됩니다.

---

5. 컴포넌트에서 API를 호출하는 방법 (흐름 상세)

API 디렉터리를 구성한 후, 실제 Vue 컴포넌트 내에서 API를 호출하는 흐름을 살펴보겠습니다.

Composition API 스타일에서의 기본적인 사용 예는 다음과 같습니다:

<!-- 예시: UserProfileView.vue -->
<template>
  <div>
    <h1>{{ profile.name }} 님의 프로필</h1>
    <button @click="refresh">프로필 새로고침</button>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { userAPI } from '@/api/user';   // API 모듈 임포트

const profile = ref(null);

// 프로필 데이터를 서버에서 불러오는 함수
const fetchUserProfile = async () => {
  try {
    const response = await userAPI.getProfile();
    // 예: 인터셉터에서 응답 가공을 안 했다면 response.data에 실제 데이터 있음
    profile.value = response.data ?? response;
  } catch (error) {
    console.error('프로필 불러오기 실패:', error);
    // 에러는 전역 인터셉터에서 처리되었을 수 있으므로 여기서는 로그만 남김
    // 필요한 추가 처리가 있으면 수행 (예: 특정 에러메시지를 화면에 표시 등)
  }
};

// 컴포넌트 마운트 시 자동으로 호출하여 프로필 로드
onMounted(fetchUserProfile);

// 새로고침 버튼 클릭 시 API 다시 호출
const refresh = () => {
  fetchUserProfile();
};
</script>

위 코드에서 알 수 있듯이, 컴포넌트는 API 모듈로부터 가져온 함수 (userAPI.getProfile)를 호출하기만 하면 됩니다. userAPI.getProfile() 자체가 Promise를 반환하므로 await으로 받아 결과를 처리하고,

에러가 throw 되면catch로 잡아내는 표준 패턴입니다.

여기서 핵심은 컴포넌트가 Axios나 구체적인 URL 경로를 직접 다루지 않는다는 점입니다.

컴포넌트 입장에서는 그저 userAPI.getProfile이라는 함수를 호출했을 뿐이고,

내부에서 Axios 호출, 헤더 첨부, 에러 공통 처리 등이 일어나 결과가 반환됩니다.

이러한 흐름의 장점은 컴포넌트 코드가 깔끔해지고 UI 로직과 데이터 통신 로직이 분리된다는 것입니다.

컴포넌트에서는 결과를 화면에 어떻게 보여줄지, 사용자 이벤트에 어떻게 대응할지만 신경 쓰고,데이터는 API 모듈에 위임합니다. 예컨대 위 컴포넌트에서는 onMounted 시 데이터를 가져오고,

버튼 클릭 시 동일한 함수를 재사용하여 새로고침을 구현했지만, API 경로나 토큰 처리 등이 전혀 드러나지 않습니다.

또한 이 구조는 테스트와 유지보수에도 유리합니다.

API 호출 함수를 별도로 분리했으므로,

단위 테스트 시에는 해당 함수를 모의(mock)하여 컴포넌트 로직만 검증할 수 있습니다.

반대로 API 모듈을 테스트할 때는 Axios를 모킹 하여 함수가 올바른 요청을 만드는지 확인할 수도 있습니다.

실제 개발 시에는 컴포넌트와 API 모듈 사이에 한 단계 더 서비스 레이어(services/)를 넣어 비즈니스 로직을 처리한 후

API를 호출하는 구조를 취하기도 하지만, 규모가 크지 않다면 API 모듈만으로도 충분합니다.

마지막으로, 에러 처리 흐름에 대해 한 번 더 정리하면:

컴포넌트에서 API를 호출 ->

인터셉터가 설정된 경우 응답 에러를 먼저 처리 ->

그래도 Promise.rejectPromise.reject 된 에러가 컴포넌트의 catch로 전달 ->

컴포넌트에서 필요에 따라 추가 처리. 이런 순서입니다.

따라서 전역 인터셉터에서 대부분의 공통 에러를 처리하고,

컴포넌트에서는 특별한 경우에만 에러 처리를 해주는 식으로 역할을 분담할 수 있습니다.

🔍 참고: Composition API의 <script setup> 구문에서는 async setup()을 쓸 수 없기 때문에,
위 예시처럼 onMounted 안에서 async 함수를 호출하거나, 또는 즉시실행 함수 형태로 호출합니다.
예를 들어 <script setup> (async () => { await fetchUserProfile(); })(); </script>처럼 작성할 수도 있습니다.
하지만 가독성을 위해 위처럼 onMounted를 사용하는 패턴이 일반적입니다.

---

6. 환경 변수(.env) 활용 팁 및 보안 주의사항

실전 프로젝트에서는 API 서버 URL이나 각종 키를 코드에 하드코딩하지 않고 환경 변수(.env) 파일에 분리합니다.

Vue 3 + Vite 프로젝트의 경우, Vite의 환경 변수 규칙을 알아두는 것이 중요합니다:

• VITE_ 프리픽스: Vite에서는 .env 파일에 정의된 변수 중 이름이 VITE_로 시작하는 변수만 프론트엔드 앱에 노출됩니다. 이는 실수로 중요한 값을 클라이언트에 노출하지 않도록 하는 장치입니다. 예컨대 .env에 VITE_API_BASE_URL="https://api.example.com"이라고 넣으면, 코드에서 import.meta.env.VITE_API_BASE_URL로 접근 가능하지만, DB_PASSWORD="..." 같이 VITE_ 없이 정의하면 import.meta.env.DB_PASSWORD는 undefined로 나와 사용이 불가능합니다. 따라서 프론트에서 필요한 환경변수는 항상 VITE_ 접두어를 붙여야 하며, 비밀 값을 실수로 포함하지 않도록 주의해야 합니다.
• .env 파일 분리: Vite는 프로젝트 루트에 .env.development, .env.production 등의 파일을 두면 모드에 따라 자동으로 로드해 줍니다. 예를 들어 개발 환경에서는 .env.development의 값을, 프로덕션 빌드에서는 .env.production의 값을 우선 사용하게 할 수 있습니다. 이를 활용해서 개발용 API URL과 운영 API URL을 구분하면, 코드 수정 없이도 빌드 모드에 따라 다른 서버와 통신할 수 있습니다. (보통 깃에는 .env.production은 커밋하지 않고 CI/CD 환경에서 주입하거나, 안전하게 관리합니다.)
• 사용 예 (baseURL 설정): 앞서 Axios 인스턴스 생성 시 baseURL: import.meta.env.VITE_API_BASE_URL로 설정한 부분을 떠올려봅시다. 프로젝트 루트에 아래와 같은 .env 파일들을 준비해 둘 수 있습니다:이렇게 하면 개발 모드에서는 로컬호스트로 API 요청이 나가고, 배포 후에는 운영 도메인으로 나가게 됩니다.
• 주의: 경로 끝에 /를 넣을지 말지는 백엔드 설정에 맞게 일관되게 관리하세요.

# .env.development
VITE_API_BASE_URL=http://localhost:3000/api

 

• 보안 고려사항: 앞서 언급했듯, VITE_로 시작하는 변수는 프론트엔드 번들에 고스란히 포함됩니다. 즉, 사용자(클라이언트)가 웹 앱의 코드를 보면 그 값을 알 수 있다는 뜻입니다. 그러므로 절대로 비밀 값(API Secret, DB Password 등)을 VITE_ 환경변수로 넣으면 안 됩니다. 이러한 비밀 값은 백엔드에서 보호해야 하며, 프론트에는 노출되지 않도록 해야 합니다. 가령 API Key 중에 공개되어도 되는 부분 (예: Stripe의 Publishable Key)은 넣어도 되지만, Secret Key는 넣으면 안 됩니다. 또한 .env 파일들은 git에 커밋되지 않도록 .gitignore에 추가하는 것이 기본입니다. 대신 .env.example이나 README를 통해 어떤 환경변수가 필요한지만 공유하고, 실제 값은 각 개발자/서버 환경에서 주입하는 방식입니다.
• 기타 팁:
  • Vite의 import.meta.env에는 기본 내장 변수들도 있습니다. import.meta.env.MODE (현재 모드), import.meta.env.BASE_URL (기본 경로) 등도 활용 가능하지만, 대부분 큰 프로젝트에서는 필요한 값만 새로 정의해서 씁니다.
  • 환경변수 값은 문자열로 취급되므로, 숫자나 불리언을 넣으면 코드에서 파싱해야 합니다. 예: VITE_USE_MOCK="false"라고 넣어도 import.meta.env.VITE_USE_MOCK는 문자열 "false"로 오므로, 이를 JS에서 불리언으로 변환해서 써야 합니다 (혹은 "0"/"1"을 쓰거나).
  • Vue 프로젝트에서 환경변수 설정이 제대로 안 먹히는 경우, vite.config.js의 envDir나 envPrefix 옵션을 확인해보세요. 일반적으로 기본 설정이면 위 규칙이 잘 적용되지만, 간혹 monorepo 등의 구조에서는 경로를 못 찾는 경우도 있습니다.

요약하면, 환경변수는 민감정보와 분리하여 사용하되,

VITE_ 접두사 규칙과 모드별 파일을 활용하여 유연하고 안전하게 관리하는 것이 포인트입니다.

프론트엔드 환경변수는 완전한 보안 장치는 아니므로 노출되어도 되는 값들만 사용하고,

백엔드와 연계해 진짜 비밀은 지키는 전략이 필요합니다.

---

7. 확장 포인트: 에러 핸들링 훅 & Axios 래퍼 컴포저블

Axios 인스턴스와 인터셉터 기반 구조를 구축한 후에도, 프로젝트에 따라 추가로 고려할 만한 확장 포인트들이 있습니다.

여기서는 에러 핸들링 고도화와 Axios 활용 컴포저블 두 가지를 소개합니다.

글로벌 에러 핸들링 훅(Hook) 또는 유틸리티: 인터셉터에서 처리하기 어려운 복잡한 에러 처리는 별도 함수나 훅으로 분리할 수 있습니다. 예를 들어, 백엔드에서 내려오는 에러 response에 errorCode나 message 필드가 있다면 이를 해석해 사용자 친화적 메시지로 변환하는 작업을 생각해볼 수 있습니다. 이를 전역 인터셉터의 에러 처리 부분에 직접 넣으면 코드가 길어지므로, handleAPIError(error) 같은 유틸 함수를 만들어 활용합니다. 예시:

// Axios 응답 인터셉터에서 활용
api.interceptors.response.use(
  response => response,
  error => {
    // 공통 에러 핸들러 사용
    handleAPIError(error);
    return Promise.reject(error);
  }
);

위처럼 구현하면 에러 처리 로직을 한 곳에 모아서 관리할 수 있고, 필요시 team 공유도 쉬워집니다.

또 하나의 방법으로, Vue 컴포지션 API의 provide/inject를 이용해 전역 에러 핸들러를 주입해놓고,

컴포넌트 어디서든 호출할 수 있게 할 수도 있습니다.

하지만 일반적으로는 위와 같은 함수 형태나, Vuex/Pinia에 에러 상태를 저장하는 방식을 더 많이 사용합니다.

• Axios Wrapper 컴포저블: Composition API의 강력함을 활용해 API 호출을 전담하는 커스텀 컴포저블(composable)을 만들 수도 있습니다. 예컨대 useApiRequest()라는 컴포저블을 만들어 내부에서 axios 인스턴스를 사용하고, 로딩 상태, 결과, 에러 상태를 모두 reactive하게 관리하면 컴포넌트에서는 더욱 선언적으로 API 호출을 다룰 수 있습니다. 간단한 예로, 특정 요청을 보내는 컴포저블:이 컴포저블을 사용하면 컴포넌트에서는 const { loading, data, error, request } = useApiRequest(); 한 후 request('get', '/user/profile')처럼 호출하여 데이터를 가져오고, loading이나 error 상태를 활용해 UI에 로딩중 표시나 에러 메시지를 표현할 수 있습니다. 이러한 패턴은 VueUse 라이브러리의 useAxios나 useFetch 컴포저블과 유사한데, VueUse에서도 제공하는 useAxios는 Axios를 감싸 반응형 상태(로딩 여부, 완료 여부 등)를 제공하므로 활용할 만합니다.

또한 위 예시처럼 vue-toastification 등의 UI 피드백도 컴포저블 안에서 바로 사용할 수 있기 때문에,

인터셉터로 처리하기 애매한 UI 반응을 컴포저블에서 해줄 수 있습니다.

실제 사례로, Stack Overflow 등지에서는 전역 인터셉터 대신 이러한 컴포저블 방식의 API 호출을 권장하는 의견도 있습니다.

특히 컴포넌트별로 조금씩 다른 에러 처리나 후속 동작이 필요하다면,

인터셉터보다 컴포저블/훅으로 유연하게 대처하는 편이 더 깔끔할 수 있습니다.

// src/api/utils/errorHandler.js 
export function handleAPIError(error) { 
	const status = error.response?.status; 
    const errorCode = error.response?.data?.errorCode; 
    switch (errorCode) { 
    	case 'TOKEN_EXPIRED': 
            // 토큰 만료 시 재발급 시도 
            return refreshTokenAndRetry(error); 
        
        case 'VALIDATION_ERROR': 
        	// 유효성 검증 오류 처리 
            alert('입력 값을 다시 확인해주세요.'); 
            break; 
        default: 
        	// 기타 오류 공통 처리 
            alert('알 수 없는 오류가 발생했습니다.'); 
     } 
     return Promise.reject(error); 
}

// src/composables/useApiRequest.js 
import { ref } from 'vue'; 
import api from '@/api'; 

// Axios 인스턴스 
import { useToast } from 'vue-toastification'; 

// 예: 토스트 알림 라이브러리 
export function useApiRequest() { 
	const loading = ref(false); 
    const data = ref(null); 
    const error = ref(null); 
    const toast = useToast(); 
    const request = async (method, url, payload = null) => { 
    	loading.value = true; 
        error.value = null; 
        try { 
        	const response = await api[method](url, payload); data.value = response.data; 
        } catch (err) { 
        	error.value = err; 
            // 예: 에러 종류에 따라 전역 토스트 출력 
            if (err.response?.status === 403) { 
            	toast.error("세션이 만료되었습니다. 다시 로그인해주세요."); 
                } 
             } finally { 
             	loading.value = false; 
             } 
        }; 
    return { loading, data, error, request }; 
}

🔗 관련 참고: VueUse의 useAxios 컴포저블은 Axios 인스턴스를 인자로 받아 사용할 수도 있고,
React Query나 SWR처럼 요청 결과를 캐싱하거나 재사용하는 고급 기능도 제공하니,
대규모 프로젝트라면 도입을 검토해볼 만 합니다. 단, 러닝커브와 도입 비용이 있으므로 팀원들과 상의하여 결정하세요.

 

정리하면, 확장 포인트란 기본 구조 외에 프로젝트 요구사항에 따라 추가로 설계되는 부분입니다.

전역 에러 처리 훅/함수, API 호출 컴포저블 외에도,

요청 취소(Cancellation) 구현이나, 재시도 전략(exponential backoff), 응답 캐싱 등도 확장 포인트가 될 수 있습니다.

이러한 기능들은 Axios 자체 기능이나 추가 라이브러리로도 구현 가능하니, 프로젝트 규모와 필요에 맞춰 적용하면 됩니다.

---

8. 실무 적용 사례: 팀 작업 분리 기준 및 팁

마지막으로, 실제 서비스 개발 시 본 구조를 적용하면서 얻은 팀 협업 관점의 팁 몇 가지를 소개합니다.

• 모듈별 담당자 지정: API 디렉터리를 도메인별(서비스별)로 분리하면, 자연스럽게 해당 모듈의 담당자를 정할 수 있습니다. 예를 들어 user.js는 A님, product.js는 B님 식으로 맡아서 개발/유지보수하면 효율적입니다. 담당자는 자신의 모듈 내 변경이 다른 곳에 영향 주지 않도록 책임지고 관리하며, 다른 개발자는 그 모듈의 함수를 가져다 사용합니다. 이렇게 역할을 분리하면 Git 충돌도 줄어들고, 코드 소유권이 명확해져 리뷰나 수정도 수월합니다.

코딩 컨벤션 및 문서화: 팀원마다 API 함수를 만들 때 코드 스타일이 다르면 혼란이 생길 수 있습니다. 統一된 컨벤션을 정해두세요.

• 함수명은 동사+명사 (getUsers, createOrder) 형태로 짓기
• 함수는 가능하면 항상 response.data (또는 가공된 데이터)만 반환하여 일관된 반환 타입 유지
• Axios 호출 시 async/await 사용을 권장하거나, 프로미스 체인을 선호하는지 합의
• 에러 처리는 인터셉터에 맡기되, 개별 함수에서는 특별한 필요가 없으면 try/catch를 생략 (또는 모든 함수 내부에서 한 번 감싸서 특정 에러를 변환해 throw하는 식으로 처리)

그리고 이러한 규칙이나 사용 방법을 README나 위키에 문서화하여 신규 팀원이 쉽게 따라올 수 있게 합니다.

특히 API 모듈은 백엔드 명세와 직접적으로 연결되므로,

API 명세 변화에 어떻게 대응하는지(예: 모듈 내 함수 수정 + 관련 컴포넌트 영향 조사) 등에 대한 가이드도 있으면 좋습니다.

• 실제 사례: 예를 들어 필자가 참여했던 프로젝트에서는, /api/ 폴더에 10여 개의 모듈이 있었고 (예약, 결제, 회원, 상품 등), 초기에 팀원이 각각 맡아서 CRUD 함수들을 구현했습니다. 이후 다른 페이지 개발을 할 때, 이미 작성된 API 함수를 import해 쓰기만 하면 되므로 개발 속도가 빨라졌습니다. 만약 함수가 없으면 담당자에게 추가를 요청하거나, 직접 추가 구현 후 코드리뷰를 받는 식으로 진행했습니다. 이때 담당자가 아닌 사람이 모듈을 수정할 경우 반드시 리뷰어로 담당자를 지정하여 검토받도록 했습니다. 이렇게 하니 책임 구분이 확실해지고 코드 품질도 올라갔습니다.
• 다중 인스턴스 활용: 또 다른 사례로, 하나의 프로젝트에서 두 개 이상의 다른 API 서버를 불러야 했습니다 (예: 메인 서버와 통계 서버). 이때 각각 Axios 인스턴스를 만들어 api/index.js에서 export const mainAPI = axios.create(...); export const statsAPI = axios.create(...); 식으로 내보냈고, 모듈별로 적절한 인스턴스를 사용하도록 분리했습니다. 이를 통해 혼동을 줄이고, 각 인스턴스별로 다른 인터셉터 (예: 통계 API는 별도 에러 처리)도 적용했습니다. 팀에서는 이러한 구조를 문서로 남겨 새로운 API가 추가될 때 어느 인스턴스를 사용할지 판단 기준을 공유했습니다.
• 협업 시 유의점: API 모듈을 분리해도, 결국 하나의 코드베이스이므로 의존성 관리를 잘 해야 합니다. 예를 들어 auth 모듈에서 토큰을 갱신하면 user 모듈의 함수들이 영향을 받을 수 있습니다. 이럴 때는 api/index.js 인터셉터에서 토큰 변경을 처리하고 모든 모듈이 그 변경을 공유하도록 하거나, Pinia 등 전역 상태로 토큰을 관리하여 동기화해야 합니다. 팀원들 간에 이러한 상호작용을 명확히 합의해 두고 개발하면 런타임 버그를 줄일 수 있습니다.

---

정리

Vue 3 + Composition API + Vite 환경에서 Axios를 활용한 API 통신 구조를 정리해 보았습니다.

Axios 인스턴스와 인터셉터를 통한 일원화된 설정,

API 디렉터리 모듈화를 통한 체계적인 관리,

컴포넌트 분리로 인한 가독성 향상 등이 이 구조의 큰 장점입니다.

여기에 더해 환경변수를 이용한 유연한 환경 구성과, 필요시 확장 가능한 설계까지 고려하면,

중대형 규모의 Vue 프론트엔드 프로젝트에서도 효율적이고 유지보수하기 좋은 코드베이스를 만들 수 있습니다.

실무에서는 프로젝트마다 상황이 다르겠지만,

여기서 소개한 개념들과 패턴 (인터셉터 활용, 모듈 구조, 컴포저블 등)은 많은 Vue 개발자들이 추천하는 방식이며

실제로도 널리 쓰이고 있습니다.

처음 설계에 조금 공을 들이면 이후 개발 속도와 코드 품질이 향상되니,

팀원들과 충분히 논의하여 최적의 구조를 마련해 보세요.