-- 토큰 만료와의 혈투 기록 --

프론트엔드를 하다보면, 그 어떤 api보다도 나를 가장 괴롭히는게 등장한다

바로 토큰 만료(401)

이번 글은

“처음에 대충 회사 코드 ctrl c + ctrl v 했다가 혼나서 결국 프로젝트 갈아엎고 다시 처음부터 axios 인터셉터 설계하게 된 이야기”

1. 시작은 항상 **복붙**이었다.

솔직히 말하면 인터셉터 만들 여유보다는 화면 구성하고싶은 맘이 조급했다.

백오피스를 마이그레이션 하라는 지시를 받았고, 인터셉터 그까이거 그냥 사용하던거 쓰면 되는거 아님? 당연히 이렇게 시작했다.

나는 그냥 옛날 코드 가져와 붙였고, 아무 생각 없이 진행하고 있었다.

근데 코드리뷰에서 멘토님이 한 말씀

기존거 가져다쓰지 마시고 처음부터 머리 박아가면서 만들어보시죠.

네..? 다시요..?

그렇게 나는 다시 401을 맞았다.

그래서 진짜로 인터셉터가 어떤 구조로 작동해야 하는지, 토큰 로직은 어떻게 구성해야 하는지 기본부터 다시 뜯어보기로 했다.

사실 이번 인턴 면접에서 토큰 기반 인증에 관한 질문이 있었고, (현 멘토님이 내 면접관이셨다)

한 페이지에서 여러 요청이 동시에 401 에러가 나오면 어떻게 해결하는지에 대해 여쭤보셨다.

나는 그것까지는 생각을 해본 적이 없어서 잘 모르겠다고 답 했었고?? 두고두고 맘에 남았다.

그래서 기존 프로젝트 axios 인터셉터 보고 “오 이렇게 만드는구나. 설계가 잘 되어있구나” 하고 그대로 갖다 썼던 마음이 큰 것 같다.

2. 첫 삽질: 401 해결하려다 403 맞기

나는 빠르게 at 만료 감지를 만들고, refresh api도 붙였다.

그리고 좀 기다려서 만료되었을 때 나의 시나리오

1. 오래된 at로 api 호출
2. 서버가 401 던짐
3. 인터셉터가 refresh 호출
4. 새 토큰으로 요청 재시도

… 되어야 하는데

1. 만료된 at로 api 호출 -> 401 err
2. 자동적으로 refresh api 호출 -> 403 err

아니 왜 재발급 한번도 못했는데 왜 403 나옴?

이 악몽같은 현상으로 하루종일 삽질만 했다.

재발급 시마다 alert도 띄워보고, Authorization 헤더도 다시 붙여보고, 인터셉터 바깥에서 refresh 호출 성공하는것도 확인했는데,,

원인이 걍 퐝당했음.

at와 rt의 유효기간이 같았던 것임!!! 아!뿔!싸!

기존 인터셉터도 이거 처리가 안되어있더라!

너무 모르겠어서 jwt.io에서 token 까보고 알았다.

at가 만료되었을 때 rt도 만료가되어 refresh를 할 수 있는 시간이 없었던 것이다.

accessToken 만료 → refresh 요청 시도 근데 refreshToken도 이미 만료 → 403

그래서 당연히 403이 나는 구조였다.

근데 백엔드를 바꿔달라고 할 수가 없는 상황

이걸 계기로 오랜만에 조금 머리를 굴려보았다.

3. 자동 재발급? 그건 좀 아닌것같아요.

처음에는 이런 식의 자동 로직을 생각했다.

사용자가 뭘 하든 at 만료 5분전에 자동으로 refresh 하자

근데 이 생각을 말씀드렸더니 멘토님이 말씀하셨다.

사용자가 아무 행동도 안하는데 알아서 재발급 하는건 아닌 것 같아요!

맞말임. 아무래도 백오피스다보니까 보안적인 부분도 고려를 했어야했다.

그래서 방향을 바꿨다.

사용자가 실제 api 요청 시 만료 시간이 5분 이하라면 그때 refresh 하자

즉 활성 사용자만 재발급 → 비활성 사용자 세션은 종료

   // 만료 5분 이하 + 아직 자동 갱신 안한 경우
    if (diff <= 5 * 60_000 && !hasRefreshOnce) {
      // 이미 다른 요청이 재발급 중이면 → Queue에 push
      if (isRefreshing) {
        return new Promise((resolve, reject) => {
          queue.push({ resolve, reject, config })
        })
      }

      isRefreshing = true

      try {
        const res = await axios.post<ApiResponse<string>>(
          `refresh api url`,
          { headers: { Accept: 'application/json' }, withCredentials: true }
        )

        if (res.data.code !== '0000') {
          throw new Error('refresh 실패')
        }

        const newAT = res.data.result

        setAccessTokenState(newAT)
        setRefreshOnce(true)

        config.headers.Authorization = newAT

        processQueue(null, newAT)

        return config
      } catch (err) {
        processQueue(err, undefined)

        authReset()
        reset()

        window.location.assign('/')
        return Promise.reject(err)
      } finally {
        isRefreshing = false
      }

4. 동시 요청 문제 → Pending Queue 도입

다음 문제는 이거였다. 이거는 내가 면접 때 질문을 받고 대답을 못했던 그 문제이기도 한데

• A API 요청 시 → 토큰 만료 → refresh 시작
• 그 사이에 B API 요청 → 또 토큰 만료 → refresh 또 호출

이러면 refresh api가 동시에 여러번 호출되며 경합이 발생한다.

그래서 필수적으로 refresh 중엔 다른 요청을 멈춰서 줄세우는 로직이 필요하였다.

그것이 바로 pending queue

내가 자료구조 수업에서 듣고 코테 풀때만 쓰던 큐를 진짜 써보는 날이 오다니

let isRefreshing = false
let queue: PendingReq[] = []

const processQueue = (error: unknown | null, token?: string) => {
  queue.forEach(({ resolve, reject, config }) => {
    if (error) return reject(error)

    if (token) config.headers.Authorization = token

    resolve(api.request(config))
  })
  queue = []
}

요약하자면

• refresh 중이면 → 요청을 queue 에 쌓아둠
• refresh 끝나면 → queue에 있던 요청들을 새 토큰으로 재요청

이렇게 하면 동시 재발급 요청 문제는 해결된다.

5. 세션 만료 경고가 여러 번 뜨는 문제

아 근데 산넘어 산이라더니 에베레스트가 나옴

refresh 실패(401/403) → 로그아웃 처리할 때 다음과 같은 코드가 있었다.

alert("세션이 만료되었습니다. 다시 로그인해주세요")

근데 api 여러개가 동시에 터지면서 alert이 여러개가 떴던것임! alert 확인 버튼 연타함

그래서 로그아웃이 한 번만 실행되게 하기 위해서 zustand에 isLoggingOut state를 추가하여 해결하였다.

    const { isLoggingOut, setIsLoggingOut, authReset } = useAuthStore.getState()
    const { reset } = useUserStore.getState()

    if (isLoggingOut) {
      return Promise.reject(error)
    }

    if (status === 401 || status === 403) {
      setIsLoggingOut(true)

      authReset()
      reset()

      alert('세션이 만료되었습니다. 다시 로그인해주세요')
      window.location.assign('/')
    }

근데 왜 isLoggingOut 초기화가 안돼요? 문제 발생

두번째 세션 만료 로그아웃 때, 401 떴는데 로그아웃이 안되더라

그건 내가 isLoggingOut 상태값을 zustand persist 미들웨어에 넣어놨기 때문이었다. 그래서 persist partialize 설정해서 해결하였다. ㅎㅎ 바보

6. 최종 Axios 인터셉터 코드

삽질 끝에 만들어진 인터셉터 구조는 다음과 같다.

• 토큰 만료 5분 이하 → refresh
• refresh 동안 다른 요청은 pending queue
• refresh 실패 → 로그아웃
• alert 중복 방지 → isLoggingOut
• accessToken, refreshToken 상태는 zustand에서 관리
• Authorization 헤더 자동 주입

import { useAuthStore } from '@/entities/user/store/auth.store'
import { useUserStore } from '@/entities/user/store/user.store'
import axios, {
  AxiosError,
  type AxiosInstance,
  type AxiosRequestConfig,
  type AxiosResponse,
  type InternalAxiosRequestConfig,
} from 'axios'
import type { ApiResponse } from './api.type'

// --------------------
// axios 기본 객체
// --------------------

const BASE_URL = 'example url'

export const api: AxiosInstance = axios.create({
  baseURL: BASE_URL,
  withCredentials: true,
  headers: {
    Accept: 'application/json',
  },
})

// --------------------
// 재발급 큐 로직
// --------------------

let isRefreshing = false

type PendingReq = {
  resolve: (
    value: InternalAxiosRequestConfig<any> | PromiseLike<InternalAxiosRequestConfig<any>>
  ) => void
  reject: (error?: unknown) => void
  config: InternalAxiosRequestConfig
}

let queue: PendingReq[] = []

const processQueue = (error: unknown | null, token?: string) => {
  queue.forEach(({ resolve, reject, config }) => {
    if (error) {
      return reject(error)
    }

    if (token) {
      config.headers = config.headers ?? {}
      config.headers.Authorization = token
    }

    resolve(api.request(config))
  })
  queue = []
}

// --------------------
// 요청 인터셉터
// --------------------

api.interceptors.request.use(
  async (config) => {
    const {
      sessionExpireAt,
      hasRefreshOnce,
      refreshTokenState,
      accessTokenState,
      setAccessTokenState,
      setRefreshOnce,
      authReset,
    } = useAuthStore.getState()

    const { user, reset } = useUserStore.getState()

    if (accessTokenState) {
      config.headers.Authorization = accessTokenState
    }

    if (!sessionExpireAt || !refreshTokenState) return config

    const diff = Number(sessionExpireAt) - Date.now()

    // 만료 5분 이하 + 아직 자동 갱신 안한 경우
    if (diff <= 5 * 60_000 && !hasRefreshOnce) {
      // 이미 다른 요청이 재발급 중이면 → Queue에 push
      if (isRefreshing) {
        return new Promise((resolve, reject) => {
          queue.push({ resolve, reject, config })
        })
      }

      isRefreshing = true

      try {
        const res = await axios.post<ApiResponse<string>>(
          `refresh api url`,
          { headers: { Accept: 'application/json' }, withCredentials: true }
        )

        if (res.data.code !== '0000') {
          throw new Error('refresh 실패')
        }

        const newAT = res.data.result

        setAccessTokenState(newAT)
        setRefreshOnce(true)

        config.headers.Authorization = newAT

        processQueue(null, newAT)

        return config
      } catch (err) {
        processQueue(err, undefined)

        authReset()
        reset()

        window.location.assign('/')
        return Promise.reject(err)
      } finally {
        isRefreshing = false
      }
    }

    return config
  },
  (error) => Promise.reject(error)
)

// --------------------
// 응답 인터셉터
// --------------------

api.interceptors.response.use(
  (response: AxiosResponse) => response,
  async (error: AxiosError) => {
    const status = error.response?.status
    const { isLoggingOut, setIsLoggingOut, authReset } = useAuthStore.getState()
    const { reset } = useUserStore.getState()

    if (isLoggingOut) {
      return Promise.reject(error)
    }

    if (status === 401 || status === 403) {
      setIsLoggingOut(true)

      authReset()
      reset()

      alert('세션이 만료되었습니다. 다시 로그인해주세요')
      window.location.assign('/')
    }

    return Promise.reject(error)
  }
)

// --------------------
// api wrapper
// --------------------

export const get = async <TResponse>(url: string, params?: any, config?: AxiosRequestConfig) => {
  const res = await api.get<TResponse>(url, { params, ...config })
  return res.data
}

export const post = async <TResponse>(url: string, data?: any, config?: AxiosRequestConfig) => {
  const res = await api.post<TResponse>(url, data, config)
  return res.data
}

export const put = async <TResponse>(url: string, data?: any, config?: AxiosRequestConfig) => {
  const res = await api.put<TResponse>(url, data, config)
  return res.data
}

export const del = async <TResponse>(url: string, params?: any, config?: AxiosRequestConfig) => {
  const res = await api.delete<TResponse>(url, { params, ...config })
  return res.data
}

export default { get, post, put, del }

7. 정리하자면..

이번에 인터셉터를 처음부터 설계하면서 느낀 점:

• 토큰 구조를 이해해야 한다
• 세션 만료 UX까지 고려해야 한다
• 동시 요청 문제까지 잡아야 한다
• 상태관리까지 연계해야 한다

인터셉터는 그냥 훅 두 개가 아니라 프로젝트의 전체 인증 흐름을 담당하는 중요한 부분임을 깨달았다.

그리고 무엇보다:

절대… 생각 안하고 코드 복붙부터 시작하지 말자.