/api 프리픽스 추가에 따른 원활한 마이그레이션

문제상황

기존에 페이지 이동을 생각하지 않고, API를 설계했었습니다. 이로인해 페이지 이동 요청과 데이터 요청에 대한 URL이 동일해지는 문제가 발생했습니다.

이제서야 대체 왜 /api 프리픽스를 붙이는지 이해할 수 있었습니다. 백엔드가 제공하는 데이터(=API 요청)”와 일반 웹 페이지 요청(=프론트엔드 라우팅)을 구분하기 위해서라는 이론적인 말을 예전에는 봐도 이해하지 못했거든요.

해결 과정

해결은 간단하게 백엔드 /api 프리픽스를 붙이는 것이었습니다. 그러나 문제는, 이미 기존의 API 문서를 기반으로 개발이 진행 중이라는 점이었습니다.

코드 한줄 한줄 찾아가며, 수정을 하기에는 품이 많이 들고, 다른 팀원들에게 이 사실을 주지 시키는 것도 쉽지 않으리라 생각했습니다.

그래서 저는 기존 코드와 코드 스타일을 최소한으로 수정하는 방식을 찾고자 했습니다.

1. axios 클라이언트 추상화로 프론트엔드 자동화

axios 클라이언트를 추상화하여 baseURL: '/api'를 설정함으로써, 팀원들은 기존처럼 /users/me로 요청하면 자동으로 /api/users/me로 변환되도록 했습니다.

// api/client.js
const client = axios.create({
  baseURL: '/api',
  withCredentials: true
});

이를 통해 기존 코드 수정을 최소화하고, 팀원들은 /api 프리픽스를 신경 쓰지 않고 개발할 수 있었습니다.

2. Vite 프록시로 개발 환경 CORS 해결 및 백엔드 깔끔화

개발 환경에서 프론트엔드(localhost:5173)와 백엔드(localhost:8000)의 도메인이 달라 CORS 문제가 발생했습니다. 또한 HTTP-Only 쿠키 기반 인증 방식에서는 same-origin 요청이 필수였습니다.

Vite 프록시를 설정하여 /api로 시작하는 요청을 자동으로 백엔드로 라우팅하고, rewrite 옵션으로 백엔드에 전달될 때는 /api를 제거하도록 했습니다.

// vite.config.js
proxy: {
  '/api': {
    target: 'http://localhost:8000',
    changeOrigin: true,
    rewrite: (path) => path.replace(/^\/api/, '')
  }
}

이를 통해:

프론트엔드는 /api/users/me로 요청
프록시가 localhost:8000/users/me로 변환하여 전달
백엔드는 /api 없이 깔끔하게 /users/me로 라우팅 작성

결과적으로 CORS 문제를 해결하고, HTTP-Only 쿠키도 자동 전달되며, 백엔드 코드의 독립성도 확보할 수 있었습니다.

3. API 통신 규칙 문서화로 팀 컨벤션 통일

이러한 변경 사항을 팀원들과 공유하기 위해 “API 통신 규칙”을 작성했습니다.() 프론트엔드 페이지 이동 시에는 <Link> 컴포넌트를, 백엔드 데이터 요청 시에는 client(axios)를 사용하도록 명확히 구분했습니다. (물론 이로인해 팀원들이 <a href>도 편하게 사용하길 원해서 수정했던 인증방식이 조금 무용해졌지만요.)

이를 통해 팀원들이 일관된 방식으로 개발할 수 있었고, 코드 리뷰 시 혼란을 줄일 수 있었습니다.

☀️ Log