TanStack Query Key Factory 패턴으로 FSD 프로젝트의 캐시 무효화 관리하기

복잡한 상태 흐름을 Stepper로 시각화하기

PEC 과정을 통해 프로덕트 엔지니어로서 성장하며 얻은 인사이트와 변화의 기록
<h3>들어가며: 왜 PEC를 선택했는가</h3>
저는 5년 차 프론트엔드 개발자예요. 지금까지 회사에서 개발을 하면서 주로 고려하던 포인트는 제품이나 고객이 아닌, 제가 가진 기술적 역량, 일정, 팀의 리소스 등이었어요.
그러다 보니 자연스럽게 고객이 진짜 원하고 필요한 제품을 만든다기보단, 어떻게든 일정을 맞추기 위해 스펙을 축소하거나 제가 개발하기 편하게 타협하는 순간들이 많았던 것 같아요.
그러던 어느 날, 이직 준비를 하면서 가고 싶은 회사의 면접을 본 뒤 지금까지의 제 관점이 완전히 바뀌었어요. 면접에서는 어떤 트렌디한 기술을 사용했는지가 아니라,
문제는 무엇이었고 고객에게 어떤 임팩트를 줬는지, 왜 이 기술을 선택했고 적합하다고 생각했는지 같은 엔지니어와 사용자의 관점에 관한 질문들이 이어졌어요.
이때부터 사용자의 문제를 해결하는 제품 중심의 개발을 잘하고 싶다는 갈증이 생겼어요. 우연한 기회에 PEC 과정을 알게 되었고, PEC는 단순한 기술 학습을 넘어
‘제품을 만드는 사람’으로의 시야를 넓혀주는 캠프였어요.
<h3>과정을 통해 경험한 것들</h3>
PEC는 8주 동안 정규 세션과 팀 과제로 이루어져 있어요. 매주 라이브 세션에 참여해 주차 별 주제를 학습하고, 과제를 수행한 후 피드백을 받는 방식으로 진행돼요.
제가 PEC를 선택한 결정적인 이유는, 단순한 기능 구현이 아니라 ‘문제 정의’부터 시작한다는 점에서 이전의 프로젝트들과 결이 달랐기 때문이에요.
PEC를 진행하면서 제가 지금까지 얼마나 자주 문제를 해결하지 않는 솔루션을 만들어왔는지 반성하게 되었어요.
1주 차부터 4주 차까지는 문제를 정의하고, 실제 사용자 인터뷰를 기반으로 페르소나를 작성했어요. 상세한 강의 자료 덕분에,
제가 생각하는 문제점이 아니라 사용자가 정말로 불편을 겪는 부분이 무엇인지에 집중하며 진행할 수 있었어요.
이렇게 사용자 문제를 정의하고 팀의 프로젝트가 선정되면, 그다음부터는 AI를 활용해 개발을 하게 돼요. 특히 Cursor를 사용해서 바이브 코딩 형태로 전적으로 AI에게 구현을 의존하게 되는데요,
앞선 과정에서 사용자 문제를 촘촘히 정의하고 팀원들과 설계를 충분히 논의한 덕분에, AI에게 전달할 기능 요구사항을 명확하게 만들 수 있었어요.
이 과정을 통해 앞으로 개발자라는 직업의 변화, 그리고 AI가 가져다줄 미래에 대해 조금이나마 먼저 경험해볼 수 있었던 소중한 시간이었어요.
<h3>나의 변화와 성장</h3>
PEC를 수료하고 가장 달라진 점이 무엇이냐고 묻는다면, 저는 단연코 관점이라고 대답할 수 있을 것 같아요.
문제를 바라보는 관점, 사용자를 대하는 관점, 그리고 개발과 기술을 바라보는 관점까지 모두 달라졌어요.
앞으로 AI에 의해 개발자의 업무 중 특히 구현과 관련된 부분은 대부분 위임될 거라고 생각해요. 그렇다면 우리 엔지니어들에게 남은 건
문제를 정의하고, 논리적인 기준으로 기술을 선택하며, 사용자 경험 중심의 시스템을 설계하는 일이라고 생각해요.
PEC 과정을 통해 프로덕트 중심의 사고, 문제 해결 역량, 협업, AI 활용 등 정말 많은 것들을 얻어갈 수 있었어요.
<h3>함께한 사람들</h3>
PEC 7기를 함께한 팀원 재형님, 하은님과 PEC 대표 코치이신 경찬님에게 정말 많은 것을 배우고 도움을 받았어요.
특히 열정적이고 친절한 팀원들 덕분에 8주 동안 재밌고 알찬 시간을 보낼 수 있었어요.
경찬님에게는 PEC 과정뿐만 아니라 개인적인 커리어 고민이나 어려움에 대해서도 많은 상담을 드렸었는데요, 항상 친절하게 진심을 담아 조언해주시고 잘되길 응원해주셔서 정말 큰 힘이 되었어요.
<h3>마무리: 이런 사람에게 PEC를 추천해요</h3>
PEC는 단순히 구현 중심의 개발이 아니라, 문제를 정의하고 사용자 중심으로 제품을 만들며 고민하는 엔지니어로 성장하고 싶은 분들에게 추천하고 싶은 과정이에요.
<ul>
<li>
지금까지 ‘개발’만 잘하면 되는 줄 알았던 분
</li>
<li>
‘사용자’를 고민해본 적이 없는 분
</li>
<li>
협업 과정에서 ‘무엇을’ 만들지 늘 모호했던 경험이 있는 분
</li>
<li>
AI 시대, 어떤 개발자가 살아남을까 고민해본 분
</li>
</ul>
저처럼 커리어의 전환점에서 진짜 제품을 만드는 엔지니어로 성장하고 싶다면,
PEC는 분명히 많은 인사이트와 자극을 줄 거예요.
<blockquote>
제품을 만드는 엔지니어로서,
더 좋은 질문을 던질 수 있는 개발자가 되고 싶다면 
PEC를 꼭 경험해보세요.
</blockquote>
👉 <a href="https://slashpage.com/pec">PEC 알아보기</a>

프로덕트 엔지니어로 성장하기

백오피스 필터 40개를 하나의 훅으로 — useFilter 추상화로 보일러플레이트 제거하기

<h2>들어가며</h2>
백오피스 시스템에서 세션 타임아웃은 단순한 편의 기능이 아니라 보안 요구사항이다. 자리를 비운 사이 누군가 화면을 조작하는 것을 방지해야 한다. 하지만 구현해보면 의외로 고려할 것이 많다. 타이머는 어디에 둘 것인가, 활동 감지는 어떻게 할 것인가, 경고 다이얼로그는 누가 트리거하는가, 인증 상태와 어떻게 연동하는가.
이 글에서는 React 컴포넌트에 의존하지 않는 순수 타이머 모듈을 설계하고, Zustand 구독으로 인증 상태와 연동한 과정을 정리한다.
<hr>
<h2>1. 요구사항</h2>
<table>
<thead>
<tr>
<th>항목</th>
<th>내용</th>
</tr>
</thead>
<tbody>
<tr>
<td>세션 만료</td>
<td>30분 동안 활동이 없으면 자동 로그아웃</td>
</tr>
<tr>
<td>만료 경고</td>
<td>만료 5분 전 경고 다이얼로그 표시</td>
</tr>
<tr>
<td>활동 감지</td>
<td>마우스, 키보드, 클릭, 스크롤, 터치 이벤트</td>
</tr>
<tr>
<td>경고 응답</td>
<td>“계속 사용” → 타이머 리셋, “로그아웃” → 즉시 로그아웃</td>
</tr>
<tr>
<td>강제 만료</td>
<td>경고를 무시해도 30분 도달 시 강제 로그아웃</td>
</tr>
<tr>
<td>인증 연동</td>
<td>로그인 시 타이머 시작, 로그아웃 시 타이머 중지</td>
</tr>
</tbody>
</table>
<hr>
<h2>2. 설계: React 바깥의 순수 타이머</h2>
세션 타임아웃의 핵심 로직은 “마지막 활동 시점으로부터 N분이 지났는가”를 판단하는 것이다. 이것은 React의 렌더링 사이클과 무관한 관심사다.
<h3>왜 React 훅으로 만들지 않았는가</h3>
<pre><code class="language-typescript">// [X] Bad: 훅으로 구현하면 생기는 문제
const useSessionTimeout = () =&gt; {
 useEffect(() =&gt; {
 const timer = setTimeout(handleTimeout, 30 * 60 * 1000)
 // 이벤트 리스너 등록...
 return () =&gt; clearTimeout(timer)
 }, [])
}
</code></pre>
<ul>
<li>훅은 컴포넌트가 마운트되어 있을 때만 동작한다</li>
<li>라우트 전환 시 컴포넌트가 언마운트되면 타이머가 초기화된다</li>
<li>전역 상태(인증)와의 연동이 복잡해진다</li>
</ul>
세션 타임아웃은 앱의 전체 생명주기에 걸쳐 동작해야 하므로, React 컴포넌트 트리 바깥에 두는 것이 자연스럽다.
<h3>순수 타이머 모듈</h3>
<pre><code class="language-typescript">// src/shared/lib/session-timeout.ts

const SESSION_TIMEOUT_MS = 30 * 60 * 1000 // 30분
const WARNING_BEFORE_MS = 5 * 60 * 1000 // 만료 5분 전 경고

const ACTIVITY_EVENTS: (keyof WindowEventMap)[] = [
 &#x27;mousemove&#x27;, &#x27;keydown&#x27;, &#x27;click&#x27;, &#x27;scroll&#x27;, &#x27;touchstart&#x27;,
]

let timeoutTimerId: ReturnType&lt;typeof setTimeout&gt; | null = null
let warningTimerId: ReturnType&lt;typeof setTimeout&gt; | null = null
let isActive = false
let onWarningCallback: (() =&gt; void) | null = null
let onTimeoutCallback: (() =&gt; void) | null = null
</code></pre>
상태는 모듈 스코프 변수로 관리한다. React state도, Zustand store도 아니다. 이 타이머는 어떤 UI 프레임워크에도 의존하지 않는다.
<h3>타이머 리셋 로직</h3>
<pre><code class="language-typescript">const resetTimer = () =&gt; {
 if (!isActive) return

 clearTimers()
 warningTimerId = setTimeout(handleWarning, SESSION_TIMEOUT_MS - WARNING_BEFORE_MS)
 timeoutTimerId = setTimeout(handleTimeout, SESSION_TIMEOUT_MS)
}
</code></pre>
활동이 감지될 때마다 두 타이머를 모두 리셋한다.
<ul>
<li>경고 타이머: 25분 후 발동 (30분 - 5분)</li>
<li>만료 타이머: 30분 후 발동</li>
</ul>
<h3>공개 API</h3>
<pre><code class="language-typescript">export const sessionTimeout = {
 start() {
 if (isActive) return
 isActive = true

 for (const event of ACTIVITY_EVENTS) {
 window.addEventListener(event, resetTimer, { passive: true })
 }
 resetTimer()
 },

 stop() {
 if (!isActive) return
 isActive = false

 for (const event of ACTIVITY_EVENTS) {
 window.removeEventListener(event, resetTimer)
 }
 clearTimers()
 },

 reset() {
 resetTimer()
 },

 onWarning(callback: () =&gt; void) {
 onWarningCallback = callback
 },

 onTimeout(callback: () =&gt; void) {
 onTimeoutCallback = callback
 },
}
</code></pre>
<blockquote>
콜백 등록 패턴에 주목하자. <code>onWarning</code>과 <code>onTimeout</code>은 콜백을 받아 저장만 한다. 타이머 모듈은 &quot;만료 시 무엇을 할 것인가&quot;를 모른다. 로그아웃, 다이얼로그 표시 등은 호출하는 쪽이 결정한다.
</blockquote>
<h3><code>{ passive: true }</code>를 쓰는 이유</h3>
활동 감지 이벤트(<code>mousemove</code>, <code>scroll</code>, <code>touchstart</code>)는 초당 수십~수백 회 발생할 수 있다. <code>passive: true</code>는 브라우저에게 “이 리스너는 <code>preventDefault()</code>를 호출하지 않는다”고 알려주어, 스크롤 성능 저하를 방지한다.
<hr>
<h2>3. 인증 상태와의 연동</h2>
타이머 모듈은 순수하게 유지하되, 인증 상태 변화에 따라 시작/중지되어야 한다. 이 연동은 별도의 setup 파일에서 처리한다.
<pre><code class="language-typescript">// src/app/providers/session-timeout-setup.ts

import { useSessionStore } from &#x27;@/entities/session&#x27;
import { sessionTimeout } from &#x27;@/shared/lib/session-timeout&#x27;
import { useToastStore } from &#x27;@/shared/store/useToastStore&#x27;
</code></pre>
<h3>경고 다이얼로그</h3>
<pre><code class="language-typescript">let isWarningOpen = false

sessionTimeout.onWarning(async () =&gt; {
 if (isWarningOpen) return
 isWarningOpen = true

 const confirmed = await useToastStore.getState().showConfirm({
 title: &#x27;세션 만료 안내&#x27;,
 description: &#x27;5분간 활동이 없으면 자동으로 로그아웃됩니다.\n계속 사용하시겠습니까?&#x27;,
 variant: &#x27;warning&#x27;,
 confirmText: &#x27;계속 사용&#x27;,
 cancelText: &#x27;로그아웃&#x27;,
 })

 isWarningOpen = false

 if (confirmed) {
 sessionTimeout.reset()
 } else {
 useSessionStore.getState().logout()
 window.location.href = &#x27;/login&#x27;
 }
})
</code></pre>
<h3>강제 만료</h3>
<pre><code class="language-typescript">sessionTimeout.onTimeout(() =&gt; {
 // 경고 다이얼로그가 열려있든 아닌든 강제 로그아웃
 useToastStore.getState().hideToast()
 isWarningOpen = false
 useSessionStore.getState().logout()
 window.location.href = &#x27;/login&#x27;
})
</code></pre>
<blockquote>
경고 무시 시나리오를 처리한다. 25분에 경고 다이얼로그가 뜨고, 사용자가 아무 버튼도 누르지 않으면 30분에 <code>onTimeout</code>이 발동한다. 이때 경고 다이얼로그를 강제로 닫고(<code>hideToast</code>), <code>isWarningOpen</code>을 초기화한 뒤 로그아웃한다.
</blockquote>
<h3>Zustand 구독으로 자동 시작/중지</h3>
<pre><code class="language-typescript">useSessionStore.subscribe((state) =&gt; {
 if (state.isAuthenticated) {
 sessionTimeout.start()
 } else {
 sessionTimeout.stop()
 }
})

// 현재 인증 상태에 따라 초기화
if (useSessionStore.getState().isAuthenticated) {
 sessionTimeout.start()
}
</code></pre>
이 코드가 이 설계의 핵심이다. Zustand의 <code>subscribe</code>는 React 컴포넌트 바깥에서도 동작한다. 모듈이 import되는 시점에 구독이 설정되고, 이후 인증 상태가 바뀔 때마다 타이머가 자동으로 시작/중지된다.
<hr>
<h2>4. 타임라인으로 보는 전체 흐름</h2>
<div class="mermaid">sequenceDiagram
 participant U as 사용자
 participant S as SessionStore
 participant T as sessionTimeout
 participant D as 경고 다이얼로그

 U->>S: 로그인
 S->>T: subscribe → start()
 T->>T: 이벤트 리스너 등록 + 타이머 시작

 Note over U,T: 사용자 활동 중 → resetTimer() 반복

 Note over T: 25분 경과 (활동 없음)
 T->>D: onWarning() → showConfirm()
 D->>U: "계속 사용하시겠습니까?"

 alt 계속 사용
 U->>D: "계속 사용" 클릭
 D->>T: reset()
 Note over T: 타이머 30분 재시작
 else 로그아웃
 U->>D: "로그아웃" 클릭
 D->>S: logout()
 S->>T: subscribe → stop()
 else 무응답
 Note over T: 30분 경과
 T->>S: onTimeout() → logout()
 S->>T: subscribe → stop()
 end
</div><hr>
<h2>5. 왜 이 구조가 좋은가</h2>
<h3>관심사 분리</h3>
<table>
<thead>
<tr>
<th>모듈</th>
<th>관심사</th>
<th>아는 것</th>
<th>모르는 것</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>session-timeout.ts</code></td>
<td>타이머 + 활동 감지</td>
<td>시간, DOM 이벤트</td>
<td>인증, UI, 로그아웃</td>
</tr>
<tr>
<td><code>session-timeout-setup.ts</code></td>
<td>연동 + UI 처리</td>
<td>세션 스토어, 토스트</td>
<td>타이머 내부 구현</td>
</tr>
<tr>
<td><code>useSessionStore</code></td>
<td>인증 상태</td>
<td>토큰, 사용자 정보</td>
<td>타임아웃 존재 자체</td>
</tr>
</tbody>
</table>
타이머 모듈은 React를 모르고, 세션 스토어는 타임아웃을 모른다. 둘을 연결하는 setup 파일만이 양쪽을 알고 있다.
<h3>테스트 용이성</h3>
타이머 모듈은 DOM 이벤트와 <code>setTimeout</code>만 사용하므로, React 없이 단위 테스트가 가능하다.
<pre><code class="language-typescript">// 테스트 예시
vi.useFakeTimers()
sessionTimeout.onTimeout(mockCallback)
sessionTimeout.start()

vi.advanceTimersByTime(30 * 60 * 1000)
expect(mockCallback).toHaveBeenCalledOnce()
</code></pre>
<h3>라우트 전환에 영향받지 않음</h3>
훅 기반이었다면 페이지 전환 시 컴포넌트가 언마운트되면서 타이머가 초기화될 수 있다. 모듈 스코프에 두었기 때문에 앱이 살아있는 한 타이머도 유지된다.
<hr>
<h2>6. 정리</h2>
세션 타임아웃을 구현할 때 핵심은 “타이머 로직을 React 렌더링 사이클에서 분리하는 것”이다.
<table>
<thead>
<tr>
<th>결정</th>
<th>이유</th>
</tr>
</thead>
<tbody>
<tr>
<td>순수 모듈 (훅 아님)</td>
<td>라우트 전환에 영향받지 않고, 앱 전체 생명주기에 걸쳐 동작</td>
</tr>
<tr>
<td>콜백 패턴</td>
<td>타이머가 UI/인증을 몰라도 되므로, 관심사 분리 + 테스트 용이</td>
</tr>
<tr>
<td>Zustand subscribe</td>
<td>React 컴포넌트 바깥에서 인증 상태 변화를 감지하여 타이머 자동 연동</td>
</tr>
<tr>
<td>passive 이벤트 리스너</td>
<td>활동 감지가 스크롤 성능을 저하시키지 않도록 보장</td>
</tr>
<tr>
<td>경고 + 강제 만료 이중 처리</td>
<td>경고를 무시해도 반드시 로그아웃되는 안전장치</td>
</tr>
</tbody>
</table>
이 패턴은 세션 타임아웃뿐 아니라, 앱 전체 생명주기에 걸쳐 동작해야 하는 모든 기능(웹소켓 연결 관리, 글로벌 이벤트 버스 등)에 동일하게 적용할 수 있다. 핵심은 순수 모듈로 로직을 분리하고, 프레임워크와의 연동은 별도의 setup 파일에서 처리하는 것이다.

30분 세션 타임아웃 구현 — 순수 타이머 모듈과 Zustand 구독의 조합

<blockquote>
토큰 만료 시 사용자 경험을 끊기지 않게 유지하면서, 동시 요청까지 안전하게 처리하는 HTTP 인터셉터 설계
</blockquote>
<hr>
<h2>문제 상황</h2>
토큰 기반 인증을 사용하는 프론트엔드에서는 accessToken이 만료되면 서버가 401 Unauthorized를 반환합니다. 이때 단순히 로그인 페이지로 보내면 사용자 경험이 끊기게 됩니다.
더 복잡한 문제는, 페이지 진입 시 여러 API를 동시에 호출하는 경우입니다. 토큰이 만료된 상태라면 3~5개의 요청이 동시에 401을 받게 되고, 이를 제대로 처리하지 않으면 refresh 요청이 중복 발생하거나 세션이 꼬일 수 있습니다.
이 글에서는 HTTP 클라이언트의 인터셉터(axios, ky, openapi-fetch 등 대부분의 라이브러리가 제공)를 활용해 이 문제를 해결하는 패턴을 정리합니다.
<hr>
<h2>전체 구조 요약</h2>
처리 전략은 크게 3가지입니다.
<table>
<thead>
<tr>
<th>전략</th>
<th>설명</th>
<th>처리 위치</th>
</tr>
</thead>
<tbody>
<tr>
<td>선제적 갱신</td>
<td>만료 60초 전에 미리 refresh</td>
<td>Request 인터셉터</td>
</tr>
<tr>
<td>401 재시도</td>
<td>401 수신 시 refresh 후 원래 요청 재시도</td>
<td>Response 인터셉터</td>
</tr>
<tr>
<td>중복 방지</td>
<td>동시 401 시 refresh를 1회만 실행</td>
<td>refreshPromise 싱글턴</td>
</tr>
</tbody>
</table>
<hr>
<h2>1. 정상 흐름</h2>
토큰이 유효한 경우의 기본 흐름입니다.
<div class="mermaid">sequenceDiagram
 participant C as 컴포넌트
 participant RI as Request 인터셉터
 participant RS as Response 인터셉터
 participant SS as 세션 스토어
 participant API as API 서버

 Note over C,API: 정상 흐름
 C->>RI: API 요청
 RI->>RI: 토큰 만료 임박? → No
 RI->>RI: Authorization 헤더 세팅
 RI->>RI: request.clone() → WeakMap 저장
 RI->>API: 요청 전송
 API-->>RS: 200 OK
 RS-->>C: 정상 응답 반환
</div>여기서 주목할 점은 request.clone()입니다. HTTP Request 객체의 body는 한 번 읽으면 소비(consumed)되어 재사용이 불가능합니다. 401 발생 시 원래 요청을 재시도하려면, body가 소비되기 전에 clone을 저장해둬야 합니다.
<pre><code class="language-typescript">// Request 인터셉터: clone 저장
async function onRequest(request: Request) {
 // ... 토큰 세팅 ...

 // body가 소비되기 전에 clone 저장 (401 재시도용)
 requestClones.set(request, request.clone())
 return request
}
</code></pre>
clone 저장에 WeakMap을 사용하는 이유는, Request 객체가 GC되면 clone도 함께 정리되어 메모리 누수를 방지할 수 있기 때문입니다.
<hr>
<h2>2. 선제적 갱신 (토큰 60초 내 만료)</h2>
401이 발생하기 전에 미리 토큰을 갱신하는 전략입니다.
<div class="mermaid">sequenceDiagram
 participant C as 컴포넌트
 participant RI as Request 인터셉터
 participant RS as Response 인터셉터
 participant SS as 세션 스토어
 participant API as API 서버

 Note over C,API: 선제적 갱신 "토큰 60초 내 만료"
 C->>RI: API 요청
 RI->>RI: isTokenExpired(token, 60) → true
 RI->>API: POST /auth/refresh
 API-->>RI: 새 토큰 발급
 RI->>SS: 새 토큰 저장
 RI->>RI: 새 토큰으로 Authorization 세팅
 RI->>RI: request.clone() → WeakMap 저장
 RI->>API: 요청 전송
 API-->>RS: 200 OK
 RS-->>C: 정상 응답 반환
</div>핵심은 JWT의 <code>exp</code> 클레임을 디코딩하여, bufferSeconds만큼 앞당겨서 만료를 판단하는 것입니다.
<pre><code class="language-typescript">export function isTokenExpired(token: string, bufferSeconds = 0): boolean {
 const payload = decodeJwt(token)
 if (!payload?.exp) return true
 return Date.now() &gt;= (payload.exp - bufferSeconds) * 1000
}
</code></pre>
예를 들어 토큰의 <code>exp</code>가 10:05:00이고 bufferSeconds가 60이면:
<ul>
<li>실제 만료: 10:05:00</li>
<li>판단 기준: 10:04:00</li>
<li>→ 10:04:00 이후의 요청부터 미리 refresh</li>
</ul>
이렇게 하면 요청이 서버에 도달했을 때 토큰이 이미 만료되는 상황을 예방할 수 있습니다.
<hr>
<h2>3. 401 → refresh → 재시도</h2>
선제적 갱신을 통과했지만 그래도 401이 발생한 경우(네트워크 지연, 서버 시간 차이 등)의 처리입니다.
<div class="mermaid">sequenceDiagram
 participant C as 컴포넌트
 participant RI as Request 인터셉터
 participant RS as Response 인터셉터
 participant SS as 세션 스토어
 participant API as API 서버

 Note over C,API: 401 → refresh → 재시도
 C->>RI: API 요청
 RI->>RI: request.clone() → WeakMap 저장
 RI->>API: 요청 전송 "body 소비됨"
 API-->>RS: 401 Unauthorized
 RS->>RS: AUTH_PATHS 체크 → 일반 API
 RS->>SS: refreshToken 확인 → 있음
 RS->>API: POST /auth/refresh
 API-->>RS: 새 토큰 발급
 RS->>SS: 새 토큰 저장
 RS->>RS: WeakMap에서 clone 꺼냄
 RS->>RS: clone에 새 토큰 헤더 세팅
 RS->>API: fetch(clone) 재시도
 API-->>RS: 200 OK
 RS-->>C: 정상 응답 반환
</div><pre><code class="language-typescript">async function onResponse(request: Request, response: Response) {
 if (response.status !== 401) return response

 // 인증 API 경로는 인터셉터가 가로채지 않음
 if (AUTH_PATHS.some(path =&gt; request.url.includes(path))) return response

 const refreshToken = getStoredRefreshToken()
 if (!refreshToken) { clearSession(); return response }

 try {
 const { accessToken } = await performRefresh(refreshToken)

 // 저장해둔 clone으로 원래 요청 재시도
 const clone = requestClones.get(request)
 if (clone) {
 clone.headers.set(&#x27;Authorization&#x27;, `Bearer ${accessToken}`)
 return fetch(clone)
 }
 return response
 } catch {
 clearSession()
 return response
 }
}
</code></pre>
<h3>AUTH_PATHS를 제외하는 이유</h3>
로그인 시 비밀번호가 틀리면 서버가 401을 반환합니다. 이때 인터셉터가 이를 &quot;토큰 만료&quot;로 오인하면 refresh를 시도하게 되는데, 이는 의미가 없습니다. 인증 관련 경로의 401은 인터셉터가 가로채지 않고 호출부에 그대로 전달해서, 각 화면에서 “비밀번호가 틀렸습니다” 같은 적절한 에러 메시지를 직접 보여줄 수 있게 합니다.
<hr>
<h2>4. 동시 401 중복 방지</h2>
가장 까다로운 케이스입니다. 페이지 진입 시 TanStack Query가 여러 데이터를 동시에 fetch하는 상황에서, 토큰이 만료되면 모든 요청이 동시에 401을 받습니다.
<h3>왜 동시 401이 발생하는가?</h3>
서버는 각 요청을 별도의 스레드에서 독립적으로 처리합니다. 3개의 요청이 모두 같은 만료된 토큰을 들고 왔으니, 서버 입장에서는 세 요청 모두에 401을 반환하는 것이 당연합니다.
<div class="mermaid">sequenceDiagram
 participant C as 컴포넌트
 participant RI as Request 인터셉터
 participant RS as Response 인터셉터
 participant SS as 세션 스토어
 participant API as API 서버

 Note over C,API: 동시 401 중복 방지
 par 병렬 요청
 C->>API: GET /orders
 C->>API: GET /products
 C->>API: GET /users
 end
 API-->>RS: 401 "/orders"
 API-->>RS: 401 "/products"
 API-->>RS: 401 "/users"
 RS->>RS: refreshPromise === null
 RS->>API: POST /auth/refresh "1회만"
 Note over RS: 나머지 2건은 같은 Promise 대기
 API-->>RS: 새 토큰 발급
 RS->>SS: 새 토큰 저장
 par 병렬 재시도 "clone 사용"
 RS->>API: /orders 재시도
 RS->>API: /products 재시도
 RS->>API: /users 재시도
 end
 API-->>C: 200 OK "3건 모두"
</div><h3>refreshPromise 싱글턴 패턴</h3>
<pre><code class="language-typescript">let refreshPromise: Promise&lt;TokenPair&gt; | null = null

const performRefresh = async (
 currentRefreshToken: string,
) =&gt; {
 // 첫 번째 호출만 실제 fetch 실행
 if (!refreshPromise) {
 refreshPromise = refreshTokenRequest(
 currentRefreshToken,
 ).finally(() =&gt; {
 refreshPromise = null // 완료 후 초기화
 })
 }

 // 두 번째, 세 번째 호출은 같은 Promise를 await
 const data = await refreshPromise

 // 세션 스토어 업데이트 (Zustand, Redux 등 사용하는 상태관리에 맞게)
 saveTokens(data.accessToken, data.refreshToken)

 return data
}
</code></pre>
<h3>왜 이 패턴이 안전한가? — JavaScript 이벤트 루프와 Run-to-Completion</h3>
이 패턴이 안전한 이유는 JavaScript가 싱글 스레드이기 때문입니다. 정확히는 Run-to-Completion 보장 때문인데, 하나의 동기 코드 블록이 실행 중이면 다른 어떤 코드도 끼어들 수 없습니다.
<h4>이벤트 루프 구조</h4>
<div class="mermaid">flowchart TD
 subgraph CS["Call Stack (한 번에 하나만 실행)"]
 A["현재 실행 중인 동기 코드"]
 end
 subgraph MIC["Microtask Queue"]
 B["Promise.then / await 재개"]
 C["401-A 콜백, 401-B 콜백, ..."]
 end
 subgraph MAC["Macrotask Queue"]
 D["setTimeout, I/O 등"]
 end
 CS -- "콜 스택이 비었을 때만" --> MIC
 MIC -- "마이크로태스크가 비었을 때만" --> MAC
</div>401 응답 3개가 도착하면, 3개의 onResponse 콜백이 Microtask Queue에 적재됩니다. 하지만 콜 스택에서는 한 번에 하나의 콜백만 실행됩니다.
<h4>콜백 A/B/C가 순차적으로 실행되는 과정</h4>
<div class="mermaid">sequenceDiagram
 participant CS as Call Stack
 participant MQ as Microtask Queue

 Note over CS,MQ: 401 응답 3개 도착 → 콜백 3개 큐에 적재
 MQ->>MQ: [콜백A, 콜백B, 콜백C] 대기 중
 Note over CS: 콜백A 실행 (콜 스택 점유)
 CS->>CS: if (!refreshPromise) → true
 CS->>CS: refreshPromise = refreshTokenRequest(...)
 Note over CS: 이 두 줄 사이에 다른 코드 끼어들기 불가능
 CS->>CS: await refreshPromise → 일시 중단
 CS-->>MQ: 콜 스택 반환
 Note over CS: 콜백B 실행 (콜 스택 점유)
 CS->>CS: if (!refreshPromise) → false
 Note over CS: 콜백A가 이미 할당해둔 상태
 CS->>CS: await refreshPromise → 같은 Promise 대기
 CS-->>MQ: 콜 스택 반환
 Note over CS: 콜백C 실행 (콜 스택 점유)
 CS->>CS: if (!refreshPromise) → false
 CS->>CS: await refreshPromise → 같은 Promise 대기
 CS-->>MQ: 콜 스택 반환
</div>핵심은 콜백A의 동기 코드(<code>if</code> 체크 → <code>refreshPromise</code> 할당)가 끝나고 <code>await</code>로 콜 스택을 반환한 뒤에야 콜백B가 실행된다는 점입니다. 그래서 콜백B는 반드시 이미 할당된 <code>refreshPromise</code>를 보게 됩니다.
<h4>refresh 완료 후 3개 콜백 재개</h4>
<div class="mermaid">sequenceDiagram
 participant CS as Call Stack
 participant MQ as Microtask Queue
 participant API as API 서버

 Note over CS,API: refresh 응답 도착 → Promise resolve
 API-->>MQ: refreshPromise resolved
 Note over CS: 콜백A 재개 (await 이후)
 MQ->>CS: 콜백A 재개
 CS->>CS: data = 새 토큰 수신
 CS->>CS: 세션 스토어 업데이트
 CS->>API: clone으로 /orders 재시도
 Note over CS: 콜백B 재개 (같은 Promise 결과)
 MQ->>CS: 콜백B 재개
 CS->>CS: data = 동일한 새 토큰
 CS->>CS: 세션 스토어 업데이트
 CS->>API: clone으로 /products 재시도
 Note over CS: 콜백C 재개 (같은 Promise 결과)
 MQ->>CS: 콜백C 재개
 CS->>CS: data = 동일한 새 토큰
 CS->>CS: 세션 스토어 업데이트
 CS->>API: clone으로 /users 재시도
 Note over CS: .finally() 실행
 CS->>CS: refreshPromise = null (초기화)
</div>3개의 콜백이 모두 동일한 Promise를 <code>await</code>하고 있었으므로, resolve되면 모두 같은 새 토큰을 받아 각자의 원래 요청을 재시도합니다.
<h4>멀티스레드(Java 등)와의 비교</h4>
멀티스레드 환경에서는 동일한 코드가 Race Condition을 일으킵니다.
<div class="mermaid">sequenceDiagram
 participant TA as 스레드A
 participant TB as 스레드B
 participant RP as refreshPromise

 Note over TA,RP: 멀티스레드 (Java 등) - 두 스레드가 동시에 실행 가능
 TA->>RP: if (refreshPromise == null) → true
 TB->>RP: if (refreshPromise == null) → true
 Note over TB: 스레드A가 할당하기 전에 끼어듦!
 TA->>RP: refreshPromise = doRefresh() → refresh 1회차
 TB->>RP: refreshPromise = doRefresh() → refresh 2회차
 Note over TA,RP: refresh가 2번 실행됨 → 토큰 꼬임
 Note over TA,RP: 해결: synchronized / Lock 필요
</div><div class="mermaid">sequenceDiagram
 participant CA as 콜백A
 participant CB as 콜백B
 participant RP as refreshPromise

 Note over CA,RP: 싱글스레드 (JavaScript) - Run-to-Completion 보장
 CA->>RP: if (!refreshPromise) → true
 CA->>RP: refreshPromise = doRefresh()
 CA->>CA: await → 콜 스택 반환
 Note over CA,RP: 콜백A의 동기 코드가 끝나야 콜백B 실행
 CB->>RP: if (!refreshPromise) → false
 CB->>CB: await refreshPromise → 같은 Promise 대기
 Note over CA,RP: refresh 1회만 실행, Lock 불필요
</div>JavaScript에서는 <code>if</code> 체크와 할당 사이에 다른 코드가 끼어들 수 없으므로, 별도의 Lock 메커니즘 없이도 안전합니다.
<h3>중복 방지가 없으면?</h3>
refresh token이 일회용(rotate) 방식인 경우:
<ol>
<li>요청 A의 401 → refresh 호출 → 새 토큰 A 발급</li>
<li>요청 B의 401 → refresh 호출 → 토큰 A의 refresh token은 이미 사용됨 → 실패</li>
<li>→ logout → 사용자는 갑자기 로그인 페이지로</li>
</ol>
<hr>
<h2>핵심 설계 포인트 정리</h2>
<table>
<thead>
<tr>
<th>포인트</th>
<th>선택</th>
<th>이유</th>
</tr>
</thead>
<tbody>
<tr>
<td>clone 저장 시점</td>
<td>Request 인터셉터 (요청 전)</td>
<td>body 소비 전에 저장해야 재시도 가능</td>
</tr>
<tr>
<td>clone 저장 자료구조</td>
<td>WeakMap</td>
<td>Request 객체 GC 시 clone도 자동 정리</td>
</tr>
<tr>
<td>선제적 갱신 버퍼</td>
<td>60초</td>
<td>네트워크 지연 감안, 401 발생 자체를 최소화</td>
</tr>
<tr>
<td>중복 refresh 방지</td>
<td>Promise 싱글턴</td>
<td>JS 싱글 스레드 보장으로 안전한 동시성 제어</td>
</tr>
<tr>
<td>AUTH_PATHS 제외</td>
<td>경로 기반 필터링</td>
<td>로그인 실패 401과 토큰 만료 401을 구분</td>
</tr>
</tbody>
</table>
<hr>
<h2>결론</h2>
사용자 입장에서는 토큰 만료를 전혀 인식하지 못하고, 모든 요청이 정상적으로 처리된 것처럼 느끼게 됩니다. 이 매끄러운 UX를 위해 인터셉터 레벨에서 3가지 전략(선제적 갱신, 401 재시도, 중복 방지)이 조합되어 동작합니다.

TanStack Query Key Factory 패턴으로 FSD 프로젝트의 캐시 무효화 관리하기

복잡한 상태 흐름을 Stepper로 시각화하기

프로덕트 엔지니어로 성장하기

백오피스 필터 40개를 하나의 훅으로 — useFilter 추상화로 보일러플레이트 제거하기

30분 세션 타임아웃 구현 — 순수 타이머 모듈과 Zustand 구독의 조합

프론트엔드에서 인증 만료를 우아하게 처리하는 방법

상태관리 패턴 비교 & 횡단관심사 관리 전략

useSuspenseQuery 필터 깜빡임, startTransition으로 해결하기