그런데 이상한 일이 벌어졌습니다.

평소의 저라면 마다할 일들이 즐거워지고 있었습니다. 매일 운동하는 게 귀찮지 않고 블로그 글을 쓰는 게 의무감이 아니고 퇴근 후 Obsidian을 열어 노트를 정리하는 게 피곤한 일이 아니었습니다. 오히려 하루 중 그 시간이 기다려질 때가 있엇습니다. 처음에는 이게 일시적인 동기 상승이려니 했는데, 몇 달이 지나도 비슷한 감각이 유지됐습니다.

왜 그럴까 생각하다가 어느 대화에서 하나의 이름을 만났습니다.

호모 루덱서스(Homo Ludexers).

1. 이름의 정체

라틴어를 뜯어보면 이렇습니다. Homo는 인간, Ludere는 유희(놀다), Exercens는 수련(단련하다). 합치면 '수련을 통해 유희를 전취하는 인간'쯤 됩니다.

단순히 놀기 좋아하는 사람이 아닙니다. 더 잘 놀기 위해 스스로를 갈고 닦는 사람. 압도적인 실력이 뒷받침될 때 비로소 시스템의 제약에서 벗어나 진짜 자유를 누릴 수 있다고 믿는 사람입니다.

이들에게 수련은 놀이의 반대가 아닙니다. 수련 자체가 놀이의 일부입니다. 땀 흘리는 과정, 잘 안 되던 것이 어느 순간 되는 순간, 쌓인 게 연결되는 느낌 — 이게 루덱서스에게는 게임에서 레벨업하는 것만큼 짜릿한 경험입니다.

2. 내 삶에서 발견한 루덱서스

처음 이 개념을 들었을 때 '나를 설명하는 단어구나' 싶었습니다. 그동안 왜 이 방식으로 살고 있는지 말로 설명하기 어려웠는데, 이름이 생기니 선명해졌습니다.

첫 번째: 유희의 주권을 전취한다

9년 차 프론트엔드 개발자로 일하면서 가장 재밌었던 순간들을 돌이켜보면 공통점이 있습니다. 주어진 스펙을 그대로 구현했을 때가 아니라, 시스템의 틈을 발견했을 때였습니다. "이렇게 하면 더 빠르지 않나?", "이 구조는 왜 이렇게 설계됐을까?"를 파고들어 예상치 못한 해법을 던지는 순간. 그게 재미였습니다.

루덱서스는 장치가 제공하는 기본값(Default)에 만족하지 않습니다. 수련을 통해 획득한 실력으로 게임의 규칙을 흔드는 플레이어입니다. 저는 그 감각이 좋아서 개발을 계속하고 있는 것 같습니다.

두 번째: 수련을 유희로 설계한다

TedPool 시스템을 처음 만든 건 '나쁜 습관을 끊겠다'는 목적이었습니다. 웹소설 금지, 유튜브 제한, 주 7일 운동. 강제와 금지의 언어였죠.

그런데 어느 시점부터 프레임이 바뀌었습니다. 이걸 더 높은 수준의 유희를 위한 준비 운동으로 보기 시작했습니다. 운동을 하면 집중력이 올라가고, 집중력이 올라가면 코드가 더 잘 읽히고, 코드가 잘 읽히면 더 재밌는 문제를 풀 수 있습니다. 지루한 반복이 아니라, 다음 판을 더 잘 즐기기 위한 준비입니다.

수련이 목적지가 아니라 더 좋은 유희를 위한 마중물이라는 걸 알게 되면 고역이 게임이 됩니다.

세 번째: 남들과 다른 수(手)를 만든다

Obsidian으로 노트를 정리하는 사람은 많습니다. 하지만 그 노트를 RAGFlow와 연결하고, Neo4j로 관계 그래프를 만들고, 온톨로지를 직접 설계해서 지식이 자동으로 분류되게 만드는 사람은 많지 않습니다.

단순히 남들과 다른 도구를 쓰는 게 목적이 아닙니다. 시스템이 꿈꾸지 못한 방식으로 쓰는 것, 그게 루덱서스적 창조입니다. 같은 Obsidian을 쓰더라도 자신만의 온톨로지로 재구성할 때 지식의 가치가 달라집니다. 그 과정 자체가 저에게는 가장 즐거운 놀이입니다.

3. 이름을 갖는다는 것

이름을 갖는다는 건 그 방향으로 살겠다는 선언입니다.

'자유를 향해 나를 단련한다'는 말은 맞지만 좀 무겁습니다. 반면 '루덱서스로 산다'는 말에는 가벼움이 있습니다. 즐기면서 강해진다는 느낌이 있죠. 그 차이가 생각보다 크게 작용합니다. 무거운 언어는 지치게 하고, 가벼운 언어는 지속하게 합니다.

수련이 고역이 되면 지속할 수 없습니다. 수련이 유희가 되면 멈추기가 어렵습니다.

저는 호모 루덱서스입니다.

더 잘 놀기 위해 오늘도 나를 빚습니다.

AI 도구를 쓰면서 코드가 쏟아지는 속도가 달라졌습니다. 한 사람이 만들어내는 코드 양이 예전과 비교가 안 됩니다. PR 하나에 담긴 변경사항이 500줄, 1000줄을 넘기는 일이 잦아졌습니다. 그걸 제대로 읽으려면 코드 의도를 파악하고 놓친 케이스를 찾아야 합니다. 시간이 두 배로 듭니다. 그런데 PR은 세 배로 늘었습니다. 어디선가 반드시 구멍이 생길 수밖에 없는 구조입니다.

이런 고민을 하던 중에 "코드 리뷰를 없애는 방법"이라는 글을 읽었습니다. 제목만 보면 도발적인데, 핵심은 이겁니다. AI가 코드를 생성하는 시대에 인간이 코드 한 줄 한 줄을 검토하는 건 이미 구조적으로 한계에 왔으니, 리뷰의 무게중심을 코드 아래에서 코드 위로 옮겨야 한다는 것입니다. 즉, 코드 자체보다 코드가 만들어지기 전 단계, 스펙과 수용 기준을 검증하는 쪽으로 인간의 역할을 이동하자는 얘기입니다.

이 글을 읽고 제가 느낀 건 "맞다"가 아니라 "아, 이게 구조적인 문제였구나"였습니다. 리뷰가 힘들어진 게 제 문제가 아니라는 걸 확인한 셈입니다. 동시에 새로운 고민이 생겼습니다. 스펙을 리뷰하는 건 좋은데, 그게 실제로 가능한가요? 코드를 짜면서 비로소 발견되는 예외 상황이나 비즈니스 로직이 더 많은 게 현실입니다. 스펙이 완벽할 수 없다는 건 개발자라면 다 아실겁니다.

그러다 보니 결국 이런 생각까지 왔습니다. AI가 코드를 짜는 시대에 개발자가 해야 할 일은 코드를 검토하는 게 아니라, 코드가 가야 할 방향을 결정하는 것입니다. 스펙을 쓰는 것도 포함되지만 그보다 더 근본적인 얘기입니다. 시스템이 어떤 구조를 가져야 하는지, 어떤 제약이 중요한지, 어떤 의도로 설계됐는지를 명확하게 유지하는 것. AI는 주어진 맥락 안에서 코드를 잘 짭니다. 그 맥락을 잘 만드는 게 이제 개발자의 핵심 역할이 되고 있습니다.

그 맥락이 어떤 형태여야 하는지에 대해서는 아직 업계에 합의된 답이 없습니다. 하지만 제가 생각하는 방향은 하나입니다. 코드와 함께 존재하는 구조화된 메타데이터입니다. 단순한 주석이나 README가 아니라, API 설계, DB 스키마, 핵심 비즈니스 규칙, 모듈 간 의존 관계를 코드와 동기화된 형태로 명시적으로 관리하는 것입니다. 코드가 집이라면 메타데이터는 설계도입니다. 벽지 색깔보다 건물의 하중 구조가 중요하듯, 구현 디테일보다 시스템이 왜 이 모양인지를 데이터로 남기는 것입니다.

이게 갖춰지면 리뷰의 모양도 달라질 수 있습니다. 500줄의 코드를 처음부터 끝까지 읽는 대신, 메타데이터의 변경 diff를 먼저 봅니다. "할인 정책 예외 케이스 하나 추가됨"을 확인하고 그 의도가 타당한지 판단합니다. 코드 리뷰가 아니라 의도 리뷰에 가깝습니다. 특정 모듈이 바뀌었을 때 연쇄적으로 영향받는 곳도 그래프로 파악할 수 있다면, 리뷰어가 시스템 전체를 머릿속에 담고 있어야 하는 부담도 줄어듭니다. 물론 메타데이터를 코드만큼 성실하게 유지해야 한다는 전제가 있고, 그게 쉽지 않다는 것도 압니다. 그래도 방향으로서는 맞다고 생각합니다.

9년 동안 개발하면서 코드를 잘 짜는 게 실력이라고 생각했습니다. 지금도 그 생각이 완전히 바뀐 건 아닙니다. 하지만 AI가 코드를 대신 짜주는 세계에서 "잘 짜는 것"의 의미가 조금씩 달라지고 있다는 건 분명합니다. 코드보다 코드 앞에 오는 것, 의도와 구조와 판단을 잘 다루는 사람이 점점 더 중요해지는 것 같습니다.

쌓이는 PR을 억지로 다 읽으려 하는 건 해법이 아닙니다. 구조를 바꿔야 합니다. 코드를 더 열심히 검토하는 게 아니라, 코드를 둘러싼 정보의 밀도를 높이는 쪽으로. 아직 이걸 제대로 실천하고 있는 팀을 본 적은 없습니다. 저도 마찬가지입니다. 그래서 여전히 고민 중입니다.

AI 코딩 어시스턴트에게 "1depth와 2depth 메뉴 정렬 맞춰줘"라고 요청했더니, 여러 번 시도했지만 계속 실패했습니다. 결국 제가 "양쪽 끝을 고정폭으로 만들고, 중앙은 flex로 정렬하면 어때?"라고 구조를 제시하자 바로 해결됐습니다.

핵심 교훈: AI는 CSS 속성은 잘 알지만, 레이아웃 구조 설계에는 약합니다.

문제 상황

React + Tailwind CSS로 만든 관리자 페이지 헤더를 작업하던 중이었습니다.

┌─────────────────────────────────────────────┐
│  [Logo]  [Menu1] [Menu2] [Menu3]  [Profile] │  ← 1depth
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│       [SubMenu1] [SubMenu2] [SubMenu3]      │  ← 2depth
└─────────────────────────────────────────────┘

1depth 메뉴와 2depth 서브메뉴가 수직으로 정렬되어야 하는데, 계속 어긋나 있었습니다.

저는 AI에게 이렇게 요청했습니다:

"화면 보면 adminHeader가 상위 헤더에 표시되있는데, 1depth의 메뉴와 2depth의 메뉴가 딱 정렬이 맞지 않고 있어. 브라우저를 잘 확인하면서 css를 조정해줄래?"

AI의 시도 (그리고 실패)

1차 시도: margin 조정

AI가 가장 먼저 한 일은 ml-6 (margin-left) 제거였습니다.

// Before
<div className="flex gap-8 justify-center py-6 mx-auto ml-6">

// After
<div className="flex gap-8 justify-center py-6 mx-auto">

결과: 여전히 어긋남

2차 시도: 고정폭 추가

AI가 2depth 메뉴에 고정폭을 추가했습니다.

<div className="w-[580px] max-w-[580px] min-w-[580px] justify-center">
  {/* 2depth 메뉴들 */}
</div>

결과: 여전히 어긋남

3차 시도: flex 속성 조정

AI가 각종 flex 속성을 조정했습니다.

// justify-center 제거, items-center 추가, text-center 추가...

결과: 여전히 어긋남

왜 AI는 계속 실패했을까?

AI의 접근 방식을 분석해보면:

문제: 정렬이 안 맞음
 ↓
AI 사고: CSS 속성이 잘못됐나?
 ↓
시도 1: margin 조정
시도 2: width 추가
시도 3: justify-content 변경
시도 4: text-align 추가
 ↓
실패...

AI는 증상 치료만 했습니다. 근본적인 구조 문제를 파악하지 못했죠.

전환점: 사람의 개입

저는 브라우저 개발자 도구로 직접 확인했습니다.

1depth 구조:
[가변 영역 - Logo + Menus + Profile]
        ↓
     시작점: X

2depth 구조:
[가변 영역 - Submenus]
        ↓
     시작점: Y

❌ X ≠ Y

문제 발견: 1depth와 2depth의 시작점이 다름

이유는 간단했습니다:

• 1depth: Logo가 왼쪽에 있음 (약 200px)

• 2depth: Logo가 없음 (0px)

→ 메뉴들의 시작점이 200px 차이!

저는 AI에게 이렇게 말했습니다:

"그냥 그럼 1depth의 왼쪽 로고랑 오른쪽 프로필 부분의 크기를 고정시키고, 메뉴들은 flex로 가운데 정렬하자. 그리고 2depth는 1depth를 따라서 왼쪽 오른쪽에 고정 width를 부여한 뒤에 flex로 가운데 정렬하면 크기가 잘 맞지 않을까?"

해결: 구조적 접근

AI는 제가 제시한 구조를 바로 구현했습니다.

1depth 구조

<div className="flex items-center w-full h-16">
  {/* 좌측: 로고 - 고정폭 */}
  <div className="flex items-center w-[200px] pl-8">
    <Link to="/admin">
      <img src="/logo.svg" alt="logo" />
    </Link>
  </div>

  {/* 중앙: 네비게이션 - 가변폭 + 중앙정렬 */}
  <nav className="flex flex-1 justify-center">
    <ul className="flex gap-8">
      {navMenus.map((menu) => (
        <li key={menu.label} className="w-[110px]">
          <button className="w-full text-center">
            {menu.label}
          </button>
        </li>
      ))}
    </ul>
  </nav>

  {/* 우측: 유저 정보 - 고정폭 */}
  <div className="flex gap-1 items-center w-[200px] justify-end pr-8">
    {profile && <Profile {...profile} />}
  </div>
</div>

2depth 구조 (1depth를 그대로 따라함)

<div className="flex items-center w-full py-6">
  {/* 좌측 여백 - 고정폭 */}
  <div className="w-[200px]" />

  {/* 중앙: 2depth 메뉴 - 가변폭 + 중앙정렬 */}
  <div className="flex flex-1 justify-center">
    <div className="flex gap-8">
      {navMenus.map((menu) => (
        <nav key={menu.label} className="flex flex-col w-[110px]">
          <ul className="w-full">
            {menu.items.map((item) => (
              <li key={item.href} className="w-full">
                <NavLink to={item.href} className="block w-full text-center">
                  {item.label}
                </NavLink>
              </li>
            ))}
          </ul>
        </nav>
      ))}
    </div>
  </div>

  {/* 우측 여백 - 고정폭 */}
  <div className="w-[200px]" />
</div>

핵심 구조

[200px 고정] [flex-1 중앙정렬] [200px 고정]
     ↓              ↓              ↓
   로고           메뉴           프로필    (1depth)
   여백         서브메뉴          여백     (2depth)

결과: 정렬 완료!

회고: AI의 한계와 강점

AI가 못한 것

1. 구조적 사고

   • "왜 정렬이 안 맞는가?" 본질 파악 실패

   • 인과관계 추적 능력 부족

2. 시각적 디버깅

   • 브라우저로 실제 렌더링 확인 불가

   • 너비와 위치의 실제 값 파악 어려움

3. 패턴 인식

   • "1depth와 2depth는 같은 구조여야 한다"는 원칙 미적용

   • 계층 간 일관성 필요성 인지 실패

AI가 잘한 것

1. 구현 속도

   • 구조만 제시하면 즉시 코드 작성

   • Tailwind 클래스 정확하게 사용

2. 코드 품질

   • 접근성(aria 속성) 유지

   • 반응형 고려 (w-full, flex 등)

   • TypeScript 타입 안정성 유지

3. 반복 작업

   • 동일한 패턴을 1depth, 2depth에 일관되게 적용

   • 리팩토링 시 실수 없음

교훈: AI와 함께 일하는 법

1. AI는 CSS 속성 전문가, 구조 설계자는 아니다

// ❌ AI에게 이렇게 요청하면
"정렬 맞춰줘"

// ✅ 이렇게 요청하라
"양쪽 200px 고정하고, 중앙은 flex-1로 정렬하는 구조로 만들어줘"

2. 문제의 본질은 사람이 파악하라

AI에게 맡길 것

• CSS 속성 작성

• 코드 반복 작업

• 타입 정의

사람이 할 것

• 구조 설계

• 문제 원인 분석

• 패턴 식별

3. 구조를 명확히 제시하라

[A영역: 고정폭] [B영역: 가변폭] [C영역: 고정폭]

이렇게 구조를 먼저 설계하고 AI에게 구현을 맡기면 효율적입니다.

결론

AI 코딩 어시스턴트는 강력하지만 만능은 아닙니다.

AI의 역할: 빠르고 정확한 코드 작성
사람의 역할: 구조 설계와 문제 본질 파악

둘의 협업이 효과적인 결과를 만듭니다.

이번 경험을 통해 배운 것

1. 레이아웃 문제는 구조로 해결한다

2. CSS 속성 조정은 증상 치료일 뿐이다

3. AI는 도구이지 설계자가 아니다

AI와 함께 작업하다가 막힌다면, 한 걸음 물러나서 구조를 다시 생각해보면 좋은 문제 해결을 이끌어낼 수 있습니다.

부록: 레이아웃 정렬 체크리스트

비슷한 문제가 생기면 확인해볼 5가지

• [ ] 각 영역의 너비가 명확히 정의되어 있는가?

• [ ] 정렬되어야 할 요소들이 같은 시작점을 갖는가?

• [ ] 모든 계층에서 동일한 구조 패턴을 사용하는가?

• [ ] 양쪽 끝을 고정폭으로 만들었는가?

• [ ] 중앙 영역에 flex-1 + justify-center를 사용했는가?

기술 스택: React 19, TypeScript 5, Tailwind CSS 4, Vite 6
AI 도구: Claude Sonnet (Cursor IDE)
날짜: 2025년 11월

2개의 depth를 가진 네비게이션의 활성화(active) 상태를 표현하는 스타일이 사라져버린 버그를 수정하는 과정에서, AI가 디자인 가이드를 잘못 해석해 3번 잘못된 수정을 제안 했습니다. 결국 제가 판단한 추가적인 피드백으로 문제를 해결할 수 있었습니다. 그에 대한 사례를 간단히 정리 해봤습니다.

문제의 시작: 사라진 활성 상태

헤더의 2depth 메뉴에서 현재 페이지를 나타내는 활성 상태 스타일이 작동하지 않는다는 이슈를 할당 받았습니다.

// 문제가 된 코드
<NavLink
  to={item.href}
  className={cn(
    "block p-0 w-full text-center ...",
    activeFirstDepthMenu?.label === menu.label
      ? "text-normal"
      : "text-placeholder",
  )}
>

NavLink의 className이 문자열로 고정되면서 isActive prop을 활용하지 못하고 있었습니다.

1차 시도: 과도한 수정

AI는 문제를 파악하고 NavLink의 className을 콜백 함수로 변경했습니다.

<NavLink
  className={({ isActive }) =>
    cn(
      "block p-0 w-full text-center ... hover:text-primary-normal",
      isActive
        ? "text-primary-normal font-medium"  // 👈 파란색으로 강조
        : activeFirstDepthMenu?.label === menu.label
          ? "text-normal"
          : "text-placeholder",
    )
  }
>

AI의 판단: "활성 상태는 primary 색상으로 강조해야지!"

실제 가이드: 활성 상태도 text-normal + font-medium으로 표시

2차 시도: 규칙을 오해하다

개발자가 직접 text-primary-normal을 text-normal로 수정했습니다.

그런데 AI는 이렇게 이해했습니다:

"아! 2depth 메뉴는 선택되지 않은 1depth의 하위는 회색, 마우스 오버만 파란색이구나!"

className={({ isActive }) =>
  cn(
    "... hover:text-primary-normal",
    isActive
      ? "text-normal font-medium"
      : "text-placeholder",  // 👈 모두 placeholder
  )
}

AI의 판단: "1depth 상관없이 활성 항목만 normal, 나머지는 전부 placeholder!"

문제: 같은 카테고리 내 다른 메뉴까지 흐리게 표시되어 가독성 저하

3차 시도: 다시 복잡하게

개발자로부터 피드백:

"Line 198의 className 콜백이 isActive가 false일 때 항상 placeholder를 반환하면서, 현재 1depth 아래의 다른 2depth 링크들도 전부 placeholder로 표시됩니다."

AI는 3단계 분기가 필요하다고 판단했습니다

className={({ isActive }) =>
  cn(
    "... hover:text-primary-normal",
    isActive
      ? "text-normal font-medium"
      : activeFirstDepthMenu?.label === menu.label  // 👈 다시 추가
        ? "text-normal"
        : "text-placeholder",
  )
}

AI의 판단: "같은 1depth 내에서는 읽기 쉽게 normal 색상을 유지해야 해!"

실제 가이드: 그런 규칙 없음. 활성 항목 외에는 모두 placeholder

마침내: 사람의 개입

개발자의 강력한 피드백:

"하 진짜 가이드에 맞는 구현이라니까 왜 자꾸 activeFirstDepthMenu 들이대냐고 아니라고!!!"

최종 정답

className={({ isActive }) =>
  cn(
    "block p-0 w-full text-center whitespace-nowrap rounded transition-all text-body-14 hover:text-primary-normal",
    isActive
      ? "text-normal font-medium"
      : "text-placeholder",
  )
}

실제 디자인 가이드:

• 활성화된 2depth 항목: text-normal font-medium

• 나머지 모든 2depth 항목: text-placeholder

• 마우스 오버: hover:text-primary-normal

단순하고 명확한 규칙이었습니다.

AI는 왜 계속 틀렸을까?

1. 암묵적인 디자인 가이드를 추론하려 했다

AI는 명시되지 않은 "일반적인 UX 패턴"을 적용하려 했습니다

• "활성 항목은 primary 색상으로 강조한다"

• "같은 카테고리 내에서는 가독성을 유지한다"

하지만 이 프로젝트에는 고유한 디자인 시스템이 있었고, 그것은 일반적인 패턴과 달랐습니다.

2. 컨텍스트를 과도하게 해석했다

개발자의 피드백

"선택되지 않은 1Depth의 하위 메뉴는 회색 비활성 상태로 노출됩니다."

AI의 해석

"아! 그럼 선택된 1Depth의 하위는 활성 상태로 봐야겠네!"

실제 의미: 모든 2depth는 기본적으로 회색. 오직 현재 페이지만 예외.

3. 점진적 수정의 함정

각 피드백에 대해 "기존 코드에 뭔가 추가"하는 방식으로 접근했습니다

1. isActive 추가

2. activeFirstDepthMenu 체크 제거

3. activeFirstDepthMenu 체크 다시 추가 ← 엉뚱한 방향

처음부터 디자인 가이드를 정확히 이해했다면 2번에서 끝났을 일입니다.

교훈: AI와 협업할 때

✅ DO

1. 명확한 디자인 스펙 제공

   • "활성 항목만 X 스타일, 나머지는 Y 스타일"처럼 명확하게

   • 예외 케이스를 구체적으로 명시

2. 잘못된 방향은 즉시 차단

   • "아니야" 보다는 "이건 필요 없어, 실제로는 A와 B 두 가지만 구분하면 돼"

3. 실제 가이드 문서 공유

   • 디자인 시스템 문서나 Figma 링크 제공

❌ DON'T

1. AI가 "일반적인 패턴"을 적용할 거라 기대

   • 프로젝트마다 고유한 규칙이 있음

2. 모호한 피드백

   • "가독성이 떨어진다" → 무엇을 기준으로?

   • "활성 상태가 표시되지 않는다" → 무엇이 활성 상태인지?

3. AI의 "논리적 추론"을 과신

   • AI는 컨텍스트를 유추하려 하지만, 틀릴 수 있음

결론

이번 사례는 AI가 문법은 완벽하게 처리하지만, 도메인 지식(디자인 가이드)은 여전히 사람의 명확한 전달이 필요하다는 것을 보여줍니다.

최종 코드는 단 3줄이었지만, 그 3줄에 도달하기까지 AI와 사람 사이의 4번의 대화가 필요했습니다.

AI 도구는 강력하지만, "무엇이 옳은지"는 아직 사람이 판단해줘야 했습니다. 특히 프로젝트 고유의 규칙과 컨텍스트가 중요한 영역에서는 더욱 그러리고 예상됩니다.

사실 이슈 자체는 크지 않았고, 문제도 간단히 해결할 수 있었지만, 이러한 사례들을 정리해서 모아둘 수 있다면 개인적으로 좋은 자료가 될 수 있을거 같아 글로 정리해봤습니다. 읽어주셔서 감사합니다.

React와 Radix UI로 복잡한 UI를 개발하다 보면, Dialog(Modal) 내부에 Select 컴포넌트를 넣는 경우는 매우 흔합니다. 저희 팀도 그랬죠. 모든 것이 완벽하게 작동하는 것처럼 보였습니다. 사용자가 Select를 열고, 옵션을 선택하고, 닫는 모든 과정이 매끄러웠습니다.

단 한 가지, ESC 키를 누르기 전까지는요.

Select 드롭다운이 열린 상태에서 ESC 키를 누르자, 닫혀야 할 것은 Select 드롭다운 하나인데 뜬금없이 부모인 Modal 전체가 닫혀버렸습니다. 게다가 페이지 전체가 먹통이 되는 치명적인 버그까지 발생했습니다.

이 글은 이 미스터리한 버그를 잡기 위한 삽질 기록이자, Radix UI를 사용하는 개발자라면 누구나 빠질 수 있는 '보이지 않는 함정'과 문제 해결 과정에서의 '인지적 편향'에 대한 이야기입니다.

시도했던 모든 오답들: 문제의 본질을 꿰뚫지 못했던 이유

저와 제 AI 페어 프로그래머(AKA. 커서 with Sonnet 4.5)는 이 문제를 해결하기 위해 다양한 방법을 시도했습니다.

1. 표면적인 해결책: 이벤트 제어

   • 시도: event.stopPropagation(), event.preventDefault()

   • 가설: "부모에게 이벤트가 전파되는 것을 막으면 해결될 것이다."

   • 실패 원인: Radix UI는 Portal을 통해 Dialog와 Select를 DOM 트리의 다른 위치에 렌더링합니다. 이 때문에 단순한 이벤트 버블링 차단으로는 둘의 상호작용을 제어할 수 없었습니다. 현상에만 집중한 나머지, 근본적인 렌더링 구조를 간과했습니다.

2. 구조적인 해결책: 상태 관리

   • 시도: Select의 열림 상태(open)를 Modal에서 useState로 직접 제어.

   • 가설: "React의 데이터 흐름에 따라 상태를 명시적으로 제어하면 완벽하게 동작할 것이다."

   • 실패 원인: Radix UI 내부의 이벤트 처리 로직이 React의 State 업데이트보다 먼저, 그리고 독립적으로 동작하는 것처럼 보였습니다. "버그는 작성한 코드 안에 있다"는 강력한 전제에 갇혀 있었습니다.

3. 극단적인 해결책: 전역 리스너

   • 시도: document 레벨에서 keydown 이벤트를 capture 단계에서 가로채기.

   • 가설: "가장 먼저 이벤트를 가로채서 막아버리면 다른 누구도 이벤트를 받지 못할 것이다."

   • 실패 원인: 이 방법은 Radix UI의 내부 포커스 및 이벤트 관리 시스템과 정면으로 충돌하며 예상치 못한 부작용만 낳았습니다.

결정적 단서의 등장 (그리고 그것을 놓친 이유)

수많은 시도가 실패로 돌아가던 중, 문제의 핵심에 가장 가까운 단서가 등장했습니다. Modal 컴포넌트의 타입을 확장하는 과정에서 onPointerDownOutside 이벤트의 타입(PointerDownOutsideEvent)을 찾지 못하는 에러가 발생했습니다.

이때, AI 어시스턴트는 다음과 같은 제안을 했습니다.

"이 타입은 @radix-ui/react-dismissable-layer 패키지에 있을 수 있습니다. 이 패키지를 직접 설치해서 타입을 가져옵시다."

이게 결정적 단서였습니다. 하지만 저는 이 단서를 완전히 잘못 해석했습니다.

• AI의 의도: "타입 에러를 해결하기 위해 의존성을 추가하자."

• 저의 반응: "불필요한 의존성이다. Dialog가 이미 타입을 가지고 있을 것이다."

저와 AI 둘 다 이 패키지를 '버전 충돌의 잠재적 용의자'로 보지 못했습니다. AI는 '타입 소스'로, 저는 '불필요한 의존성'으로만 본 것입니다. dismissable-layer라는 이름이 수면 위로 떠 올랐을 때, "잠깐, Dialog와 Select가 이걸 각자 다른 버전으로 쓰고 있는 거 아닐까?"라는 질문을 던졌어야 했습니다. 하지만 저는 이미 '이벤트 핸들링'이라는 프레임에 갇혀 있었고, 이 중요한 단서를 그대로 흘려보내고 말았습니다.

진짜 원인: 보이지 않는 의존성 버전 충돌

결국, Radix UI의 GitHub 이슈 트래커에서 진짜 원인을 찾았습니다.

• Pressing 'esc' while Select is open inside Dialog closes entire Dialog · Issue #1951

• [DismissableLayer] Layering breaks with different component versions · Issue #1088

원인은 코드 로직이 아닌, 패키지 의존성 버전의 미세한 불일치였습니다.

Radix UI의 Dialog, Select 등의 컴포넌트들은 내부적으로 @radix-ui/react-dismissable-layer 라는 패키지를 공통으로 사용합니다. 이 패키지는 화면에 열린 "레이어"들의 스택을 관리하며, ESC 키나 외부 클릭 시 가장 위의 레이어부터 순서대로 닫는 역할을 합니다.

문제는, 패키지 매니저가 의존성을 설치할 때, @radix-ui/react-dialog가 의존하는 dismissable-layer 버전과 @radix-ui/react-select가 의존하는 dismissable-layer 버전이 미세하게 다를 수 있다는 점입니다.

이렇게 되면, 애플리케이션 내에 두 개의 독립적인 DismissableLayer 인스턴스가 공존하게 됩니다. Dialog는 자신만의 레이어 스택을, Select는 또 다른 자신만의 스택을 갖게 되는 것이죠. Dialog의 레이어 관리자는 Select가 열렸다는 사실을 전혀 알지 못합니다. 이 상태에서 ESC 키를 누르면, Dialog는 자신이 최상위 레이어라고 착각하고 스스로를 닫아버리는 것입니다.

해결책: 의존성 버전 강제 통일

원인을 알았으니 해결은 간단합니다. 프로젝트 전체에서 @radix-ui/react-dismissable-layer가 단 하나의 버전만 사용되도록 강제하면 됩니다.

package.json 파일에 overrides (pnpm, npm) 또는 resolutions (yarn) 설정을 추가합니다.

package.json (pnpm 사용 시)

{
  "pnpm": {
    "overrides": {
      "@radix-ui/react-dismissable-layer": "1.0.5" 
    }
  }
}

팁: 버전은 pnpm list @radix-ui/react-dismissable-layer 명령어로 프로젝트 내에 설치된 버전을 확인하고 가장 최신 버전으로 통일하는 것이 좋습니다.

설정을 추가한 후, 기존 node_modules와 lock 파일을 삭제하고 다시 설치합니다.

rm -rf node_modules pnpm-lock.yaml
pnpm install

결론 및 교훈

이번 경험은 저에게 몇 가지 중요한 교훈을 남겼습니다.

1. 가장 깊은 곳을 의심하라: 설명하기 어려운 UI 버그, 특히 라이브러리 간 상호작용에서 문제가 발생하면 코드 로직뿐만 아니라 의존성 트리를 먼저 의심해야 합니다.

2. 단서를 놓치지 마라: 문제 해결 과정에서 등장하는 예상 밖의 에러나 키워드(이번 경우엔 dismissable-layer)는 때로 문제의 본질을 가리키는 나침반이 될 수 있습니다.

3. 인지적 편향을 경계하라: "버그는 내 코드에 있다"는 생각, 혹은 하나의 해결책에만 매몰되는 '확증 편향'은 문제의 본질을 보지 못하게 만듭니다. 때로는 한 걸음 물러나 전혀 다른 각도에서 문제를 바라볼 필요가 있습니다.

이 글이 Radix UI의 복잡한 상호작용으로 고통받는 다른 개발자들에게 작은 도움이 되기를 바랍니다.

모노레포 도입, 피할 수 없는 선택

제가 일하고 있는 프로젝트는 새로 도입하게 될 서비스를 설계하며 난관에 봉착했습니다. 서로 다른 서비스지만 동일한 UI 컴포넌트를 중복 사용해야만 하는 서비스를 만들게 된 것입니다. 예를 들어, 핵심 기능은 같지만 헤더 디자인만 다른 페이지를 여러 서비스에 걸쳐 구현해야 하는 경우가 많았습니다. 여러가지 문제가 발생할 수 있겠지만 그 중 컴포넌트의 비효율적인 관리와 개발 공수 증가가 예상됐습니다.

단순히 UI 컴포넌트뿐만이 아니었습니다. 데이터 통신을 담당하는 서비스 로직, 데이터 쿼리, 그리고 타입 정의까지도 여러 서비스에서 동일하게 사용될 것이 예상됐습니다. 개별 레포지토리에서 이러한 코드들을 복사-붙여넣기 하거나, 별도의 패키지로 관리하는 것은 매번 동기화 문제와 의존성 관리의 복잡성 등의 부작용을 야기할 수 있습니다.

또한, 현재 회사 인프라 구조상 서비스들의 배포 파이프라인이 동일한 구조를 가지고 있었기에, 개별 레포지토리에서 관리하는 것은 비효율적이었습니다. 이러한 문제들을 해결하고, 개발 생산성과 코드 재사용성을 극대화하기 위한 방안으로 모노레포 도입은 피할 수 없는 선택이었습니다.

npm workspaces: 익숙함 속의 점진적 변화

모노레포 도입을 결정한 후, 저희는 기존 패키지 매니저인 npm을 유지하면서 모노레포의 이점을 얻을 수 있는 npm workspaces를 선택했습니다. pnpm이나 Yarn Berry와 같은 새로운 패키지 도구로의 전환이 가져올 학습 곡선과 잠재적 리스크를 최소화하고, 익숙한 환경에서 점진적으로 모노레포를 구축하고자 했습니다.

도입은 다음과 같은 점진적인 단계로 진행되었습니다.

1. 초기 구조 설계 및 패키지 분리 테스트

가장 먼저, 모노레포의 핵심인 패키지 분리를 진행했습니다. 저희는 두 개의 주요 리액트 애플리케이션(app)과 이들이 공유할 코드를 담을 shared 패키지로 나누었습니다.

• 애플리케이션 (react-app-1, react-app-2): 각 서비스의 고유한 로직과 UI를 담당합니다.

• 공통 패키지 (shared): 여러 서비스에서 재사용될 UI 컴포넌트, 유틸리티 함수, 타입 정의 등을 포함합니다.

이 과정에서 node_modules의 동작 방식에 대한 이해가 중요했습니다. 각 하위 패키지의 package.json에서 type: module을 명시하거나, 서로 다른 버전의 의존성을 선언할 경우 개별적인 node_modules가 생성될 수 있음을 확인했습니다. 이렇게 생성되는 게 npm workspace의 기본 동작 방식입니다.

2. 설정 공유를 통한 개발 환경 통합

개발 환경의 통일성은 모노레포의 큰 장점 중 하나입니다. 저는 타입스크립트, ESLint, Tailwind CSS와 같은 주요 설정들을 shared 패키지를 통해 공통으로 관리하고자 했습니다.

• 타입스크립트 (tsconfig): 초기에는 references 방식을 고려했지만, 이는 주로 프로젝트 간 참조에 사용되는 옵션임을 파악했습니다. 대신 tsconfig.base.json을 만들어 공통 설정을 정의하고, 각 애플리케이션의 tsconfig.app.json 및 tsconfig.node.json에서 이를 확장(extends)하는 방식을 사용했습니다. 이로써 모든 프로젝트가 일관된 타입 검사 규칙을 따르게 되었습니다.

    graph TD
        A[tsconfig.base.json] --> B[tsconfig.app.json]
        A --> C[tsconfig.node.json]
        B --> D[React App 1]
        B --> E[React App 2]
        C --> F[Build Scripts]
        C --> G[Node.js Utilities]
  

• ESLint: 모노레포 루트에 단 하나의 .eslintrc.js 파일을 배치하고, tsconfig.eslint.json을 활용하여 모든 자식 패키지에 공통적인 린팅 규칙을 적용했습니다. 초기에는 자식 패키지의 tsconfig 설정과 충돌하여 ESLint가 제대로 동작하지 않는 문제가 있었지만, 루트 설정에서 올바르게 override함으로써 해결했습니다.

• Tailwind CSS: tailwind.config.js는 각 패키지마다 필요했지만, tailwind.config.css는 하나만으로도 충분했습니다. tailwind.config.ts의 content 경로 설정 오류로 스타일이 적용되지 않는 문제가 있었고, shared 패키지의 컴포넌트를 올바르게 참조하도록 경로를 수정하여 해결했습니다.

• 스토리북: 공통 컴포넌트를 위한 스토리북을 shared 패키지에 통합하려 했으나, 스타일 독립성과 개발 서버의 캐싱 문제로 인해 통합 구현은 어려웠습니다. 결국 shared 패키지 자체와 각 애플리케이션(learner 등) 하위에 .storybook 설정을 분리하여 관리했습니다. 이로 인해 node_modules/.cache 디렉토리가 각 프로젝트에 생성되는 부작용(side effect)이 있었습니다.

3. 점진적 코드 이전과 난관들

설정 통합을 마친 후, 본격적으로 기존 코드들을 shared 패키지로 이전하는 작업을 시작했습니다. 이 과정은 예상보다 훨씬 험난했습니다.

• 타입 시스템과의 씨름: 타입 선언, 추론 방식이 변경되면서 스토리북 및 useQuery 반환 값의 타입이 any로 추론되는 문제가 발생했습니다. 이는 두 개의 tsconfig에서 paths 설정이 충돌한 것이 주요 원인이었습니다. references 설정을 통해 해결을 시도했으나, 파일 경로 인식 문제와 paths 옵션 조정 과정에서 또 다른 문제가 발생하는 등 많은 시행착오를 겪었습니다.

• import 경로 문제: package.json 설정을 통해서 파일 확장자를 명시하는 import가 동작하지 않아 기존 코드들을 상당 부분 수정해야 했습니다.(많은 코드들을 배럴파일 화 하는 등 추가 작업이 필요했습니다)

• shared 패키지의 빌드 의존성: shared 패키지의 코드가 다른 애플리케이션에서 사용되기 전에 먼저 빌드되어야 한다는 것을 깨달았습니다. package.json의 scripts 설정을 통해 shared 패키지의 선 빌드를 자동화하여 해결했습니다.

• 스타일 깨짐 현상: shared 패키지로 이전된 컴포넌트의 스타일이 적용되지 않는 문제가 발생했습니다. 이는 tailwind.config.ts의 content 경로가 shared 패키지를 올바르게 참조하도록 설정되지 않았기 때문이었습니다.

4. 실제 프로젝트 적용과 Git 관리

모노레포의 실제 프로젝트 적용은 기존 Git 레포지토리의 구조를 변경하는 작업이 포함되었습니다. 기존 운영 PR들을 머지하고, 새로운 모노레포 폴더 구조를 생성한 뒤 코드를 이전했습니다. 이후 모노레포 설정 적용, shared로 코드 이전 및 import 수정, 불필요한 package.json 정리, 그리고 설정을 위한 패키지 분리까지 완료했습니다.

이 과정에서 git-filter-repo와 같은 도구를 사용해야 하는지에 대한 고민이 있었습니다. git-filter-repo는 주로 서로 다른 Git 히스토리를 가진 독립적인 저장소들을 하나의 모노레포로 통합할 때 필요합니다. 하지만 저희 프로젝트의 경우, 기존 프로젝트를 모노레포 구조로 재구성하는 형태였기에 별도의 Git 히스토리 병합이 필요하지 않았고, 결국 이 도구를 사용하지 않고도 원활하게 모노레포를 구축할 수 있었습니다.

마지막으로, 통합된 CI/CD 파이프라인을 구축하여 하나의 파이프라인 파일로 여러 서비스의 빌드 및 배포를 관리할 수 있게 되었습니다. 이는 배포 프로세스의 효율성을 크게 향상시켰습니다.

회고: 배운 점과 5개월 후의 개선점들

모노레포 전환은 기술적인 깊이와 넓은 시야를 요구하는 복잡한 작업이었습니다. npm workspaces의 특성을 이해하고, TypeScript, ESLint, Tailwind CSS 등 다양한 도구의 설정을 통합하는 과정에서 많은 시간을 들였지만, 그만큼 팀원들의 문제 해결 능력과 기술 역량을 크게 향상시키는 계기가 되었습니다.

이번 여정을 통해 얻은 가장 큰 교훈은 점진적인 접근과 충분한 테스트, 그리고 명확한 의존성 관리의 중요성이었습니다. 초기에는 예상치 못한 문제들이 속출했지만, 매일매일 해결책을 찾아나가면서 목표를 달성할 수 있었습니다. 특히, 어떤 도구가 어떤 상황에 필요한지에 대한 정확한 이해(예: git-filter-repo 불필요)는 불필요한 공수를 줄이는 데 중요함을 깨달았습니다.

모노레포 도입 후 5개월여가 지났습니다. 큰 구조적 변화는 없었지만 몇 가지 작업이 더 진행 됐습니다.

• build 설정을 각 프로젝트에 보다 체계적으로 배치하는 작업

• shared 컴포넌트들의 폴더 트리를 더욱 효율적으로 구성하는 작업

• firebase, react-gtm-module, tanstack/react-query 등 주요 라이브러리들을 shared 영역으로 완전히 이전하는 작업

이번 프로젝트에서 모노레포를 적용한 건 서비스 확장 전략에 있어 핵심적인 기술 선택이 됐고 많은 유익이 있었습니다.
하지만 이 글에서 언급됐던것처럼 다양한 설정들을 조정해야 될 수 있으니 트레이드 오프를 고려하여 적용되야 할 기술이라고 생각합니다.

간헐적으로 발생하는 API 타임아웃은 원인 파악이 가장 까다로운 장애 유형 중 하나입니다. 이 글에서는 다중 프록시 및 로드밸런서를 거치는 아키텍처의 프론트엔드 서버에서 발생한 간헐적 API 타임아웃의 원인을 분석하고, Nginx의 DNS 해석 방식을 수정하여 문제를 해결한 과정을 회고합니다.

2. 시스템 아키텍처와 문제 현상

장애가 발생한 시스템의 트래픽 흐름은 다음과 같이 다층적으로 구성되어 있습니다.(완전히 정확하진 않고 대략 이렇습니다)

Client -> AWS API Gateway -> WAF ALB -> 3rd-party WAF -> ALB -> Frontend Server(Nginx)

문제는 이 마지막 단계인 프론트엔드 서버의 Nginx에서 발생했습니다. 이 Nginx 서버는 SPA(Single Page Application)의 정적 빌드 파일을 서빙하는 동시에, /api/* 경로로 들어오는 모든 요청을 백엔드 API 게이트웨이(자체 ALB, api.aurora-corp.io 도메인, 의사 도메인입니다)로 프록시하는 역할을 담당했습니다.

아래는 전체 아키텍처를 도식화한 차트입니다.

graph TD
    %% Node Definitions
    Client([Client])
    APIGW[AWS API Gateway]
    WAF_ALB[WAF + ALB]
    ThirdPartyWAF[3rd-party WAF]
    FE_ALB[ALB for Frontend]
    Nginx[Frontend Server <br> Nginx]
    Backend_GW[Backend API Gateway<br>api.aurora-corp.io via ALB]

    %% Subgraph Grouping
    subgraph "User Zone"
        Client
    end

    subgraph "AWS Infrastructure"
        APIGW
        WAF_ALB
        ThirdPartyWAF
        FE_ALB
        Nginx
    end

    subgraph "Backend Zone"
        Backend_GW
    end

    %% Edge Definitions (Connections)
    Client --> APIGW
    APIGW --> WAF_ALB
    WAF_ALB --> ThirdPartyWAF
    ThirdPartyWAF --> FE_ALB
    FE_ALB --> Nginx
    Nginx -- "/api proxy" --> Backend_GW

    %% Styling
    style Nginx fill:#f9f,stroke:#333,stroke-width:2px,color:black

주요 현상:

• 정적 파일 서빙(index.html, JS, CSS 등)은 항상 정상적으로 동작했습니다.

• 오직 /api/* 경로로 프록시되는 요청 중 일부만 Connection Timeout 에러를 반환했습니다.

• 장애는 특정 API에 국한되지 않고 불규칙하게 발생했습니다.

• 프론트엔드 Nginx 프로세스를 재시작(restart or reload)하면 현상이 해소되었습니다.

3. 원인 분석: 정적 DNS 캐싱과 Stale Keep-alive Connection

초기 장애 분석 단계에서, 문제의 범위를 좁히기 위해 전체 트래픽 경로에 대한 로그를 면밀히 검토했습니다. AWS API Gateway, 각 단계의 WAF 및 ALB, 그리고 최종 백엔드 애플리케이션의 로그까지 확인했지만, 어떤 컴포넌트에서도 지연 시간 증가, 에러 로그, 슬로우 쿼리 등의 유의미한 흔적을 발견할 수 없었습니다.

모든 백엔드 시스템이 정상적으로 응답하고 있다는 사실은, 장애의 원인이 외부가 아닌 프론트엔드 Nginx 자체에 국한되어 있음을 명확히 나타내고 있었습니다. 프론트 재배포로 인한 Nginx 재시작으로 문제가 임시 해결된다는 점을 바탕으로, Nginx의 내부 상태, 특히 백엔드와의 커넥션 관리 방식을 집중적으로 분석했습니다.

핵심 원인은 Nginx의 upstream 블록이 동적 클라우드 리소스(ALB)와 상호작용하는 방식에 있었습니다.

1. Nginx upstream의 DNS 캐싱: 오픈소스 Nginx의 upstream 모듈은 설정이 로드되는 시점(시작 또는 리로드)에 단 한 번만 도메인 이름(api.aurora-corp.io)을 IP 주소로 확인(resolve)한다. 그리고 이 IP 주소 목록을 내부 메모리에 캐싱합니다.

2. 백엔드 ALB의 동적 IP: 백엔드 API 게이트웨이 앞단의 ALB는 트래픽, 인스턴스 상태 등에 따라 노드의 IP 주소를 동적으로 변경합니다.

3. Stale Connection 발생: 프론트엔드 Nginx는 최초에 확인한 백엔드 ALB의 IP 주소 목록을 기반으로 TCP 커넥션 풀(Keep-alive)을 생성하고 유지한다. 시간이 지나 백엔드 ALB의 IP가 변경되면, Nginx의 커넥션 풀에 남아있는 일부 커넥션은 더 이상 유효하지 않은 과거의 IP(Stale IP)를 가리키게 된다.

새로운 API 요청이 이 Stale IP를 사용하는 커넥션을 재사용하게 되면, Nginx는 존재하지 않는 엔드포인트에 연결을 시도하다가 결국 proxy_connect_timeout에 도달하여 실패합니다. 유효한 커넥션을 할당받은 다른 요청들은 정상 처리되었기 때문에, '간헐적'이고 '일부 API'에서만 타임아웃이 발생하는 것처럼 보인 것입니다.

4. 해결 방안: 동적 DNS Resolution으로 전환

이 문제를 해결하기 위해 upstream 블록을 제거하고, Nginx가 요청 시점에 DNS를 동적으로 조회하도록 설정을 변경했습니다.

# /etc/nginx/conf.d/default.conf

server {
  # 1. Resolver 정의: 신뢰할 수 있는 DNS 서버(VPC 내부 리졸버 등)를 지정.
  resolver 10.110.11.11 valid=30s;

  # 2. 백엔드 호스트를 변수로 선언.
  set $backend_host "api.aurora-corp.io";

  location ~ ^/api/ {
    # 3. proxy_pass에 변수 사용: 변수를 사용하면 Nginx는
    # resolver를 통해 TTL(valid=30s)을 존중하며 DNS를 동적으로 조회한다.
    proxy_pass https://$backend_host$request_uri;
    ...
  }
}

proxy_pass 지시어에 변수가 포함되면 Nginx는 upstream의 정적 캐시 메커니즘을 사용하지 않고, resolver를 통해 DNS를 해석합니다. 이로써 백엔드 ALB의 IP 변경에 유연하게 대응할 수 있게 되었다.

5. 파생 문제 해결 및 최종 설정

proxy_pass에 변수를 사용하는 방식은 세 가지 중요한 부가 설정을 요구합니다.

1. 쿼리스트링 보존: proxy_pass https://$backend_host/$1$2$is_args$args변수 사용 시 쿼리스트링이 누락되므로, $is_args$args를 명시하여 보존했습니다

2. SNI(Server Name Indication) 활성화: proxy_ssl_server_name on;

   • HTTPS 백엔드 통신 시 TLS 핸드셰이크 오류를 방지하기 위해 SNI를 활성화했습니다.

3. 원본 프로토콜 전달: proxy_set_header X-Forwarded-Proto $scheme;

   • 다중 프록시 환경에서 원본 프로토콜을 정확하게 전달하도록 수정했습니다.

6. 결론

복잡한 클라우드 아키텍처에서는 각 컴포넌트의 내부 동작 방식을 정확히 이해하는 것이 중요합니다. 이번 장애는 프론트엔드 서버 Nginx의 DNS 캐싱 정책이 백엔드 ALB의 동적 특성과 맞지 않아 발생한 문제였습니다. 특히, 장애 분석 과정에서 다른 모든 시스템의 정상 동작을 먼저 확인함으로써 문제의 범위를 효과적으로 좁힐 수 있었습니다.

마치며

• 백엔드 엔드포인트가 ALB 등 동적 IP를 사용하는 서비스일 경우, Nginx 오픈소스 버전의 upstream 블록 사용은 잠재적 장애 요인이 될 수 있습니다.

• resolver와 변수를 사용한 동적 DNS 조회는 이러한 환경에 대한 표준적인 해결책입니다.

• 하나의 설정을 변경하면 연쇄적으로 고려해야 할 다른 설정(쿼리스트링, SNI 등)이 있음을 인지하고 종합적으로 접근해야 합니다.

개발 후 QA과정에서 재현 조건이 까다로운 오류와 마주쳤습니다.

NotFoundError: Failed to execute 'removeChild' on 'Node': The node to be removed is not a child of this node.

React 개발자라면 한 번쯤 봤을 법한 이 오류는 일반적으로 React의 가상 DOM 상태와 실제 DOM 상태가 일치하지 않을 때 발생합니다. 하지만 이번 경우는 달랐습니다. 오류는 특정 사용자 그룹의 특정 상황, 바로 Chrome의 '이 페이지 번역' 기능을 활성화했을 때만 발생했습니다.

기나긴 디버깅 여정: 가설과 실패의 연속

이 문제를 해결하기 위해 여러 가설을 세우고 다양한 해결책을 시도했습니다.

1. 가설 1: React 상태 업데이트 경쟁 상태

   • 시도: Select 컴포넌트의 onValueChange 핸들러에서 여러 상태가 동시에 업데이트되면서 렌더링 충돌이 발생한다고 추측했습니다. useTransition과 setTimeout을 사용해 상태 업데이트에 지연을 주어 렌더링 타이밍을 분리하고자 했습니다.

   • 결과: 실패. 오류는 여전히 발생했습니다.

2. 가설 2: 컴포넌트 레벨에서의 번역 차단

   • 시도: 문제가 Chrome 번역 기능에 있다는 것을 인지하고, 오류가 발생하는 Radix UI의 SelectItem 컴포넌트에 translate="no" 속성을 추가하여 해당 부분의 번역을 막으려고 시도했습니다.

   • 결과: 실패. SelectItem 내부의 텍스트 노드는 여전히 번역기에 의해 수정되었고, 문제는 해결되지 않았습니다.

3. 가설 3: Radix UI의 Portal 시스템과 번역기의 충돌

   • 시도: Radix UI는 Select의 드롭다운 메뉴를 document.body 끝에 Portal을 사용해 렌더링합니다. 이 Portal 내부의 DOM이 번역기에 의해 조작되면서 충돌이 발생한다고 판단, Portal 기능을 제거하고 컴포넌트 내부에 직접 렌더링하도록 수정했습니다. 또한 requestAnimationFrame과 더 긴 setTimeout 지연(100ms)을 결합하여 타이밍 이슈를 해결하려 했습니다.

   • 결과: 실패. 오류의 발생 빈도가 줄어드는 것처럼 보였지만, 근본적인 해결책은 아니었습니다. 오류는 결국 다시 발생했습니다.

근본 원인 분석: React의 예측을 배신하는 <font> 태그

모든 시도가 실패로 돌아간 후, 우리는 문제의 본질을 더 깊이 파고들었습니다. 원인은 React의 가상 DOM과 Chrome 번역기가 실제 DOM을 조작하는 방식 사이의 근본적인 불일치에 있었습니다. 특히, 한 커뮤니티 블로그 포스트(출처)는 결정적인 단서를 제공했습니다.

React: 예측 가능한 가상 DOM

React는 "가상 DOM"이라는 자신만의 설계도를 가지고 있습니다. React가 렌더링하는 모든 요소는 이 설계도에 기록됩니다. 예를 들어 SelectItem은 내부에 "이름"이라는 순수한 텍스트 노드를 가지고 있습니다.

// React의 가상 DOM (설계도)
<Item>
  "이름"  <-- 텍스트 노드
</Item>

번역기: 예측 불가능한 <font> 태그 주입

반면, Chrome 번역기는 React의 설계도를 무시하고 실제 DOM에 직접 개입합니다. 번역기는 "이름" 텍스트 노드를 발견하면, 그 내용을 바꾸는 것을 넘어 <font> 태그로 감싸버립니다.

<!-- 번역기가 변경한 실제 DOM -->
<Item>
  <font>"Name"</font>  <-- font 요소 노드
</Item>

React가 기억하던 "이름" 텍스트 노드는 사라지고, 그 자리에는 <font>라는 새로운 요소가 들어서게 됩니다.

충돌의 순간 분석

이 복잡한 충돌 과정을 순서도로 표현하면 다음과 같습니다.

sequenceDiagram
    participant User
    participant React as React (Virtual DOM)
    participant Translator as Chrome Translator
    participant DOM as Browser (Real DOM)

    User->>React: Select Trigger 클릭
    React->>DOM: "이름" 텍스트를 포함한 드롭다운 렌더링
    activate DOM

    Note over Translator, DOM: 번역기가 DOM을 스캔하여 번역할 텍스트 탐색

    Translator->>DOM: "이름" 텍스트 노드 제거 (React 몰래)
    Translator->>DOM: "Name" 텍스트 노드 삽입 (React 몰래)

    User->>React: 번역된 "Name" 아이템 클릭
    React->>React: 드롭다운 unmount 시작

    Note over React, DOM: React는 자신의 Virtual DOM을 기준으로<br/>원래 있던 "이름" 노드를 제거하려 함

    React->>DOM: removeChild("이름") 요청
    DOM-->>React: 오류! "이름" 노드를 찾을 수 없음
    deactivate DOM

    React-->>User: "NotFoundError" 오류 발생

1. React: 사용자가 메뉴를 닫으면, 자신의 설계도에 따라 <Item> 컴포넌트에서 "이름" 텍스트 노드를 제거하라고 지시합니다.

2. 실제 DOM: <Item> 컴포넌트를 확인하지만, 그 안에는 "이름" 텍스트 노드가 없고 <font> 요소만 존재합니다.

3. 브라우저: NotFoundError 발생. 제거하려는 "이름" 노드는 <Item>의 자식이 아니기 때문입니다.

Radix UI가 특히 취약했던 이유는 Select, DropdownMenu, Tooltip 등 텍스트를 포함하고 Portal을 사용하는 복잡한 컴포넌트가 많기 때문입니다. Portal은 DOM 트리 상의 다른 위치에 UI를 렌더링하므로 번역기의 스캔에 더 쉽게 노출되고, 복잡한 상호작용(포커스 관리, 접근성 속성 변경 등) 도중에 DOM이 예기치 않게 변경되면 전체 로직이 깨지기 쉽습니다.

최종 해결책: 충돌의 원천 차단

결국 저는 충돌을 '해결'하는 것이 아니라, 충돌의 '원인' 자체를 원천적으로 차단하는 방향으로 선회했습니다. index.html에 다층적인 번역 방지 시스템을 구축하여, Chrome 번역기가 우리 애플리케이션의 DOM에 아예 접근하지 못하도록 막았습니다.

• HTML 속성: <html>, <body>에 translate="no", class="notranslate" 추가

• 메타 태그: <meta name="google" content="notranslate">로 번역 서비스 비활성화

• JavaScript: MutationObserver를 사용해 React가 동적으로 생성하는 모든 DOM 노드에도 실시간으로 번역 방지 속성을 강제 주입

이 방법은 '번역'이라는 기능을 포기해야 하는 트레이드오프가 있지만, 애플리케이션의 안정성을 보장하는 가장 확실한 해결책이었습니다.

다른 제품에서 ‘번역’이라는 기능을 포기할 수 없는 상황이라면 어떻게 대응할까도 고민해봤습니다. 첫째로 범위를 제한한 번역 금지 기능, 둘째로 Radix UI 포탈처럼 번역에서 안전하지 않은 Portal을 커스텀 포탈로 제한하는 방식을 조합해 적용해볼 수 있을 것 같습니다.

결론

이번 경험을 통해 몇 가지 교훈을 얻을 수 있었습니다.

1. React의 통제권은 절대적이지 않다: 우리는 React가 DOM을 완전히 통제한다고 가정하지만, 브라우저 확장 프로그램이나 외부 스크립트는 언제든 이 가정을 깨뜨릴 수 있습니다.

2. '불가능한' 버그는 외부 요인을 의심하라: 코드 상의 로직으로 설명되지 않는 오류가 발생한다면, 브라우저 환경, 확장 프로그램, 네트워크 등 애플리케이션 외부의 요인을 반드시 고려해야 합니다.

3. 커뮤니티를 활용하라: 비슷한 문제를 겪고 해결한 다른 개발자들의 경험(참고 블로그)은 문제 해결의 결정적인 실마리가 될 수 있습니다.

4. 때로는 회피가 최선의 해결책이다: 제어할 수 없는 외부 요인과의 충돌은 정면으로 맞서기보다, 충돌 자체가 발생하지 않도록 원인을 차단하거나 우회하는 것이 더 현실적이고 안정적인 해결책일 수 있습니다.

이 현상의 중심에는 React의 성능 최적화 전략인 "Bailout" 이 있습니다. 말 그대로, React가 "이 컴포넌트는 변경점이 없으니, 렌더링 과정을 건너뛰자!"라고 결정하는 스마트한 메커니즘입니다.

이번 글에서는 이 Bailout이 어떤 원리로 동작하는지, 실제 React 소스 코드와 다이어그램을 통해 파헤쳐 보겠습니다.

수수께끼: 왜 일부만 리렌더링될까?

다음과 같은 컴포넌트 구조를 상상해 보세요.

// 우리의 컴포넌트 구조
<A>
  <B>
    <C>
      <button/>
      <D/>
    </C>
  </B>
  <E>
    <F/>
  </E>
</A>

여기서 컴포넌트 C 안의 버튼을 클릭해 상태를 변경하면, 놀랍게도 C와 D만 다시 렌더링됩니다. A, B, E, F는 아무런 변화가 없습니다. React는 어떻게 이 사실을 알고 최소한의 작업만 수행했을까요?

모든 것의 시작: setState 호출 시퀀스

사용자가 버튼을 클릭하여 setState를 호출하면 어떤 일이 벌어질까요? 렌더링이 일어나기까지의 과정을 Sequence Diagram으로 먼저 살펴보겠습니다.

sequenceDiagram
    participant User
    participant Component
    participant ReactScheduler as "React 스케줄러"
    participant ReactReconciler as "React 조정자 (Reconciler)"

    User->>Component: "버튼 클릭 (이벤트 발생)"
    Component->>Component: "setCount() 호출"
    Component->>ReactScheduler: "scheduleUpdateOnFiber() (업데이트 예약)"
    Note right of ReactScheduler: "업데이트에 'lane'을 할당하고<br/>루트까지 전파<br/>(markUpdateLaneFromFiberToRoot)"

    ReactScheduler->>ReactReconciler: "performUnitOfWork() (작업 단위 수행)"
    loop "각 파이버(Fiber)에 대해"
        ReactReconciler->>ReactReconciler: "beginWork(fiber)"
        Note left of ReactReconciler: "Bailout 여부 결정"
        alt "Bailout 성공 (변경 없음)"
            ReactReconciler-->>ReactReconciler: "작업 중단 (null 반환)"
        else "Bailout 실패 (변경 있음)"
            ReactReconciler-->>ReactReconciler: "자식 파이버 생성/업데이트<br/>(reconcileChildren)"
        end
    end

이 다이어그램은 업데이트 요청이 어떻게 스케줄러를 통해 조정자(Reconciler)에게 전달되고, beginWork 함수가 각 컴포넌트(파이버)의 운명을 결정하는 핵심 역할을 하는지 보여줍니다.

Deep Dive 1: 업데이트의 흔적, lanes와 Fiber 노드

React는 내부적으로 컴포넌트 트리를 파이버(Fiber) 노드 트리로 관리합니다. 각 파이버는 컴포넌트의 작업 단위이자 상태를 저장하는 장소입니다. setState가 호출되면 React는 이 파이버 노드에 흔적을 남깁니다.

• lanes: 상태 변경이 직접 일어난 파이버에 꽂히는 깃발(flag)입니다.

  • lane왈: "나 자신이 업데이트되어야 해!"

• childLanes: 상태 변경이 일어난 파이버의 모든 부모에게 꽂히는 깃발입니다.

  • childLane왈: "내 자식들 중에 업데이트가 필요한 녀석이 있어!"

이 속성들은 파이버 노드 객체 안에 존재합니다. 파이버 노드의 구조를 간단히 살펴보겠습니다.

Deep Dive 2: Bailout의 관문, beginWork 소스 코드 분석

이제 하이라이트인 beginWork 함수의 실제 코드를 살펴보겠습니다. 이 함수가 어떻게 props와 lanes를 사용해 Bailout을 결정하는지 직접 확인해보겠습니다.

// source: react-reconciler/src/ReactFiberBeginWork.js (일부 단순화)

function beginWork(current, workInProgress, renderLanes) {
  // 'current'는 이전 렌더링의 파이버입니다. null이 아니면 업데이트 상황입니다.
  if (current !== null) {
    const oldProps = current.memoizedProps;
    const newProps = workInProgress.pendingProps;

    // 1. props나 context가 변경되었는가? (참조 비교)
    if (oldProps !== newProps || hasContextChanged()) {
      // 변경되었으면 무조건 리렌더링 진행
      didReceiveUpdate = true;
    } else {
      // 2. props는 같다. 그럼 스케줄된 업데이트(lanes)가 있는가?
      const hasScheduledUpdate = checkScheduledUpdateOrContext(current, renderLanes);
      if (!hasScheduledUpdate) {
        // 3. 스케줄된 업데이트도 없다! 최종 Bailout 시도.
        // 이 함수 내부에서 childLanes를 확인하고 최종 결정을 내립니다.
        return attemptEarlyBailoutIfNoScheduledUpdate(current, workInProgress, renderLanes);
      }
      // ...
    }
  }

  // ...
  // Bailout 되지 않았다면, 컴포넌트 타입에 따라 렌더링 함수를 실행합니다.
  return updateFunctionComponent(current, workInProgress, ...);
}

이 코드의 논리를 Flowchart로 시각화하면 더욱 명확해집니다.

flowchart TD
    subgraph "beginWork 함수 로직"
        direction LR
        A["시작"] --> B{"current !== null?<br/>(current: 이전 렌더링 파이버)"};
        B -->|No| R["새로운 컴포넌트 렌더링"];

        subgraph "업데이트 경로"
            direction TB
            B -->|Yes| C{"oldProps !== newProps?"};
            C -->|No| D{context 변경?};
            D -->|No| E{"lanes에 업데이트 존재?"};
            E -->|No| G{"childLanes에 업데이트 존재?"};
        end

        C -->|Yes| Q["didReceiveUpdate = true<br>리렌더링 진행"];
        D -->|Yes| Q;
        E -->|Yes| Q;

        G -->|No| H["최종 Bailout!<br>작업 중단 (null 반환)"];
        G -->|Yes| I["자신은 건너뛰고<br>자식 파이버로 계속 진행"];
    end

    Q --> R;
    I --> R;
    R --> S["완료"];
    H --> S;

숨겨진 범인: 왜 아무 상관 없는 <D/>는 리렌더링될까?

이제 D가 리렌더링되는 이유를 코드 레벨에서 추적할 수 있습니다. C는 Bailout에 실패했으므로 updateFunctionComponent가 호출됩니다. 이 함수는 C의 렌더링 함수를 실행하여 return <div...><D/></div>를 통해 새로운 <D/> 엘리먼트 객체를 만듭니다.

이 새 엘리먼트는 D 파이버의 pendingProps가 됩니다. 다음 차례에 D의 beginWork가 실행될 때, oldProps !== newProps 비교에서 두 객체의 메모리 주소가 다르므로 true를 반환하고, 결국 리렌더링으로 이어지는 것입니다.

아무 상관없는 컴포넌트 해결책: 참조를 동일하게 유지하라

이 문제를 해결하기 위해 개발자들은 props의 참조를 동일하게 유지하려는 다양한 메모이제이션(memoization) 노력을 해왔습니다. 단순히 자식 컴포넌트 자체를 React.memo로 감싸는 것뿐만 아니라, 자식에게 전달하는 props가 렌더링마다 새로 생성되지 않도록 막는 것이 핵심입니다.
위와 같은 기법들의 공통 목표는 "렌더링 시 불필요한 참조 생성을 막아 React의 Bailout 메커니즘이 효율적으로 동작하도록 돕는 것" 입니다.

미래 엿보기: React 19와 React Compiler

React 19부터 선택적으로 도입되는 React Compiler는 이 모든 과정을 자동화하는 것을 목표로 합니다. 컴파일러가 코드를 미리 분석하여 <D />와 같이 불필요하게 재생성되는 부분을 찾아내고, 자동으로 React.memo로 감싼 것과 같은 효과를 내도록 코드를 변환해줍니다. 아직은 실험적인 기능이지만, React의 개발 경험이 어떻게 진화할지 보여주는 흥미로운 방향입니다.

결론

React의 "Bailout"은 props의 참조 동일성과 내부적인 lanes 시스템을 기반으로 동작하는 정교한 최적화 메커니즘입니다. beginWork라는 관문을 통해 각 컴포넌트의 운명을 결정하며, 이 과정을 이해하는 것은 React의 성능을 최대로 끌어올리는 데 큰 도움이 됩니다.

우리가 작성하는 코드가 화면 뒤에서 어떻게 동작하는지 알 때, 우리는 더 나은 코드를 작성하고 예측 불가능한 버그를 더 쉽게 해결할 수 있기 때문입니다. 부족한 글 읽어주셔서 감사합니다.

최근 겪었던 실제 사례를 통해 이 문제를 깊이 파헤쳐 보겠습니다. 상황은 이랬습니다. 헤더에 표시되는 회사 이름 중, 이더리움그룹처럼 긴 이름은 정상 출력되는데, (주)비트처럼 훨씬 짧은 이름이 말줄임표(...) 처리되는 현상이 발생했습니다. 직관에 반하는 이 현상을 마주하고 혼란스러웠고 문제를 해결해도 개운하게 이해가 안됐었습니다. 결론부터 말하면, 범인은 truncate가 아니라 flex-shrink였습니다.

Case Study: 왜 짧은 텍스트가 잘리는가?

문제의 컴포넌트는 다음과 같은 구조를 가졌습니다.(의사 코드입니다)

// Header Layout
<header className="flex justify-between items-center">
  {/* Left Section */}
  <div className="flex items-center gap-3">
    <img src="/logo.svg" alt="logo" />
    <CompanyName companyName={name} />
  </div>

  {/* Right Section */}
  <div className="flex items-center gap-4">
    <span>{user.name}</span>
    <Avatar />
  </div>
</header>

CompanyName 컴포넌트는 반응형 분기에 따라 md 이상 스크린에서 truncate가 적용되도록 설정되어 있었습니다. 초기 분석 시에 truncate와 텍스트 줄바꿈(word-break)의 문제에 집중했었죠.

1차 분석: word-break와 truncate의 상호작용

최초 코드에는 한글 단어가 깨지지 않도록 break-keep (word-break: keep-all)이 적용해둔 상태였습니다. 여기서 첫 번째 단서를 발견했습니다.

• 이더리움그룹: break-keep에 의해 통짜 단어로 인식된다.

• (주)비트: 괄호 ()는 CSS에서 단어 분리 문자로 취급될 수 있습니다. 이로 인해 브라우저는 (주)와 비트를 별개의 어휘 단위로 판단, 그 사이에서 줄바꿈이 발생할 수 있습니다.

이것이 초기 "깨짐" 현상의 원인이었습니다. 하지만 truncate는 white-space: nowrap을 포함하므로 줄바꿈 자체가 일어나면 안 됩니다. 그런데 왜 (주)비트는 여전히 두 줄로 "깨지면서" 동시에 truncate가 되려고 했을까요?

범인은 md:whitespace-normal 같은 반응형 오버라이드였습니다. 특정 분기점에서 nowrap을 해제하면서 break-keep의 동작과 충돌을 일으킨 것입니다.

이 분석에 따라 break-all을 적용하고 반응형 클래스를 정리했습니다. 줄바꿈 문제는 해결됐지만, 근본적인 truncate 현상은 사라지지 않았습니다.

2차 분석: 진짜 범인, flex-shrink

문제의 본질은 CompanyName 컴포넌트 자체에 있지 않았습니다. 헤더의 flex 컨테이너가 원인이었습니다.

1. Flexbox의 공간 분배: justify-between은 자식 요소들을 양 끝으로 밀어냅니다. 왼쪽엔 [로고, 회사이름], 오른쪽엔 [사용자이름, 아바타]가 위치합니다.

2. flex-shrink의 기본 동작: flex 아이템은 기본적으로 flex-shrink: 1 속성을 가집니다. 이는 컨테이너에 공간이 부족할 경우, 할당된 공간을 양보하며 스스로 "수축(shrink)"할 수 있음을 의미합니다.

3. 시나리오: 오른쪽의 사용자이름이 길어지면, 오른쪽 섹션은 더 많은 공간을 요구합니다. flex 컨테이너의 전체 너비는 고정되어 있으므로, 왼쪽 섹션은 공간을 양보해야 합니다. 이때 CompanyName이 flex-shrink: 1 속성에 따라 수축하게됩니다.

결국 (주)비트라는 텍스트 길이는 문제가 아니었습니다. 다른 flex 아이템 때문에 CompanyName 컴포넌트 자체가 자신의 콘텐츠보다 좁은 너비를 할당받았기 때문에 truncate가 발동한 것입니다.

해결책: flex-shrink: 0

해결책은 간단했습니다. CompanyName 컴포넌트가 수축하지 않도록 명시하는 것입니다.

function CompanyName({ className, companyName }) {
  return (
    /** 'shrink-0'가 핵심 */
    <div
      className={cn(
        "shrink-0 px-3 py-1 font-medium rounded-md border md:truncate ...",
        className
      )}
    >
      {companyName}
    </div>
  );
}

Tailwind 유틸리티 shrink-0 (flex-shrink: 0)를 추가함으로써, 이 컴포넌트는 더 이상 형제 요소에게 공간을 양보하지 않고 자신의 고유 콘텐츠 너비를 유지하게 됩니다. 이로써 짧은 텍스트가 잘리는 현상은 해결됐습니다.

CSS 텍스트 처리 속성 요약

이 사례에 등장한 핵심 속성들을 표로 정리하면 다음과 같습니다. 이 표 하나로 대부분의 텍스트 처리 이슈를 진단할 수 있습니다. 텍스트 처리 이슈를 마주할때마다 제가 다시 보기 위해 정리 해뒀습니다.

키 포인트

• truncate는 텍스트 길이가 아닌, 할당된 공간의 크기에 따라 동작한다.

• flex 레이아웃에서 아이템의 크기는 형제 요소에 의해 동적으로 변할 수 있다. flex-shrink 속성을 항상 염두에 두어야 한다.

• break-keep은 CJK 텍스트 처리 시 유용하지만, 특수 문자에 의해 의도치 않은 단어 분리가 발생할 수 있다.

• 문제가 발생하면 해당 요소만 보지 말고, 부모의 레이아웃 시스템(Flex, Grid 등)과 형제 요소와의 상호작용까지 반드시 확인해야 한다.

단순한 UI 버그처럼 보였던 이슈를 통해 CSS의 핵심 원리인 레이아웃, 컨텍스트, 그리고 속성 간의 상호작용을 돌아볼 수 있었습니다. 정리를 안해두면 왠지 계속 비슷한 씨름을 하게 될 것 같아 글로 정리해봤습니다.

감사합니다.

이 글에서는 React 19의 렌더링 과정을 두 단계로 나누어 설명합니다.

• 1부에서는 모든 React 19 애플리케이션의 기본 동작인 표준 렌더링 파이프라인을 살펴봅니다.

• 2부에서는 React Compiler가 이 표준 파이프라인 위에서 어떻게 자동으로 작동하여, 우리가 수동으로 하던 최적화 작업을 자동화하는지 보겠습니다.

1부: React 19의 표준 렌더링 파이프라인

React 19의 기본적인 렌더링 과정은 이전 버전의 핵심 원칙을 계승합니다. 렌더링 과정은 크게 트리거(Trigger), 렌더(Render), 커밋(Commit) 세 단계의 파이프라인으로 이루어집니다.

React 4가지 핵심 원칙 간단 정리

1. 상태(state)가 UI를 결정한다: 개발자가 상태(state = data)를 바꾸면 UI는 알아서 바뀐다.

2. 선언적 프로그래밍: UI가 어떤(what) 상태여야 하는지 선언한다.

3. 재조정(Reconciliation): 가상의 UI 구조(virtual DOM)에서 변경 전후 차이점 비교로 재조정한다.

4. 컴포넌트 기반 아키텍쳐: UI를 독립적이며 재사용 가능한 컴포넌트 단위로 조립한다.

1. 트리거(Trigger) 단계: 변경의 시작

"업데이트가 필요하다"는 사실을 인지하고 작업을 예약하는 단계입니다.

• 시작점: 사용자의 클릭 등으로 useState의 세터 함수가 호출되면서 시작됩니다.

• 작업 예약: React는 이 업데이트가 얼마나 시급한지 판단하여 우선순위(lanes)를 매깁니다. 예를 들어, 버튼 클릭은 입력에 대한 즉각적인 피드백이 중요하므로 높은 우선순위를 갖습니다.

• 경로 표시: 업데이트가 필요한 컴포넌트부터 최상위 루트(root)까지의 경로에 있는 모든 Fiber 노드(컴포넌트에 대한 정보 객체)에 lanes와 childLanes라는 플래그를 남겨, "이쪽 라인을 점검해야 해!"라고 표시합니다.

2. 렌더(Render) 단계: 변경점 계산

"실제 DOM을 건드리지 않고, 가상으로 무엇이 변했는지 계산하는 두뇌 역할" 을 하는 복잡하고 중요한 단계입니다.

• 재조정(Reconciliation): React는 트리거 단계에서 표시된 경로를 따라 Fiber 트리를 순회하며 컴포넌트를 다시 실행합니다. 그리고 이전에 렌더링된 결과와 새로 생성된 결과를 비교합니다.

• 최적화 (Bailout): 재조정 과정에서, 만약 어떤 컴포넌트의 props가 이전과 동일하고 상태 변경도 없다면, React는 "이 컴포넌트와 그 아래 자식들은 모두 변경점이 없겠구나"라고 판단합니다. 그리고 해당 컴포넌트와 그 하위 트리 전체의 렌더링 과정을 통째로 "건너 뛰어(Bailout)" 버립니다. 이것이 바로 React.memo가 수동으로 이끌어내는 핵심 최적화이며, 불필요한 계산을 막아 성능을 향상시킵니다.

• 변경 계획 수립 (플래그 표시): 비교 결과 변경이 감지된 부분은 실제 DOM을 바로 바꾸는 대신, "이 노드는 DOM에 새로 추가해야 함(Placement)", "이 노드는 속성을 수정해야 함(Update)", "이 노드는 제거해야 함(Deletion)" 과 같이 해야 할 일들을 Fiber 노드에 플래그로 기록합니다. 이 플래그들이 모여 최종 **'변경 계획서'**가 됩니다. 이 때 변경 계획서는 Fiber 노드들의 집합인 Fiber 트리에 기록 되있습니다.

3. 커밋(Commit) 단계: 실제 화면에 반영

렌더 단계에서 수립된 '변경 계획서'를 실제 DOM에 적용하여 사용자가 변경을 볼 수 있게 하는 마지막 단계입니다.

• 계획 실행: React는 렌더 단계에서 플래그가 표시된 모든 Fiber 노드를 찾아냅니다.

• DOM 업데이트: 이 플래그에 따라 DOM 노드를 추가, 수정, 삭제하는 실제 작업을 실행합니다. 이 과정은 화면 깜빡임 같은 현상을 막기 위해 동기적으로, 한 번에 일괄 처리됩니다.

• 작업 완료: 모든 DOM 조작이 끝나면 렌더링 과정이 최종적으로 완료됩니다.

이것이 React 19의 표준 렌더링 파이프라인입니다.

React 19 표준 렌더링 파이프라인 시각화

상태 변경부터 실제 UI 업데이트까지 이어지는 Trigger, Render, Commit 단계의 전체 흐름을 시각화합니다.

flowchart TD
    subgraph "[1] 트리거 단계"
        A["상태 변경<br />(예: setState)"]
        B["업데이트 스케줄링"]
        C["Fiber 경로에 lanes 표시<br />리렌더링 위치 지정"]
    end

    subgraph "[2] 렌더 단계"
        D["루트에서 렌더링 시작"]
        E["Fiber 트리 순회"]
        F["업데이트 필요한가?<br />(Bailout 로직)"]
        G["컴포넌트 건너뛰기"]
        H["자식 컴포넌트 재조정"]
        I["DOM 변경 플래그 표시<br/>(추가, 업데이트, 삭제)"]
        J["다음 Fiber로 이동"]
        K["순회 완료?"]
        L["작업 완료된 Fiber 트리 생성"]
    end

    subgraph "[3] 커밋 단계"
        M["커밋 단계 시작"]
        N["실제 DOM에 변경사항 적용<br/>(삭제 → 업데이트 → 추가)"]
        O["UI 업데이트 완료"]
    end

    A --> B
    B --> C

    C --> D
    D --> E
    E --> F
    F -- "아니요" --> G
    F -- "예" --> H
    H --> I
    G --> J
    I --> J
    J --> K
    K -- "아니요" --> E
    K -- "예" --> L

    L --> M
    M --> N
    N --> O

2부: React Compiler, 똑똑한 최적화의 등장

그렇다면 React Compiler는 이 표준 파이프라인에서 어떤 역할을 할까요? 컴파일러는 "렌더 단계를 더 똑똑하게 만드는 조력자" 입니다. 먼저 컴파일러가 어떤 철학으로 설계되었는지 살펴보는 것이 중요합니다.

React Compiler 설계 원칙 (Goals & Non-Goals)

React Compiler의 핵심 설계 목표와, 의도적으로 제외된 비-목표를 시각화하여 프로젝트의 명확한 범위와 방향을 제시합니다.

mindmap
  root((React Compiler<br/>설계 원칙))
    subgraph Goals (핵심 목표)
      id1["자동 및 제한적 리렌더링<br/>(성능 예측성 확보)"]
      id2["시작 시간 성능 유지<br/>(코드 크기 및 오버헤드 최소화)"]
      id3["익숙한 React 모델 유지<br/>(useMemo, useCallback 등 제거)"]
      id4["관용적(Idiomatic) 코드 지원<br/>(React 규칙 준수 코드)"]
      id5["명시적 타입/주석 불필요"]
    subgraph Non-Goals (비-목표)
      id6["완벽하게 최적화된 렌더링<br/>(런타임 오버헤드 방지)"]
      id7["React 규칙을 위반하는 코드 지원"]
      id8["레거시 기능 지원<br/>(클래스 컴포넌트 등)"]
      id9["JavaScript 언어 100% 지원"]

차트에서 볼 수 있듯이, 컴파일러의 핵심 목표는 개발자가 useMemo, useCallback 같은 API를 직접 사용하지 않아도, 자동으로 코드를 분석하여 불필요한 리렌더링을 방지하는 것입니다.

어떻게 가능할까요?

컴파일러는 빌드 시점에 코드를 미리 분석하여, 어떤 값이나 함수가 리렌더링 사이에 변하지 않을지 예측합니다.

• 반응형 스코프(Reactive Scopes) 분석: 컴파일러는 어떤 값들이 서로 의존하는지, 어떤 상태(state)가 변할 때 어떤 부분만 다시 계산하면 되는지를 파악하여 '반응형 스코프'라는 그룹으로 묶습니다.

• 자동 메모이제이션: 분석이 끝나면, 컴파일러는 마치 개발자가 useMemo나 useCallback을 직접 추가한 것처럼 코드를 변환합니다. 이 변환된 코드는 렌더 단계에서 React의 Bailout 최적화를 극대화하여, 불필요한 리렌더링을 원천적으로 차단합니다.

개발자의 최적화 작업 변화 시각화

React Compiler가 도입되면서, 개발자가 수동으로 하던 최적화 작업을 컴파일러가 대신해주는 과정을 보여줍니다.

graph TD
    subgraph "과거 (Compiler 이전)"
        A[개발자] --> B("불필요한 리렌더링 확인");
        B --> C{"최적화 필요한가?"};
        C -- Yes --> D["useMemo, useCallback 등<br>API 직접 적용"];
        C -- No --> E[코드 완료];
        D --> E;
    end

    subgraph "현재 (React 19 + Compiler)"
        F[개발자] --> G("React 규칙에 맞춰<br>컴포넌트/로직 작성");
        G --> H("React Compiler가<br>자동으로 메모이제이션");
        H --> I[코드 완료];
    end

결론: 개발자는 로직에, 최적화는 React에 맡기자

정리하자면, React 19의 렌더링 방식은 다음과 같습니다.

1. 기본적으로는 Trigger → Render → Commit 파이프라인을 따릅니다.

2. React Compiler는 이 파이프라인의 '렌더' 단계를 자동 최적화하여, 개발자가 수동으로 개입할 필요 없이도 최고의 성능을 내도록 돕습니다.

이는 React의 핵심 철학인 'UI를 선언적으로 만드는 것'에 더 깊이 다가가는 중요한 변화입니다. React Compiler는 단순히 편의성을 높이는 것을 넘어, React 생태계 전체의 성능 기준을 한 단계 끌어올리는 혁신을 목표로 하고 있습니다. 만약 이 새로운 기능이 제대로 자리 잡게 된다면, 이제 React를 사용하는 개발자들은 최적화에 대한 고민을 React에 맡기고, 다른 영역에 좀 더 집중할 수 있는 여유(slack)을 가질 수 있게 될 것입니다.

이 글에서는 최신 React 19.1.0 버전의 소스 코드를 기반으로, React 애플리케이션이 최초로 화면을 그리는 '초기 마운트(Initial Mount)' 과정을 다이어그램과 함께 자세히 살펴보겠습니다.

1. 개발자 관점의 시작: createRoot에서 render까지

모든 것은 개발자가 작성하는 몇 줄의 코드에서 시작됩니다. React가 내부적으로 복잡한 일을 하기 전에, 개발자는 어떤 순서로 React와 상호작용할까요? 다음 순서도는 개발자 입장에서의 전체적인 흐름을 보여줍니다.

flowchart TD
    subgraph "개발자 코드 (index.js)"
        A["react-dom/client 에서<br/>import { createRoot }"] --> B["렌더링할 DOM 노드 가져오기<br/>(예시: <br />document.getElementById)"]
        B --> C["createRoot(container)를 <br/>호출하여 root 객체 생성"]
        C --> D["root.render(&lt;App /&gt;)를 호출하여<br/>렌더링 요청"]
    end

    subgraph "React 시스템"
        E["React Root가 생성되고<br/>렌더링 준비 완료"]
        F["&lt;App /&gt; 컴포넌트 트리가<br/>실제 DOM으로 렌더링됨"]
    end

    C -- "결과" --> E
    D -- "결과" --> F

이처럼 개발자는 단지 createRoot로 렌더링의 뿌리를 만들고, render 함수로 무엇을 그릴지 알려주기만 하면 됩니다. 이제부터 이 단순한 함수 호출 뒤에서 React가 어떤 일을 하는지 내부로 깊이 들어가 보겠습니다.

2. React 내부 여정의 첫발: createRoot에서 FiberRoot까지

사용자가 createRoot를 호출하면, React는 렌더링 파이프라인을 시작할 준비에 들어갑니다.

1단계: createRoot (in react-dom)

packages/react-dom/src/client/ReactDOMRoot.js에 위치한 createRoot 함수는 내부적으로 createContainer 함수를 호출하며, 각종 옵션을 설정하고 경고 메시지를 처리하는 역할을 합니다.

// packages/react-dom/src/client/ReactDOMRoot.js
export function createRoot(container, options) {
  // ... 다양한 옵션 및 경고 처리 ...
  const root = createContainer(container, ConcurrentRoot, ...);
  // ... 이벤트 리스너 설정 등 ...
  return new ReactDOMRoot(root);
}

2단계: createContainer & createFiberRoot (in react-reconciler)

핵심 로직은 react-reconciler 패키지에 있습니다. "Reconciler(조정자)"는 가상 DOM과 실제 DOM의 차이를 계산하고 업데이트를 관장하는 React의 core입니다.

createContainer는 내부에서 createFiberRoot 함수를 호출하여, React 애플리케이션의 근간이 되는 두 가지 핵심 객체를 생성합니다.

// packages/react-reconciler/src/ReactFiberReconciler.js
export function createContainer(containerInfo, tag, ...) {
  const hydrate = false;
  const initialChildren = null;
  const root = createFiberRoot(
    containerInfo,
    tag,
    hydrate,
    initialChildren,
    ...
  );
  return root;
}

• FiberRootNode: 전체 애플리케이션 인스턴스에 대한 최상위 객체입니다. 렌더링할 DOM 컨테이너 정보, 현재 렌더링된 트리(current), 업데이트 큐(queue) 등 모든 상태를 총괄합니다. 앱 하나당 단 하나만 존재합니다.

• HostRoot FiberNode: FiberRootNode가 관리하는 Fiber Tree의 실제 시작점이 되는 특별한 종류의 FiberNode입니다.

// packages/react-reconciler/src/ReactFiberReconciler.js
export function createFiberRoot(...) {
  const root = new FiberRootNode(containerInfo, tag, ...);
  // 👇 바로 이 부분에서 HostRoot 타입의 Fiber를 생성합니다.
  const uninitializedFiber = createHostRootFiber(tag, isStrictMode);
  // FiberRootNode가 자신의 'current' 속성으로 HostRoot Fiber를 가리키게 합니다.
  root.current = uninitializedFiber;
  // HostRoot Fiber는 자신의 'stateNode' 속성으로 FiberRootNode를 가리켜, 서로 참조하게 됩니다.
  uninitializedFiber.stateNode = root;
  // ...
  return root;
}

이 두 객체가 생성되고 서로 연결되면, React는 렌더링할 준비를 마치게 됩니다.

3. 핵심 객체들의 관계 시각화하기

초기 마운트 과정에서 생성되는 주요 객체들의 관계를 클래스 다이어그램으로 살펴보면 구조를 더 명확하게 이해할 수 있습니다.

classDiagram
    class ReactDOMRoot {
        -_internalRoot: FiberRootNode
        +render(children) void
        +unmount() void
    }

    class FiberRootNode {
        +current: FiberNode
        +containerInfo: HTMLElement
        +pendingLanes: Lanes
        +...
    }

    class FiberNode {
        +tag: number
        +return: FiberNode | null
        +child: FiberNode | null
        +sibling: FiberNode | null
        +stateNode: any
        +...
    }

    ReactDOMRoot "1" *-- "1" FiberRootNode : _internalRoot
    FiberRootNode "1" o-- "1" FiberNode : current (HostRoot)
    FiberNode "1" --* "0..*" FiberNode : child/sibling/return

• 개발자가 받는 ReactDOMRoot 객체는 _internalRoot 속성을 통해 FiberRootNode를 소유합니다.

• FiberRootNode는 current 속성을 통해 현재 화면에 그려진 Fiber Tree의 최상단 FiberNode(즉, HostRoot)를 가리킵니다.

• 각 FiberNode는 child, sibling, return 포인터를 통해 트리 구조를 형성합니다.

4. 함수 호출의 흐름 살펴보기

createRoot 호출부터 root.render 직전까지, 각 모듈이 어떤 순서로 통신하는지 시퀀스 다이어그램으로 확인해 보겠습니다.

sequenceDiagram
    participant User as 사용자 코드
    participant DOM as react-dom
    participant Rec as react-reconciler

    User->>DOM: "createRoot(container)"
    activate DOM

    DOM->>Rec: "createContainer(container, ...)"
    activate Rec

    Rec->>Rec: "createFiberRoot(...)"
    activate Rec

    Note right of Rec: FiberRootNode 인스턴스화

    Rec->>Rec: "createHostRootFiber(...)"
    Note right of Rec: HostRoot FiberNode 생성

    Note right of Rec: 두 노드를 서로 연결

    Rec-->>Rec: "root"
    deactivate Rec

    Rec-->>DOM: "root"
    deactivate Rec

    DOM-->>User: "ReactDOMRoot 인스턴스"
    deactivate DOM

    User->>DOM: "root.render(<App />)"
    activate DOM

    Note right of DOM: updateContainer 호출,<br>본격적인 렌더링 파이프라인 시작

    DOM->>Rec: "updateContainer(<App />, root, ...)"
    deactivate DOM

createRoot 호출이 react-dom을 거쳐 react-reconciler에게 위임되고, 핵심 객체들이 생성된 후 다시 ReactDOMRoot 인스턴스로 포장되어 사용자에게 돌아오는 전 과정을 한눈에 볼 수 있습니다.

5. 요약 및 다음 단계

지금까지 React 19에서 애플리케이션이 렌더링을 시작하기 전, 즉 준비 단계를 살펴보았습니다.

1. 개발자가 createRoot를 호출합니다.

2. react-dom은 createContainer를 통해 react-reconciler에게 루트 생성을 요청합니다.

3. react-reconciler는 createFiberRoot를 통해 앱의 상태를 총괄할 FiberRootNode와 Fiber Tree의 시작점인 HostRoot FiberNode를 생성합니다.

4. 모든 준비를 마친 ReactDOMRoot 인스턴스가 반환됩니다.

이 모든 과정은 root.render(<App />)가 호출되는 순간, 본격적인 Render 단계와 Commit 단계를 통해 우리가 작성한 컴포넌트를 실제 DOM에 그려주기 위한 빌드업이었습니다.

다음 글에서는 render 함수 호출 이후, React가 어떻게 Fiber Tree를 구축하고 DOM을 업데이트하는지에 대해 더 깊이 알아보겠습니다.

이 글에서는 React의 복잡한 내부 세계를 서버 컴포넌트와 클라이언트 컴포넌트의 상호작용을 중심으로 살펴보고, 특히 클라이언트에서의 동적 업데이트가 일어나는 과정을 트리거(Trigger), 스케줄(Schedule), 렌더(Render), 커밋(Commit)이라는 네 가지 핵심 단계로 나누어 설명합니다. 복잡도를 조금이나마 낮춰보기 위해 다양한 다이어그램을 활용해서 이해를 도왔습니다.

React 내부, 어떻게 학습해야 할까?

React 내부 세계에 대해 설명하기 전에, React를 학습하는 방식에 대해 간단하게 정리해보고자 합니다. React의 코드베이스는 방대하고 복잡해서 어디서부터 시작해야 할지 막막할 수 있습니다. 바로 코드베이스를 보며 학습하기 보다 다음과 같은 효과적인 방식을 시도해보길 권장합니다.

1. 공식 문서 깊이 파기: React.dev 공식 문서(+블로그 포함)와 React Working Group 토론에는 React 핵심 팀의 철학과 의사결정 과정이 담겨있습니다. API 사용법을 넘어 그들의 생각을 읽는 것이 중요합니다.

2. React 팀 팔로우하기: React 팀원들의 소셜 미디어나 블로그를 팔로우하면 코드에는 드러나지 않는 귀중한 정보와 토론의 흐름을 파악할 수 있습니다. (트위터가 없어지며 팀원들이 다들 흩어져서 이 방식은 조금 어려워지긴 했습니다)

3. React 레포지토리 탐색하기: React GitHub 레포지토리의 코드뿐만 아니라, Pull Request(PR)와 코드 리뷰를 살펴보세요. 코드 주석(리액트 코드에는 설명용 주석이 많습니다)보다 더 상세한 구현 배경과 논의를 엿볼 수 있습니다.

4. 단순 블로그 글이 아닌 코드를 신뢰하기: 인터넷의 수많은 글은 개념적인 설명에 그치는 경우가 많습니다.(이 글 포함) 실제 소스 코드를 직접 디버깅하고 분석하는 것이 가장 정확하게 이해하는 방법입니다.

5. 핵심 경로(Critical Path)부터 찾기: 학습에 있어서 큰 덩어리로 시작하는건 효율적이지 않습니다. useState가 호출될 때부터 화면에 그려지기까지의 핵심적인 흐름을 먼저 파악한 뒤, 점진적으로 분할 정복을 하며 지식을 확장해 나가는 것이 효과적입니다.

React 패키지 구조 엿보기

React 패키지 내부를 들여다보면, 최신 React가 어떻게 구성되어 있는지 명확하게 알 수 있습니다.

• 서버와 클라이언트의 분리: react.react-server.js와 같은 파일들은 서버 환경 전용 빌드입니다. 반면, index.js 등은 클라이언트(브라우저) 환경을 위한 것입니다. 이는 React가 서버와 클라이언트에서 각기 다른 역할을 수행하도록 설계되었음을 보여줍니다.

• 클라이언트 렌더링 엔진: useState, useEffect와 같은 훅(Hook)과 4단계 업데이트 로직은 클라이언트용 빌드에 포함된 Reconciler와 Scheduler가 담당합니다.

• React 컴파일러 지원: compiler-runtime.js 파일은 React 컴파일러(코드명: Forget)를 위한 런타임 코드로, 빌드 시점 최적화를 지원합니다.

이처럼 실제 패키지 구조는 우리가 논의할 서버/클라이언트 모델과 최적화 전략이 실제 코드 레벨에서 구현되어 있음을 증명합니다.

React 업데이트는 누가, 어떻게 시작할까요?

React 업데이트는 개발자, 서버, 그리고 사용자라는 세 주체에 의해 시작됩니다. 각 주체는 애플리케이션 생명주기의 다른 시점에서 업데이트를 유발합니다.

1. 개발자 (Developer): 모든 것의 시작점입니다. 개발자는 컴포넌트 구조와 렌더링 로직을 코드로 작성합니다. 특히 전통적인 클라이언트 사이드 렌더링(CSR)에서는 개발자가 작성한 ReactDOM.createRoot().render() 코드가 직접적으로 애플리케이션의 첫 렌더링을 시작시킵니다.

2. 서버 (Server): React 서버 컴포넌트(RSC) 환경에서는, 사용자의 페이지 요청을 받은 서버가 개발자가 작성한 코드를 실행하여 초기 UI를 렌더링합니다. 이는 서버에 의해 시작되는 업데이트입니다.

3. 사용자 (User): 애플리케이션이 로드된 후, 사용자는 버튼 클릭이나 입력 같은 상호작용을 통해 클라이언트 컴포넌트의 상태를 변경합니다. 이는 후속 리렌더링을 유발(trigger)합니다.

이 관계는 아래 유즈케이스 다이어그램으로 명확히 표현할 수 있습니다.

flowchart TD
    subgraph "외부 액터(Actor)"
        DEV["👨‍💻 개발자"]
        SERVER["🌐 서버"]
        USER["👤 사용자"]
    end

    subgraph "React App 유즈케이스"
        UC1["초기 렌더링 시작<br/>(CSR: render() 호출)<br />(RSC: 페이지 요청)"]
        UC2["상태 변경에 의한<br/>리렌더링 (클라이언트)"]
        UC3["컴포넌트 트리<br/>렌더링/업데이트"]
        UC4["DOM 업데이트"]
        UC5["Effect 실행<br/>(useEffect, useLayoutEffect)"]
    end

    DEV -- "코드 작성 및 render() 호출" --> UC1
    SERVER -- "RSC 요청 처리" --> UC1
    USER -- "UI 상호작용" --> UC2

    UC1 -.->|include| UC3
    UC2 -.->|include| UC3
    UC3 -.->|include| UC4
    UC4 -.->|include| UC5

    style DEV fill:#e1f5fe
    style SERVER fill:#d1c4e9
    style USER fill:#f3e5f5
    style UC1 fill:#fff3e0
    style UC2 fill:#fff3e0
    style UC3 fill:#e8f5e8
    style UC4 fill:#e8f5e8
    style UC5 fill:#e8f5e8

클라이언트 업데이트의 4단계 동작 원리

'use client'로 명시된 클라이언트 컴포넌트에서 발생하는 모든 업데이트는 아래 플로우차트에 나타난 트리거 → 스케줄 → 렌더 → 커밋의 4단계 과정을 거칩니다. 이 흐름은 React가 UI를 업데이트하는 핵심 로직입니다.

graph TD
    subgraph "Trigger"
        A["시작: 초기 렌더링 또는<br/>상태 변경(setState) 호출"] --> B["업데이트 작업 생성<br/>(scheduleUpdateOnFiber)"];
    end

    B --> C["스케줄러에 작업 전달<br/>(scheduleCallback)"];

    subgraph "Schedule"
        C --> D["작업 우선순위 지정 및<br/>대기열 추가"];
        D --> E["스케줄러가 작업 실행<br/>(workLoop)"];
    end

    subgraph "Render"
        E --> F["렌더 단계 시작<br/>(performConcurrentWorkOnRoot)"];
        F --> G["컴포넌트 함수 호출<br/>새 파이버 트리 생성"];
        G --> H["상태 값 비교 (Bailout)<br/>& 기존 트리와 비교 (Diffing)"];
        H --> I{"변경 사항 있음?"};
    end

    I -- "No" --> J["작업 종료<br/>(렌더링 생략)"];

    subgraph "Commit"
        I -- "Yes" --> K["커밋 단계 시작<br/>(commitRoot)"];
        K --> L["DOM 변경 사항 적용<br/>(commitMutationEffects)"];
        L --> M["useLayoutEffect 실행"];
        M --> N["브라우저 렌더링"];
        N --> O["useEffect 실행<br/>(flushPassiveEffects)"];
    end

    O --> P["작업 종료"];

    style Trigger fill:#f9f,stroke:#333,stroke-width:2px
    style Schedule fill:#ccf,stroke:#333,stroke-width:2px
    style Render fill:#cfc,stroke:#333,stroke-width:2px
    style Commit fill:#fca,stroke:#333,stroke-width:2px
    style J fill:#eee,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5
    style P fill:#eee,stroke:#333,stroke-width:2px

1. Trigger (트리거)

render()나 setState() 같은 이벤트가 발생하면, React는 어떤 컴포넌트를 다시 렌더링해야 할지 결정하고 업데이트 작업을 생성합니다.

2. Schedule (스케줄)

생성된 업데이트 작업의 우선순위를 정하고, 내부 스케줄러를 통해 언제 실행할지 결정합니다. 긴급한 업데이트는 먼저 처리(우선순위는 lane에 정의 되있습니다)하여 사용자 경험을 최적화합니다.

3. Render (렌더)

스케줄링된 컴포넌트를 실제로 렌더링하여 새로운 파이버 트리(Fiber Tree)를 구성하고, 기존 트리와 비교하여 변경 사항(diff)을 계산합니다. 이 단계는 실제 DOM을 건드리지 않으며, 더 급한 작업이 들어오면 중단될 수 있습니다.

4. Commit (커밋)

렌더 단계에서 계산된 변경 사항을 실제 DOM에 적용하는 마지막 단계입니다. 이 단계는 중단되지 않으며, DOM 업데이트 후 useLayoutEffect, 그리고 브라우저 페인팅 이후 useEffect를 순차적으로 실행합니다.

모듈 간의 상호작용

React 컴포넌트의 상호작용은 그것이 실행되는 환경(서버 또는 클라이언트)에 따라 크게 달라집니다.

1) 클라이언트 컴포넌트의 업데이트 상호작용

클라이언트 컴포넌트는 사용자의 상호작용(예: 버튼 클릭)에 의해 업데이트됩니다. 이 과정은 이전에 설명한 4단계(트리거 → 스케줄 → 렌더 → 커밋) 모델을 따르며, 최종적으로 실제 DOM을 변경하여 사용자에게 변경된 UI를 보여줍니다.

sequenceDiagram
    actor User
    participant Component
    participant ReactHooks as React Hooks<br/>(useState)
    participant Scheduler
    participant Reconciler as Reconciler<br/>(Render/Commit)
    participant DOM

    User->>+Component: 1. 버튼 클릭
    Component->>+ReactHooks: 2. setState() 호출
    ReactHooks->>+Reconciler: 3. 업데이트 예약<br/>(scheduleUpdateOnFiber)
    Reconciler->>+Scheduler: 4. 작업 스케줄링 요청<br/>(scheduleCallback)
    Scheduler-->>-Reconciler: 5. 렌더링 작업 시작<br/>(performConcurrentWorkOnRoot)
    loop 렌더(Render) 단계
        Reconciler->>Component: 6. 컴포넌트 함수 재호출
        Component-->>Reconciler: 7. 새로운 JSX 반환
    end
    Reconciler->>Reconciler: 8. 변경사항 계산 (Diffing)
    Reconciler->>+DOM: 9. DOM 업데이트 (Commit)
    Reconciler->>Component: 10. useEffect 실행
    DOM-->>-User: 11. 변경된 UI 표시

2) 서버 컴포넌트의 초기 렌더링 상호작용

서버 컴포넌트는 사용자의 최초 페이지 요청이나 내비게이션 요청에 의해 렌더링됩니다. 주된 목적은 데이터를 가져와 UI 구조를 생성하고, 이를 클라이언트로 스트리밍할 수 있는 특별한 형식(RSC Payload)으로 직렬화하는 것입니다.

sequenceDiagram
    participant Browser
    participant FrameworkServer as Framework Server <br />(e.g., Next.js)
    participant ReactServer
    participant Reconciler

    Browser->>+FrameworkServer: 1. 페이지 요청 (GET /)
    FrameworkServer->>+ReactServer: 2. 렌더링 요청
    ReactServer->>+Reconciler: 3. 서버 렌더링 시작
    loop Render on Server
        Reconciler->>Reconciler: 4. 서버 컴포넌트 실행 (DB/API 접근)
        Reconciler->>Reconciler: 5. 클라이언트 컴포넌트는 자리표시자로 처리
    end
    Reconciler-->>-ReactServer: 6. RSC 페이로드 생성
    ReactServer-->>-FrameworkServer: 7. 페이로드 스트림 반환
    FrameworkServer-->>-Browser: 8. UI 스트리밍 응답

이 과정은 사용자와의 상호작용이 없으며, 최종 결과물은 DOM 변경이 아닌 직렬화된 데이터입니다.

React를 구성하는 핵심 모듈들

이 모든 마법은 React 내부의 핵심 모듈들이 유기적으로 협력하기에 가능합니다. 각 모듈의 역할과 관계를 모듈 클래스 다이어그램으로 확인 해보겠습니다.

classDiagram
    direction LR
    class ReactDOMClient {
        +createRoot(container)
        +render(component)
    }
    class ReactCore {
        <<Hooks>>
        +useState()
        +useEffect()
        +useContext()
    }
    class Scheduler {
        -PriorityQueue tasks
        +scheduleCallback(callback, priority)
        -workLoop()
    }
    class Reconciler {
        <<Fiber>>
        +scheduleUpdateOnFiber()
        -performConcurrentWorkOnRoot()
        -commitRoot()
    }
    class ReactServer {
         - Renders Server Components
    }
    class DOM {
        <<Host Environment>>
        +createElement()
        +appendChild()
    }

    ReactDOMClient ..> Reconciler : 렌더링 시작 (클라이언트)
    ReactCore ..> Reconciler : 업데이트 요청 (클라이언트)
    Reconciler ..> Scheduler : 작업 스케줄링 (클라이언트)
    Reconciler ..> DOM : DOM 조작 (클라이언트)
    ReactServer ..> Reconciler : 초기 렌더링 (서버)

• ReactDOMClient: render()를 통해 React 세계를 시작하는 진입점입니다.

• ReactCore: useState, useEffect 등 우리가 사용하는 훅을 제공합니다.

• Scheduler: 클라이언트 측 업데이트 작업의 우선순위를 관리하고 실행 시점을 조율합니다.

• Reconciler: 파이버(Fiber) 아키텍처를 기반으로 작동하는 React의 핵심 엔진입니다. 서버에서는 초기 렌더링을, 클라이언트에서는 변경 사항을 계산(Render)하고 DOM에 적용(Commit)하는 역할을 모두 수행합니다.

• ReactServer: 서버 환경에서 서버 컴포넌트를 렌더링하는 추상적인 주체입니다. 내부적으로 Reconciler를 사용하지만, Scheduler나 DOM 조작 로직은 사용하지 않습니다.

정리하며

최신 React는 개발자가 작성한 코드를 기반으로, 서버와 클라이언트가 각자의 역할을 수행하는 하이브리드 모델을 구현합니다.

서버는 react.react-server.js 빌드를 사용해 초기 로딩과 데이터 페칭을 최적화하고, 클라이언트는 index.js 빌드를 통해 트리거 → 스케줄 → 렌더 → 커밋 과정을 거쳐 사용자와의 동적 상호작용을 처리합니다. 여기에 React 컴파일러가 더해져 렌더링 과정을 더욱 최적화합니다.

이 통합적인 동작 원리를 실제 패키지 구조와 연결하여 이해하면, 복잡한 애플리케이션의 성능을 어떻게 최적화할 수 있는지에 대한 깊이 있는 통찰력을 얻을 수 있습니다.

오늘은 이 "조용한 버그"의 원인을 파헤치고 해결하는 과정을 공유해보겠습니다. 특히 shadcn/ui와 같은 헤드리스(Headless) UI 라이브러리를 사용하신다면 좀 더 흥미롭게 읽으실 수 있으실겁니다.

현상: console.log는 찍히는데, 페이지 이동은 안 된다?

상황은 단순했습니다. 사용자가 드롭다운 메뉴에서 '로그아웃' 버튼을 클릭하면 로그아웃 페이지로 이동시키는 기능이었습니다. 코드는 다음과 같았습니다.

// Profile.tsx
import { useNavigate } from 'react-router-dom';
import { DropdownMenuItem } from '@/components/ui/DropdownMenu';

// ...

const navigate = useNavigate();

const handleLogout = () => {
  console.log("로그아웃 시도");
  navigate("/logout"); // 페이지 이동 실행
  console.log("navigate 함수 호출됨");
};

// ...

<DropdownMenuItem onSelect={handleLogout}>
  로그아웃
</DropdownMenuItem>

간단하고 명백해 보이는 코드였습니다. 하지만 실제 동작은 우리를 미궁에 빠뜨렸습니다. '로그아웃' 버튼을 클릭하면 브라우저 콘솔에는 "로그아웃 시도", "navigate 함수 호출됨"이 모두 찍혔지만, 정작 URL은 바뀌지 않고 페이지는 미동도 하지 않았습니다. react-router에 설정해 둔 라우트 로더(loader)도 전혀 호출되지 않았죠. 마치 navigate 함수가 유령처럼 실행만 되고 사라지는 것처럼 느껴졌습니다.

1차 삽질: useNavigate의 잘못된 사용?

처음에는 react-router-dom의 버전업에 따른 사용법 변경을 의심했습니다. 혹시 replace 함수를 직접 import해서 써야 하나? 아니면 Link 컴포넌트만 써야 하나? 여러 가설을 세우고 시도했지만 모두 실패였습니다. 코드는 useNavigate의 표준적인 사용법을 정확히 따르고 있었습니다.

2차 삽질: useEffect와의 충돌?

다음 가설은 "상태 변경과의 충돌"이었습니다. 혹시 navigate가 호출된 직후 다른 상태(state)가 변경되면서 컴포넌트가 리렌더링되고, 이 때문에 페이지 이동이 중단되는 것은 아닐까?

이 가설은 상당히 그럴듯했습니다. 실제로 navigate와 상태 변경 함수를 동시에 호출하면 종종 이런 문제가 발생하거든요. 그래서 setTimeout으로 navigate 호출을 살짝 지연시켜 리렌더링이 끝난 후에 실행되도록 하는 꼼수를 써봤습니다.

// 임시 해결책 (하지만 좋은 방법은 아닙니다!)
const handleLogout = () => {
  setTimeout(() => navigate("/logout"), 50);
};

놀랍게도, 이 방법은 통했습니다! 페이지가 드디어 이동하기 시작했습니다. 하지만 이건 근본적인 해결책아니고 결국 Hack에 불과했습니다. 왜 이런 일이 발생하는지 정확한 원인을 알고 싶었습니다.

진짜 원인: UI 컴포넌트의 "기본 동작"과의 경합 조건 (Race Condition)

문제의 핵심은 DropdownMenuItem 컴포넌트의 내부 동작에 있었습니다.

shadcn/ui의 DropdownMenu는 내부적으로 Radix UI를 사용합니다. 이 라이브러리의 DropdownMenuItem은 onSelect 이벤트가 발생하면 (즉, 사용자가 메뉴를 클릭하면) 두 가지 일을 하도록 설계되어 있습니다.

1. 우리가 onSelect에 전달한 함수(handleLogout)를 실행한다.

2. 메뉴를 닫는 "기본 동작"을 실행한다. (내부적으로 open 상태를 false로 바꾼다.)

이 두 가지 동작이 거의 동시에 실행되면서 "경합 조건(Race Condition)"이 발생한 것입니다.

1. handleLogout이 호출되고, navigate 함수가 페이지 이동 프로세스를 "시작" 합니다.

2. 하지만 페이지 이동이 완료되기 전에, DropdownMenu가 닫히면서 내부 상태가 변경되고, 이로 인해 Profile 컴포넌트가 리렌더링됩니다.

3. 이 갑작스러운 리렌더링이, 이제 막 출발하려던 페이지 이동 프로세스를 "취소" 시켜버린 것입니다.

이것이 바로 콘솔은 찍히지만 페이지 이동은 안 되는, 유령 버그의 정체였습니다.

최종 해결책: 라이브러리가 의도한 방법, asChild

setTimeout 같은 임시방편 대신, 라이브러리가 이런 경우를 위해 마련해 둔 우아한 해결책이 있었습니다. 바로 asChild 속성입니다.

// 최종 해결책
import { Link } from 'react-router-dom';
import { DropdownMenuItem } from '@/components/ui/DropdownMenu';

// ...

<DropdownMenuItem asChild>
  <Link to="/logout" replace>
    로그아웃
  </Link>
</DropdownMenuItem>

asChild 속성은 DropdownMenuItem에게 "너 자신을 렌더링하지 말고, 네 자식 컴포넌트(Link)에게 너의 모든 스타일과 동작을 물려줘"라고 지시합니다.

그 결과, 우리는 react-router-dom의 Link 컴포넌트를 사용하지만, 겉보기에는 완벽한 DropdownMenuItem처럼 보이는 컴포넌트를 얻게 됩니다.

이 방법이 왜 완벽한 해결책일까요?

• 진짜 링크(<a> 태그)로 동작: 이제 메뉴 아이템은 단순한 버튼이 아니라, 페이지 이동을 위한 시맨틱한 링크가 됩니다. 브라우저는 링크 클릭 시 페이지 이동을 다른 UI 상태 변경보다 우선시하므로 충돌 자체가 발생하지 않습니다.

• 불필요한 핸들러 제거: 더 이상 navigate나 handleLogout 함수가 필요 없어 코드가 훨씬 간결해집니다.

• replace 속성 활용: Link 컴포넌트의 replace 속성을 사용하면, 로그아웃 페이지가 브라우저 히스토리에 쌓이지 않게 하여 뒤로가기 문제를 깔끔하게 방지할 수 있습니다.

마무리 회고

이번 삽질을 통해 몇 가지 중요한 교훈을 얻었습니다.

1. navigate가 동작하지 않으면, 리렌더링과의 충돌을 가장 먼저 의심하라. 특히 인터랙티브한 UI 컴포넌트 내부에서 navigate를 호출할 때는 더욱 그렇습니다.

2. 사용하는 라이브러리의 문서를 다시 한번 살펴보자. setTimeout 같은 꼼수가 통하더라도, 분명 더 우아하고 안정적인 "공식적인" 해결책이 존재할 가능성이 높습니다. asChild가 바로 그런 케이스였습니다.

3. Headless UI 라이브러리는 편리하지만, 내부 동작 원리를 이해하는 것이 중요하다. 내부적으로 어떤 상태를 관리하고, 어떤 기본 동작이 실행되는지 알면 이런 디버깅 시간을 크게 줄일 수 있습니다.

혹시 저와 비슷한 문제를 겪고 계신 분이 있다면, 이 글이 문제 해결의 실마리가 되기를 바랍니다. 읽어주셔서 감사합니다.

React Query v5(TanStack Query)의 내부 구조와 동작 원리를 심층 분석하여, 더 효율적인 서버 상태 관리를 위한 인사이트를 제공합니다.

들어가며

React Query는 비동기 상태 관리 라이브러리로서 리액트 개발에서 서버 상태 관리의 사실상 표준처럼 사용되고 있습니다. 하지만 useQuery()를 사용하다 보면 내부에서 어떤 마법이 일어나는지 궁금해집니다. 김정환님의 블로그를 참고하여 React Query의 내부 동작을 체계적으로 분석해봤습니다.

아키텍처 개요

React Query는 크게 두 개의 패키지로 구성됩니다

구조를 시각적으로 나타내 보겠습니다.

graph TB
    subgraph "react-query 패키지"
        A1[useQuery]
        A2[useInfiniteQuery]
        A3[useQueries]
        A4[useBaseQuery]
        A1 --> A4
        A2 --> A4
        A3 --> A4
    end

    subgraph "query-core 패키지"
        B1[QueryObserver]
        B2[Query]
        B3[QueryCache]
        B4[QueryClient]
        B5[notifyManager]

        B1 -.->|구독| B2
        B2 -.->|저장| B3
        B4 -.->|보유| B3
        B1 -.->|알림| B5
    end

    subgraph "브라우저 이벤트"
        C1[focusManager]
        C2[onlineManager]
    end

    A4 -.->|생성| B1
    A4 -.->|useSyncExternalStore| B1
    B4 -.->|구독| C1
    B4 -.->|구독| C2
    C1 -.->|포커스 이벤트| B3
    C2 -.->|온라인 이벤트| B3

핵심 구성 요소 분석

1. useQuery() 훅의 역할

// useQuery의 핵심 구조
function useQuery(options, queryClient) {
  return useBaseQuery(options, QueryObserver, queryClient)
}

2. 전체 데이터 흐름 과정

React Query의 전체 동작 흐름을 한눈 보기

graph TD
    A["컴포넌트에서 useQuery() 호출"]
    B["useBaseQuery 실행"]
    D["QueryObserver 생성"]
    E["useSyncExternalStore로<br>컴포넌트와 상태 동기화"]
    F["QueryCache에서 Query 조회/생성"]
    G{"Query 존재?"}
    H["새 Query 인스턴스 생성"]
    I["기존 Query 사용"]
    I2{"데이터가 Stale?"}
    I3["캐시 데이터로 즉시 렌더링"]
    J["Query.fetch() 실행"]
    K["네트워크 요청"]
    L{"요청 결과"}
    M["Query 상태 업데이트<br/>(data, error 등)"]
    N["Query 에러 상태 업데이트"]
    O["QueryObserver에 변경 알림"]
    P["notifyManager가 알림을 batch 처리"]
    T["컴포넌트 리렌더링"]

    A --> B
    B --> D
    D --> F
    D --> E
    F --> G
    G -- "없음" --> H
    G -- "있음" --> I
    I --> I2
    I2 -- "Yes (Stale)" --> J
    I2 -- "No (Fresh)" --> I3
    H --> J
    J --> K
    K --> L
    L -- "성공" --> M
    L -- "실패" --> N
    M --> O
    N --> O
    O --> P
    P --> E
    E --> T
    I3 --> T

    classDef user fill:#c9d1d9,stroke:#333,stroke-width:1px
    classDef react fill:#61dafb,stroke:#333,stroke-width:2px,color:#000
    classDef core fill:#ff6b6b,stroke:#333,stroke-width:2px,color:#fff
    classDef result fill:#4ecdc4,stroke:#333,stroke-width:2px,color:#000

    class A user
    class B,D,E react
    class F,G,H,I,I2,J,K,L,M,N,O,P core
    class T,I3 result

3. useBaseQuery()의 핵심 역할

4. 시퀀스 다이어그램으로 전체 데이터 흐름 다시보기

컴포넌트부터 네트워크 요청까지의 상세한 상호작용 흐름을 확인해보겠습니다.

sequenceDiagram
    participant Component as 🎯 컴포넌트
    participant useQuery as 🪝 useQuery
    participant Observer as 👁️ QueryObserver
    participant Cache as 💾 QueryCache
    participant Query as 📡 Query
    participant Network as 🌐 네트워크
    participant NotifyMgr as ⚡ notifyManager

    Component->>useQuery: useQuery(options) 호출
    useQuery->>Observer: QueryObserver 생성
    Observer->>Cache: Query 조회/생성 요청

    alt Query가 없는 경우
        Cache->>Query: 새 Query 인스턴스 생성
    else Query가 있는 경우
        Cache->>Query: 기존 Query 반환
    end

    Observer->>Query: 구독 시작
    Query->>Network: fetch 요청 실행
    Network-->>Query: 응답 데이터

    Query->>Observer: 상태 변경 알림
    Observer->>NotifyMgr: batchCalls로 알림
    NotifyMgr->>NotifyMgr: 배치 처리
    NotifyMgr-->>Component: 리렌더링 트리거

    Note over Component: 최신 데이터로 UI 업데이트

5. QueryObserver - 리렌더링의 핵심

QueryObserver는 Query와 React 컴포넌트 사이의 가교 역할을 합니다.

6. Query - 서버 상태의 단위

Query의 생명주기

7. QueryCache - 중앙 저장소

8. QueryClient - 전역 API 제공자

QueryClient는 명령형 API를 통해 쿼리를 제어할 수 있게 해줍니다.

개인적으로 QueryClient가 선언형으로 다룰 수 있게되면 좋겠다는 소박한 희망이 있습니다.

데이터 조작 API

프리페칭 API

성능 최적화: notifyManager

React Query의 성능 최적화 핵심은 notifyManager입니다.

배치 처리 메커니즘

렌더링 최적화의 효과

호출이 많을수록 최적화의 효과가 두드러집니다.

구성 요소별 역할 요약

전체 구조를 마인드맵으로 정리해보겠습니다.

mindmap
  root((React Query))
    [useQuery]
      useBaseQuery
        QueryObserver 생성
        useSyncExternalStore 구독
    [QueryObserver]
      Query 구독
      상태 파생 및 전달
      1:N 구독 관계
    [Query]
      서버 상태 단위
      fetchFn 트리거
      결과 전파
    [QueryCache]
      Query 중앙 저장소
      쿼리 키로 접근
      생명주기 관리
    [QueryClient]
      전역 API 제공
      QueryCache 보유
      명령형 인터페이스
    [notifyManager]
      배치 처리
      성능 최적화
      렌더링 제어

데이터 흐름 단계별 정리

간단한 표를 활용하여 전체 데이터 흐름을 단계별로 정리해보겠습니다.

성능 모니터링

React Query의 성능을 모니터링할 수 있는 지표

결론

React Query의 내부 동작을 이해하면 다음과 같은 이점을 얻을 수 있습니다

핵심 포인트:

• QueryObserver가 Query와 컴포넌트를 연결하는 핵심 가교 역할

• notifyManager의 배치 처리로 렌더링 성능 최적화

• QueryCache를 통한 효율적인 중앙 집중식 상태 관리

• 명령형 API로 컴포넌트 외부에서도 쿼리 제어 가능

React Query는 데이터 페칭에 많이 쓰이지만 사실 정교하게 설계된 비동기 상태 관리 시스템입니다. 이러한 내부 구조를 이해하고 활용한다면, 더욱 효율적이고 안정적인 React 애플리케이션을 개발할 수 있습니다.

참고: 리액트 쿼리, 내부는 이렇게 움직인다 - 김정환 블로그

시작: 단순해 보였던 405 에러

QA 환경에서 다음과 같은 API 호출이 실패하고 있었습니다:

POST https://qa.leadershipcube.ai/api/assessment/v1/login
→ 405 Method Not Allowed

첫 번째 가설은 "백엔드 서버가 POST 메서드를 지원하지 않나?"였습니다. 하지만 곧 더 깊은 문제가 숨어있다는 것을 깨달았습니다.

🔍 디버깅의 시작: curl로 추적하기

문제를 정확히 파악하기 위해 curl을 사용해 백엔드 서버에 직접 요청을 보내봤습니다:

# 백엔드 서버 직접 호출
curl -X POST https://gw.qa.hunet.io/assessment/v1/login \
  -H "Content-Type: application/json" \
  -H "x-hunet-franchise-type: 271" \
  -d '{"email": "test@example.com", "employeeCode": "Test"}'

결과: 200 OK ✅

이상했습니다. 백엔드는 정상적으로 동작하는데, 프록시를 거치면 왜 405 에러가 나는지 알 수 없었죠.

첫 번째 발견: Host 헤더 문제

Nginx 프록시 설정을 자세히 살펴보니 문제를 발견했습니다:

# 기존 설정
location ~ ^/api/assessment {
  rewrite ^/api/assessment(.*) /assessment$1 break;
  proxy_pass https://api_backend;
  proxy_set_header Host $host;  # 여기가 문제!
}

proxy_set_header Host $host; 설정 때문에 Nginx가 브라우저의 원래 Host 헤더(qa.xxx.ai)를 백엔드로 그대로 전달하고 있었습니다.

하지만 백엔드 서버는 자신의 주소(gw.qa.xxx.io)가 Host 헤더에 있어야만 요청을 처리하도록 설정되어 있었습니다.

해결책 1: 올바른 Host 헤더 설정

location /api/assessment/ {
  proxy_pass https://api_backend/assessment/;
  proxy_set_header Host gw.qa.xxx.io;  # 백엔드가 기대하는 Host로 명시
}

두 번째 문제: 301 리다이렉션 지옥

Host 헤더 문제를 해결하고 나니, 이번에는 /api/auth 엔드포인트에서 다른 문제가 발생했습니다:

PUT https://qa.xxx.ai/api/auth
→ 301 Moved Permanently
→ Location: https://qa.xxx.ai/api/auth/

원인: 슬래시(/) 불일치

# 문제가 되는 설정
location /api/auth/ {  # 슬래시로 끝남
  proxy_pass ...;
}

클라이언트는 /api/auth (슬래시 없음)으로 요청했는데, Nginx 설정은 /api/auth/ (슬래시 있음)로 되어 있어 Nginx가 "친절하게" 리다이렉션을 보낸 것이었습니다.

해결책 2: 정규식으로 유연하게 처리

# 시도 1: 정규식 사용
location ~ ^/api/auth/?$ {
  proxy_pass https://api_backend/auth/;
}

# 시도 2: rewrite 사용
location /api/auth {
  rewrite ^/api/auth(.*)$ /auth$1 break;
  proxy_pass https://api_backend;
}

로컬 테스트 환경 구축

매번 QA 서버에 배포해서 테스트하는 것은 비효율적이었습니다. Mac북에서 사용할 수 있는 도커 cli 중에 podman을 사용해 로컬 테스트 환경을 구축했습니다.

podman run --rm -d --name local-nginx-test \
  -p 8080:80 \
  -v ./build/qa/default.conf:/etc/nginx/conf.d/default.conf:ro \
  -v ./public:/usr/share/nginx/html:ro \
  docker.io/nginx:latest

예상치 못한 문제들

로컬 환경에서 여러 예상치 못한 문제들을 만났습니다:

1. DNS resolver 충돌: 로컬 컨테이너가 사설 DNS 서버에 접근하지 못해 발생

2. Nginx 설정 문법 오류: set 지시어를 잘못된 위치에 사용

3. Podman 네트워킹 문제: 포트 포워딩이 예상대로 동작하지 않음

각각을 하나씩 해결해 나가면서, 로컬에서 실제 QA 환경과 동일한 동작을 재현할 수 있게 되었습니다.

마지막 발견: HTTP 메서드 문제

모든 설정을 올바르게 고쳤는데도 여전히 405 에러가 발생했습니다. 마지막에 알고 보니

# 실패하는 요청
curl -X POST /api/auth ...
→ 405 Method Not Allowed

# 성공하는 요청  
curl -X PUT /api/auth ...
→ 200 OK ✅

토큰 갱신 API는 POST가 아니라 PUT 메서드를 사용해야 했습니다. 실수도 연속해서 저지르다보면 인지도 못하는 쉬운 실수가 생기더라구요.

최종 해결책: 단순함의 승리

모든 문제를 해결한 후, 복잡했던 설정을 더 간단하고 명확하게 리팩토링했습니다:

# 최종 설정 - 간단하고 명확함
server {
  set $backend_host "gw.qa.xxx.io";

  location /api/assessment/ {
    proxy_pass https://api_backend/assessment/;
    proxy_set_header Host $backend_host;
    # ... 기타 헤더들
  }

  location /api/auth {
    proxy_pass https://api_backend/auth;
    proxy_set_header Host $backend_host;
    # ... 기타 헤더들
  }
}

배운 점들

1. 체계적인 디버깅의 중요성

• 가설 세우기: 각 단계에서 명확한 가설을 세우고 검증

• 격리된 테스트: curl을 사용해 Nginx를 우회한 직접 테스트

• 로컬 재현: 로컬 환경에서 문제를 재현해 빠른 반복 테스트

2. Nginx의 미묘한 동작들

• Host 헤더의 중요성: 가상 호스팅 환경에서 Host 헤더가 라우팅에 미치는 영향

• 경로 매칭의 복잡성: 슬래시 유무에 따른 리다이렉션 동작

• upstream vs 변수: proxy_pass에서 upstream과 변수 사용의 차이점

3. 도구의 활용

• curl: API 테스트의 강력한 도구

• Podman/Docker: 로컬 테스트 환경 구축

• 로그 분석: 에러 메시지에서 단서 찾기

결론

겉보기에 단순해 보였던 405 에러 하나가 Host 헤더, 경로 매칭, HTTP 메서드, DNS 설정 등 여러 복잡한 요소들이 얽힌 문제였습니다.

이 과정을 통해 Nginx 프록시의 동작 원리를 이전보다 깊이 이해하게 되었고, 무엇보다 체계적인 디버깅과 로컬 테스트 환경의 중요성을 다시 한번 깨달았습니다.

가끔 복잡한 해결책보다는 단순하고 명확한 설정이 더 나은 선택일 수 있다는 것도 좋은 교훈이었습니다.

모든 API 요청에 액세스 토큰을 자동으로 주입하고, 토큰이 만료되면 알아서 갱신 후 재요청까지 해주는 로직. 저 역시 이 기능을 구현하여 사용자 경험을 향상시키고자 했습니다.

하지만 이 편리함을 구현하는 과정은 간단하지 않았습니다. 특히 "이 토큰 갱신 코드를 어디에 위치시키고 어떻게 관리할 것인가?" 라는 근본적인 설계 문제와 마주했고, 이는 결국 "API 무한 재요청" 이라는 치명적인 버그로 이어졌습니다. 이 글은 그 문제를 해결하며 얻은 경험에 대한 기록입니다.

문제의 발단: 재사용성과 관심사의 분리

토큰 갱신 로직을 구현할 때, 가장 먼저 고민한 것은 "코드의 위치"였습니다.

• 선택지 1: 각 컴포넌트에서 개별 처리? API를 호출하는 모든 컴포넌트나 커스텀 훅에서 try-catch로 401 에러를 잡고, 직접 갱신 함수를 호출하는 방식입니다. 다만 수십, 수백 개의 API 호출 지점에서 코드가 중복되고, 로직 변경 시 모든 파일을 수정해야 하는 유지보수 지옥이 펼쳐질 가능성이 높아 보였습니다.

• 선택지 2: API 헬퍼에서 중앙 처리? 모든 API 통신이 거쳐 가는 api.helper.ts에 로직을 집중시키는 것이 정답이라고 생각했습니다. ky 라이브러리의 hooks를 사용하면, 모든 요청과 응답을 한 곳에서 가로챌 수 있어 '관심사의 분리' 원칙에도 부합했습니다.

저는 2번을 선택했고, afterResponse 훅을 이용해 401 에러 시 토큰을 갱신하고 원래 요청을 재시도하는 코드를 작성했습니다.

치명적인 실수: 무한 재요청의 덫

중앙 처리 방식은 우아해 보였지만, 저는 한 가지 간과한 사실이 있었습니다. 바로 "토큰을 갱신하는 API 요청(authService.refresh()) 또한 내가 만든 중앙 처리 로직을 통과한다" 는 점이었습니다.

이로 인해 다음과 같은 무한 루프 시나리오가 발생했습니다.

1. Request A: 일반 API를 호출했으나, 액세스 토큰이 만료되어 401 Unauthorized 응답을 받습니다.

2. afterResponse 훅 발동: 401 에러를 감지하고, 토큰을 갱신하기 위해 authService.refresh()를 호출합니다.

3. Request B: authService.refresh()가 토큰 갱신 API(PUT /api/auth)를 호출합니다. 하지만 사용자의 리프레시 토큰마저 만료된 상태였습니다.

4. afterResponse 훅 또 발동: PUT /api/auth 요청 또한 401 응답을 받습니다. 이 응답 역시 중앙 처리 로직에 의해 감지되고, 또다시 토큰을 갱신하기 위해 authService.refresh()를 호출합니다.

5. 무한 루프: 3번과 4번 과정이 무한히 반복되며, 브라우저의 네트워크 탭은 순식간에 수많은 실패 요청으로 가득 찼습니다.

중앙 처리 로직이 자기 자신을 처리하려 들면서 생긴 문제였습니다. 이 문제를 해결할 '탈출구'가 필요했습니다.

해결의 실마리: 독립적인 통신 채널

해결책은 의외로 간단했습니다. 토큰 갱신을 위한 API 요청은 "어떠한 훅도 거치지 않는 순수한 통신 채널" 로 보내야 한다는 것이었습니다.

// src/lib/api.helper.ts

// 1. 모든 요청을 가로채는 메인 API 인스턴스
export const api = ky.create({
  hooks: {
    // 여기에 afterResponse 등 토큰 갱신 로직이 들어감
  }
});

// 2. 토큰 갱신만을 위한 '순수한' API 인스턴스
export const refreshApi = ky.create({
  // 훅 없음
});

api.helper.ts에 훅이 없는 새로운 ky 인스턴스(refreshApi)를 만들었습니다. 그리고 authService.refresh() 함수는 이제 api가 아닌 refreshApi를 사용하도록 수정했습니다.

// src/services/auth.service.ts

const refresh = async () => {
  // refreshApi를 사용함으로써 무한 루프의 고리를 끊음
  const accessToken = await refreshApi.put(...).text();
  return accessToken;
};

이제 토큰 갱신 요청은 afterResponse 훅의 영향을 받지 않으므로, 갱신이 실패하면 그냥 에러를 반환하고 무한 루프 없이 깔끔하게 상황이 종료됩니다.

이번 프로젝트를 통해 얻은 진짜 교훈

• 중앙화된 '마법'은 '탈출구'를 필요로 한다: 인터셉터나 훅처럼 보이지 않는 곳에서 동작하는 로직은 매우 편리하지만, 그 '마법'이 자기 자신에게도 적용될 때의 부작용을 반드시 고려해야 합니다. 모든 규칙에는 예외가 필요하듯, 중앙 처리 로직에는 그 로직을 우회할 수 있는 독립적인 통로를 마련해두는 설계가 중요합니다.

• 문제의 원인은 아키텍처에 있다: "API 요청이 무한히 나간다"는 현상만 보면 당황하기 쉽습니다. 하지만 근본 원인은 코드 한 줄이 아니라, "모든 통신은 단일 인스턴스를 통한다"고 설정한 아키텍처의 허점에 있었습니다. 버그를 잡을 때는 현상 너머의 구조를 보는 시각이 필요하다는 것을 절실히 느꼈습니다.

마치며

'토큰 자동 갱신'이라는 비교적 흔한 기능을 구현하면서, 저는 아키텍처 설계의 중요성과 부작용에 대해 경험하며 배울 수 있었습니다. 단순히 기능을 완성하는 것을 넘어, 발생할 수 있는 모든 엣지 케이스를 고려하고 시스템 전체의 안정성을 확보하는 것이 얼마나 중요한지 체감할 수 있었습니다.