필자는 프론트엔드 개발을 하면서 "도메인"이라는 단어를 꽤 자주 접해왔다. 코드 리뷰에서 "이건 도메인 로직이니까 컴포넌트 밖으로 빼세요", 아키텍처 논의에서 "도메인 모델을 먼저 정의합시다" 같은 말들이 오간다. 그런데 막상 "도메인이 정확히 뭔데?"라고 물어보면 명쾌하게 대답하기가 쉽지 않다. (솔직히 필자도 한동안 그냥 분위기에 맞춰 끄덕였었다)

더 혼란스러운 것은 "도메인 모델"과 "도메인 오브젝트"와 "도메인 오브젝트 모델"이 서로 어떻게 다른지, 그리고 이 개념들이 백엔드가 아닌 프론트엔드에서는 어떤 의미를 갖는지에 대한 정리된 글이 많지 않다는 점이다. 이 글에서는 각 개념의 정확한 정의부터 시작해서, 프론트엔드에서 도메인 로직을 어떻게 분리하고 추상화하는 것이 적합한지까지 예시와 함께 정리해보려 한다.

도메인(Domain)이란 무엇인가?

가장 기초적인 질문부터 시작해보자. 도메인이란 무엇인가?

Eric Evans는 그의 저서 *"Domain-Driven Design: Tackling Complexity in the Heart of Software"(2003)*에서 도메인을 다음과 같이 정의한다.

"A sphere of knowledge, influence, or activity." (지식, 영향력, 또는 활동의 영역)

쉽게 말해, 프로그래밍으로 해결하고자 하는 문제 영역 그 자체가 도메인이다. 세금 신고 서비스를 만든다면 "세금 신고"가 도메인이고, 보험 청구 플랫폼을 만든다면 "보험 청구"가 도메인인 것이다. 도메인은 코드가 아니다. 소프트웨어 이전에 존재하는 현실 세계의 문제 영역이다.

프론트엔드 개발자에게 이것은 어떤 의미일까? 우리가 만드는 UI는 결국 이 도메인을 사용자에게 보여주고 조작할 수 있게 해주는 **창(window)**이다. 토스인컴 같은 세금 환급 서비스를 개발한다면, 소득 유형, 경비율, 소득공제, 세액공제, 환급액이라는 도메인 개념을 UI로 표현하는 것이다. 따라서 프론트엔드 개발자도 자신이 다루는 도메인을 깊이 이해해야 한다. UI 컴포넌트를 잘 그리는 것 못지않게, **"이 서비스가 해결하는 문제가 무엇인지"**를 아는 것이 중요하다는 뜻이다.

그런데 "세금"이라는 도메인 하나만 해도, 들여다보면 내부에 수많은 하위 도메인이 존재한다. 종합소득세 계산 파이프라인만 봐도 이렇다.

총수입금액 → 필요경비 차감 → 종합소득금액
  → 소득공제 → 과세표준 → 세율 적용 → 산출세액
    → 세액공제 → 결정세액 → 기납부세액 차감
      → 납부 or 환급

이 파이프라인의 각 단계가 독자적인 규칙과 데이터를 가진 하위 도메인이다. "세금"이라는 하나의 큰 도메인 안에 소득(Income), 공제(Deduction), 세액(Tax), 신고(Filing)라는 세부 도메인들이 얽혀 있는 것이다. 이것을 코드로 어떻게 나눠야 하는지가 바로 도메인 모델링의 핵심 질문이다.

도메인 모델(Domain Model)이란?

그렇다면 도메인 모델은 무엇일까? 도메인 그 자체와 도메인 "모델"은 어떻게 다른 것일까?

Martin Fowler는 *"Patterns of Enterprise Application Architecture"(2002)*에서 도메인 모델을 이렇게 정의한다.

"An object model of the domain that incorporates both behavior and data." (행위와 데이터를 모두 포함하는 도메인의 객체 모델)

Eric Evans의 정의도 살펴보자.

"A system of abstractions that describes selected aspects of a domain and can be used to solve problems related to that domain." (도메인의 선택된 측면을 기술하는 추상화 체계로, 해당 도메인과 관련된 문제를 해결하는 데 사용될 수 있다.)

핵심은 **"선택적 추상화"**라는 점이다. 도메인 모델은 현실 세계의 모든 것을 담지 않는다. 영화감독이 현실의 모든 장면을 담지 않고 이야기에 필요한 장면만 선택하듯, 도메인 모델도 해결하려는 문제에 필요한 측면만 골라서 구조화한 것이다.

여기서 중요한 점이 하나 있다. 도메인 모델은 반드시 코드일 필요가 없다. 화이트보드에 그린 다이어그램일 수도 있고, 팀원들 머릿속에 공유된 멘탈 모델(Mental Model)일 수도 있다. 한국어로 정리된 Hudi의 블로그에서도 이를 명확히 짚고 있다 — "도메인 모델이라는 용어 자체는 엄밀하게는 소프트웨어와는 별개의 개념"이라고 말이다.

도메인 모델과 데이터 모델은 다르다

프론트엔드 개발자가 특히 혼동하기 쉬운 부분이 있다. API 응답의 JSON 구조를 보고 "이게 도메인 모델이군"이라고 생각하는 것이다. 하지만 이는 **데이터 모델(Data Model)**이지, 도메인 모델이 아니다.

데이터 모델은 "어떤 형태로 데이터가 오가는가"를 정의하고, 도메인 모델은 "이 데이터가 비즈니스적으로 무엇을 의미하고 어떤 규칙을 따르는가"를 정의한다. 이 둘을 구분하지 못하면, 컴포넌트가 API 응답 구조에 직접 의존하게 되어 백엔드 스키마가 바뀔 때마다 프론트엔드 전체가 흔들리는 상황이 벌어진다.

도메인 오브젝트(Domain Object)란?

도메인 모델이 개념적 추상화라면, 도메인 오브젝트는 그 개념이 코드로 구현된 실체이다.

Code with Jason의 정리가 가장 직관적이다.

"Any object in my object model that also exist as a concept in my domain model I would call a domain object." (내 객체 모델에 있는 객체 중 내 도메인 모델에도 개념으로 존재하는 것을 도메인 오브젝트라고 부른다.)

즉, 도메인 모델에서 "종합소득"이라는 개념이 있고, 코드에서 Income이라는 타입이 있다면, 이 Income이 바로 도메인 오브젝트인 것이다. 모든 코드 객체가 도메인 오브젝트인 것은 아니다. HttpClient, LocalStorageAdapter, useDebounce 같은 것들은 기술적 도구이지 도메인 개념이 아니다.

Entity와 Value Object

Evans는 도메인 오브젝트를 크게 두 가지로 분류한다. Fowler는 이를 "Evans Classification"이라고 부른다.

Entity(엔티티):

"Objects that have a distinct identity that runs through time and different representations." (시간과 다양한 표현을 관통하는 고유한 정체성을 가진 객체)

세금 신고서(TaxFiling), 납세자(Taxpayer), 보험 계약(Policy)처럼 고유한 ID로 식별되는 객체이다. 속성이 바뀌더라도 같은 ID면 같은 엔티티이다. 신고서의 공제 항목이 수정되어도 같은 신고서인 것처럼.

Value Object(값 객체):

"Objects that matter only as the combination of their attributes. Two value objects with the same values for all their attributes are considered equal." (속성의 조합으로만 의미를 가지는 객체. 모든 속성 값이 같으면 동일한 것으로 간주한다.)

금액(Money), 세율(TaxRate), 과세 구간(TaxBracket)처럼 값 자체가 의미인 객체이다. "세율 6%"는 어디에서 쓰이든 "세율 6%"일 뿐이다.

프론트엔드에서 이 구분이 왜 중요할까? TypeScript로 예시를 들어보자.

// Entity - ID로 식별된다
interface TaxFiling {
  id: string;
  taxpayerName: string;
  taxYear: number;
  status: FilingStatus;
}
 
// 같은 ID면 같은 신고서
const isSameFiling = (a: TaxFiling, b: TaxFiling) => a.id === b.id;
 
// Value Object - 값의 조합으로 식별된다
interface Money {
  amount: number;
  currency: "KRW" | "USD";
}
 
// 모든 속성이 같으면 같은 값
const isSameMoney = (a: Money, b: Money) =>
  a.amount === b.amount && a.currency === b.currency;

Entity는 ID 기반 비교, Value Object는 속성 기반 비교. 이 구분을 명확히 하면 상태 관리에서 "이 데이터가 같은 건지 다른 건지"를 판단하는 로직이 자연스럽게 정리된다. 리스트에서 아이템을 갱신할 때 Entity라면 ID로 찾아서 교체하고, Value Object라면 불변 교체(immutable replace)를 하는 식이다.

도메인 오브젝트 모델(Domain Object Model)이란?

자, 여기까지 읽으면 자연스럽게 떠오르는 질문이 하나 있다. "도메인 모델"과 "도메인 오브젝트"는 알겠는데, 도메인 오브젝트 모델은 또 뭔가?

이 용어는 앞의 세 개념을 연결하는 다리 역할을 한다.

"The place where my domain model turns into actual code is in the object model." (내 도메인 모델이 실제 코드로 전환되는 곳이 바로 객체 모델이다.) — Code with Jason

도메인 오브젝트 모델 = 도메인 모델의 코드 구현체이다. 개념적 추상화(도메인 모델)를 프로그래밍 언어의 타입, 클래스, 함수로 표현한 것이 도메인 오브젝트 모델이고, 그 안의 개별 타입이나 인스턴스가 도메인 오브젝트인 것이다.

(참고로, 웹 개발에서 흔히 접하는 DOM(Document Object Model)과는 완전히 다른 개념이다. Wikipedia에서도 이 둘이 별개임을 명시하고 있다.)

네 가지 개념의 관계를 세금 도메인으로 정리하면 다음과 같다.

도메인 (Domain)
  → 문제 영역 그 자체. "종합소득세 신고"

도메인 모델 (Domain Model)
  → 문제 영역의 선택적 추상화. "소득-경비-공제-세액-환급" 계산 파이프라인

도메인 오브젝트 모델 (Domain Object Model)
  → 도메인 모델의 코드 구현 전체. Income, Deduction, TaxCalculation, Filing 타입들과 그 관계

도메인 오브젝트 (Domain Object)
  → 구현된 개별 객체. 특정 납세자의 TaxCalculation 인스턴스 하나

이것은 추상에서 구체로 내려가는 계층이다. 도메인이 가장 넓고, 도메인 오브젝트가 가장 구체적이다.

프론트엔드에서 도메인 로직은 어디에 있어야 하는가?

개념 정의는 여기까지로 하고, 이제 실전 이야기를 해보자. 프론트엔드에서 도메인 로직은 어디에 있어야 하는 걸까?

Khalil Stemmler는 처음에 "비즈니스 로직은 프론트엔드에 속하지 않는다"고 주장했다가, 이후 입장을 수정하며 이렇게 말했다.

"Pretty much everything we're doing architecturally on the backend, we could and should be doing on the frontend." (백엔드에서 아키텍처적으로 하고 있는 거의 모든 것을, 프론트엔드에서도 할 수 있고 해야 한다.)

필자도 이 입장에 동의한다. 물론 프론트엔드가 비즈니스 로직의 **단일 진실 공급원(Single Source of Truth)**이 되어서는 안 된다. 그것은 백엔드의 역할이다. 하지만 프론트엔드에도 프론트엔드만의 도메인 로직이 분명히 존재한다. 세금 서비스처럼 "사용자가 입력한 정보에 따라 실시간으로 예상 환급액을 보여줘야 하는" 경우에는 더욱 그렇다.

흔히 발생하는 안티패턴: 도메인 로직이 컴포넌트에 섞인 경우

종합소득세 미리보기 화면을 예로 들어보자. 사용자가 소득 정보를 입력하면 예상 세액을 실시간으로 보여주는 기능이다. 아래는 흔히 볼 수 있는, 도메인 로직과 UI 로직이 뒤섞인 코드이다.

function TaxPreviewPage() {
  const [grossIncome, setGrossIncome] = useState(0);
  const [expenseRate, setExpenseRate] = useState(0.646); // 단순경비율
  const [personalDeductions, setPersonalDeductions] = useState(1); // 본인 1명
 
  // 비즈니스 규칙: 종합소득금액 = 총수입 - 필요경비
  const totalIncome = grossIncome - grossIncome * expenseRate;
 
  // 비즈니스 규칙: 인적공제 1인당 150만원
  const deductionAmount = personalDeductions * 1_500_000;
  const taxableBase = Math.max(0, totalIncome - deductionAmount);
 
  // 비즈니스 규칙: 8단계 누진세율
  let calculatedTax = 0;
  if (taxableBase <= 14_000_000) {
    calculatedTax = taxableBase * 0.06;
  } else if (taxableBase <= 50_000_000) {
    calculatedTax = taxableBase * 0.15 - 1_260_000;
  } else if (taxableBase <= 88_000_000) {
    calculatedTax = taxableBase * 0.24 - 5_760_000;
  } else if (taxableBase <= 150_000_000) {
    calculatedTax = taxableBase * 0.35 - 15_440_000;
  } else {
    calculatedTax = taxableBase * 0.38 - 19_940_000;
  }
 
  // 비즈니스 규칙: 기납부세액 (3.3% 원천징수)
  const prepaidTax = grossIncome * 0.033;
  const refundOrPayment = prepaidTax - calculatedTax;
 
  return (
    <div>
      <input value={grossIncome} onChange={e => setGrossIncome(Number(e.target.value))} />
      <p>종합소득금액: {totalIncome.toLocaleString()}원</p>
      <p>과세표준: {taxableBase.toLocaleString()}원</p>
      <p>산출세액: {Math.floor(calculatedTax).toLocaleString()}원</p>
      <p>기납부세액: {Math.floor(prepaidTax).toLocaleString()}원</p>
      <p>{refundOrPayment > 0 ? '환급 예상액' : '납부 예상액'}: {Math.abs(Math.floor(refundOrPayment)).toLocaleString()}원</p>
    </div>
  );
}

이 코드의 문제가 보이는가? "인적공제 1인당 150만원", "8단계 누진세율", "3.3% 원천징수"라는 세법에 의해 정해진 비즈니스 규칙이 React 컴포넌트 안에 직접 박혀 있다. 세법이 매년 개정되는데, 이런 규칙이 컴포넌트에 흩어져 있으면 개정 시 수정해야 할 곳을 찾아 헤매게 된다. (토스인컴의 QA팀이 환급 플로우만으로 35개 이상의 E2E 시나리오를 운영한다는 사실을 떠올려보면, 이런 규칙이 컴포넌트에 박혀 있을 때의 테스트 비용을 짐작할 수 있다) emewjin의 블로그에서도 이 상황을 정확히 지적한다 — "이게 뷰 로직인지 비즈니스 로직인지 구분하기 어려울 정도로 엉킨다."

도메인 로직 분리: 순수 함수로 추출하기

Alex Bespoyasov의 Clean Architecture 접근법에서 핵심 원칙을 빌려오자. 도메인 로직은 프레임워크에 의존하지 않는 순수 함수로 분리하는 것이다.

"The domain is the core that distinguishes one application from another. You can think of the domain as something that won't change if we move from React to Angular." (도메인은 하나의 애플리케이션을 다른 것과 구별하는 핵심이다. React에서 Angular로 옮기더라도 변하지 않는 것이라고 생각하면 된다.)

위의 세금 계산 예시를 리팩토링해보자.

1단계: 도메인 타입 정의

// domain/tax.ts
 
export interface Income {
  grossAmount: number;       // 총수입금액
  expenseRate: number;       // 경비율 (단순/기준)
}
 
export interface Deductions {
  personalCount: number;     // 인적공제 대상 인원
  pensionPaid: number;       // 연금보험료
  additionalDeductions: number; // 기타 소득공제
}
 
export interface TaxCalculation {
  totalIncome: number;       // 종합소득금액
  deductionAmount: number;   // 소득공제 합계
  taxableBase: number;       // 과세표준
  calculatedTax: number;     // 산출세액
  prepaidTax: number;        // 기납부세액
  refundOrPayment: number;   // 환급(+) 또는 납부(-)
}

2단계: 도메인 로직을 순수 함수로 분리

// domain/tax.ts (이어서)
 
const PERSONAL_DEDUCTION_PER_PERSON = 1_500_000;
const WITHHOLDING_RATE = 0.033;
 
const TAX_BRACKETS = [
  { limit: 14_000_000,  rate: 0.06, progressiveDeduction: 0 },
  { limit: 50_000_000,  rate: 0.15, progressiveDeduction: 1_260_000 },
  { limit: 88_000_000,  rate: 0.24, progressiveDeduction: 5_760_000 },
  { limit: 150_000_000, rate: 0.35, progressiveDeduction: 15_440_000 },
  { limit: 300_000_000, rate: 0.38, progressiveDeduction: 19_940_000 },
  { limit: 500_000_000, rate: 0.40, progressiveDeduction: 25_940_000 },
  { limit: 1_000_000_000, rate: 0.42, progressiveDeduction: 35_940_000 },
  { limit: Infinity,    rate: 0.45, progressiveDeduction: 65_940_000 },
] as const;
 
export function calculateTotalIncome(income: Income): number {
  return income.grossAmount - income.grossAmount * income.expenseRate;
}
 
export function calculateDeductions(deductions: Deductions): number {
  return (
    deductions.personalCount * PERSONAL_DEDUCTION_PER_PERSON +
    deductions.pensionPaid +
    deductions.additionalDeductions
  );
}
 
export function calculateTaxableBase(totalIncome: number, deductionAmount: number): number {
  return Math.max(0, totalIncome - deductionAmount);
}
 
export function calculateTax(taxableBase: number): number {
  const bracket = TAX_BRACKETS.find(b => taxableBase <= b.limit)!;
  return Math.floor(taxableBase * bracket.rate - bracket.progressiveDeduction);
}
 
export function calculatePrepaidTax(grossIncome: number): number {
  return Math.floor(grossIncome * WITHHOLDING_RATE);
}
 
export function calculateRefund(prepaidTax: number, calculatedTax: number): number {
  return prepaidTax - calculatedTax;
}
 
export function computeFullTax(income: Income, deductions: Deductions): TaxCalculation {
  const totalIncome = calculateTotalIncome(income);
  const deductionAmount = calculateDeductions(deductions);
  const taxableBase = calculateTaxableBase(totalIncome, deductionAmount);
  const calculatedTax = calculateTax(taxableBase);
  const prepaidTax = calculatePrepaidTax(income.grossAmount);
  const refundOrPayment = calculateRefund(prepaidTax, calculatedTax);
 
  return { totalIncome, deductionAmount, taxableBase, calculatedTax, prepaidTax, refundOrPayment };
}

3단계: 컴포넌트는 도메인 로직을 "사용"만 한다

// ui/TaxPreviewPage.tsx
 
import { computeFullTax } from '../domain/tax';
 
function TaxPreviewPage() {
  const [income, setIncome] = useState<Income>({ grossAmount: 0, expenseRate: 0.646 });
  const [deductions, setDeductions] = useState<Deductions>({
    personalCount: 1, pensionPaid: 0, additionalDeductions: 0,
  });
 
  const result = computeFullTax(income, deductions);
 
  return (
    <div>
      <IncomeForm value={income} onChange={setIncome} />
      <DeductionForm value={deductions} onChange={setDeductions} />
      <TaxResultSummary result={result} />
    </div>
  );
}

무엇이 달라졌는가?

1. 8단계 누진세율 테이블(TAX_BRACKETS)이 한 곳에 모여 있어 세법 개정 시 이 파일만 수정하면 된다
2. 계산 파이프라인이 computeFullTax 한 함수로 응집되어, 전체 흐름이 한눈에 보인다
3. 컴포넌트는 "어떻게 보여줄까"에만 집중한다. 세율이 바뀌어도 컴포넌트를 수정할 필요가 없다
4. React에서 Vue로 마이그레이션한다 해도, domain/tax.ts는 한 글자도 바꿀 필요 없다

테스트가 쉬워진다

도메인 로직이 분리되면 테스트는 놀랍도록 단순해진다. 세금 도메인에서는 계산의 정확성이 곧 사용자의 돈이기 때문에 이 점이 특히 중요하다.

// domain/tax.test.ts
 
describe('calculateTax', () => {
  it('1,400만원 이하는 6% 세율', () => {
    expect(calculateTax(10_000_000)).toBe(600_000);
  });
 
  it('5,000만원 이하는 15% 세율 - 누진공제 126만원', () => {
    expect(calculateTax(40_000_000)).toBe(4_740_000); // 40M * 0.15 - 1,260,000
  });
 
  it('과세표준 0원이면 세액도 0원', () => {
    expect(calculateTax(0)).toBe(0);
  });
});
 
describe('computeFullTax', () => {
  it('프리랜서 3,000만원 소득, 단순경비율 64.6%의 환급액을 정확히 계산한다', () => {
    const income = { grossAmount: 30_000_000, expenseRate: 0.646 };
    const deductions = { personalCount: 1, pensionPaid: 0, additionalDeductions: 0 };
    const result = computeFullTax(income, deductions);
 
    // 종합소득금액: 30M - 30M * 0.646 = 10,620,000
    expect(result.totalIncome).toBe(10_620_000);
    // 과세표준: 10,620,000 - 1,500,000 = 9,120,000
    expect(result.taxableBase).toBe(9_120_000);
    // 산출세액: 9,120,000 * 0.06 = 547,200
    expect(result.calculatedTax).toBe(547_200);
    // 기납부세액: 30M * 0.033 = 990,000
    expect(result.prepaidTax).toBe(990_000);
    // 환급액: 990,000 - 547,200 = 442,800
    expect(result.refundOrPayment).toBe(442_800);
  });
});

React Testing Library도, render도, screen.getByText도 필요 없다. 순수 함수에 입력을 넣고 출력을 확인하면 된다. 우아한형제들 기술블로그에서도 SCM 플랫폼 프론트엔드 개발 사례를 통해, 도메인 단위 테스트가 컴포넌트 분리 기준을 자연스럽게 잡아주고, 테스트 코드가 문서 역할까지 한다는 점을 보여주고 있다.

빈약한 도메인 모델(Anemic Domain Model)을 경계하라

여기서 한 가지 주의할 점이 있다. Martin Fowler는 **빈약한 도메인 모델(Anemic Domain Model)**을 안티패턴으로 강하게 비판했다.

"The fundamental horror of this anti-pattern is that it's so contrary to the basic idea of object-oriented design; which is to combine data and process together." (이 안티패턴의 근본적인 공포는, 데이터와 프로세스를 결합하라는 객체지향 설계의 기본 사상에 정면으로 반한다는 것이다.)

"In essence the problem with anemic domain models is that they incur all of the costs of a domain model, without yielding any of the benefits." (본질적으로 빈약한 도메인 모델의 문제는, 도메인 모델의 비용은 모두 지불하면서 이점은 하나도 얻지 못한다는 것이다.)

프론트엔드에서 빈약한 도메인 모델은 이런 모습이다. 세금 신고(Filing) 도메인을 예로 들어보자.

// 빈약한 도메인 모델의 예
// 타입은 있지만, 행위(규칙)가 없다
interface TaxFiling {
  id: string;
  status: 'draft' | 'submitted' | 'reviewing' | 'completed' | 'amended';
  taxYear: number;
  filingType: 'regular' | 'late' | 'amendment';
  determinedTax: number;
}
 
// 비즈니스 규칙이 여기저기 흩어져 있다
// utils/filingHelpers.ts
function canAmendFiling(filing: TaxFiling): boolean { /* ... */ }
 
// hooks/useFilingActions.ts
function useFilingActions() { /* canAmendFiling를 또 구현하거나 import... */ }
 
// components/FilingDetail.tsx
function FilingDetail({ filing }: { filing: TaxFiling }) {
  // 또 다른 곳에서 수정 가능 여부를 직접 판단...
  const isEditable = filing.status === 'draft';
  // ...
}

타입은 정의했지만 규칙이 타입과 분리되어 여러 파일에 흩어져 있다. 이러면 "경정청구 가능 조건이 변경됩니다"라는 요구사항이 들어왔을 때, 수정해야 할 곳이 어딘지 찾아다녀야 한다. (속된 말로 지뢰 찾기다)

개선된 방향은 행위를 도메인과 함께 두는 것이다.

// domain/filing.ts
 
export interface TaxFiling {
  id: string;
  status: FilingStatus;
  taxYear: number;
  filingType: FilingType;
  determinedTax: number;
}
 
export type FilingStatus = 'draft' | 'submitted' | 'reviewing' | 'completed' | 'amended';
export type FilingType = 'regular' | 'late' | 'amendment';
 
// 도메인 규칙은 도메인 옆에 둔다
export function canEdit(filing: TaxFiling): boolean {
  return filing.status === 'draft';
}
 
export function canSubmit(filing: TaxFiling): boolean {
  return filing.status === 'draft' && filing.determinedTax >= 0;
}
 
export function canAmend(filing: TaxFiling): boolean {
  return filing.status === 'completed' && filing.filingType !== 'amendment';
}
 
export function getNextAvailableStatuses(filing: TaxFiling): FilingStatus[] {
  const transitions: Record<FilingStatus, FilingStatus[]> = {
    draft: ['submitted'],
    submitted: ['reviewing'],
    reviewing: ['completed'],
    completed: ['amended'],
    amended: [],
  };
  return transitions[filing.status];
}

이제 신고 관련 비즈니스 규칙은 domain/filing.ts 한 곳에서 관리된다. 어떤 컴포넌트에서든 canAmend(filing)를 호출하면 되고, 규칙이 바뀌면 이 파일 하나만 수정하면 된다.

API 응답과 도메인 모델 사이의 변환 계층

실무에서 한 가지 더 고려해야 할 것이 있다. 백엔드 API 응답 구조와 프론트엔드의 도메인 모델이 항상 일치하지는 않는다는 점이다. 세금 서비스에서는 특히 그렇다. 국세청 홈택스 연동 데이터는 약어와 코드값으로 가득 차 있다.

emewjin의 블로그에서는 class를 활용해 서버 데이터를 모델로 관리하면서 이런 이점을 발견했다고 기록한다 — "서버로부터 받아온 값과 각 필드에 대한, 뷰 로직과는 독립적인 로직을 한 곳에서 관리"할 수 있게 되었다고. 동시에 "백엔드에서 name이 realName으로 바뀌어도, 모델만 수정하면 된다"는 실용적 장점도 있었다.

TypeScript에서 class 없이도 이런 변환 계층을 만들 수 있다.

// infrastructure/mappers/incomeMapper.ts
 
// API 응답 타입 (홈택스 연동 데이터 구조)
interface HometaxIncomeResponse {
  tot_amt: number;          // 총수입금액
  inc_tp_cd: string;        // 소득유형코드
  biz_cd: string;           // 업종코드
  exp_rt: number;           // 경비율
  wh_tax_amt: number;       // 원천징수세액
  pyr_nm: string;           // 지급자명
  tx_yr: string;            // 귀속연도
}
 
// 도메인 타입 (프론트엔드가 정의한 구조)
import type { Income } from '../domain/tax';
 
export function toIncome(response: HometaxIncomeResponse): Income {
  return {
    grossAmount: response.tot_amt,
    expenseRate: response.exp_rt,
  };
}
 
function mapIncomeType(code: string): IncomeType {
  const typeMap: Record<string, IncomeType> = {
    '40': 'business',       // 사업소득
    '60': 'employment',     // 근로소득
    '61': 'pension',        // 연금소득
    '80': 'other',          // 기타소득
  };
  return typeMap[code] ?? 'other';
}

이렇게 하면 API 응답의 tot_amt, inc_tp_cd 같은 약어, 코드값 기반 분류 등을 프론트엔드 도메인에 맞게 한 곳에서 변환한다. 홈택스 API의 필드명이 바뀌어도 mapper 함수 하나만 수정하면 된다. Roseline의 블로그에서도 이 접근을 "API와 UI의 연결을 효과적으로 설계"하는 방법으로 소개하고 있다.

유틸 함수와 도메인 로직, 그 애매한 경계

도메인 로직을 분리하다 보면 반드시 부딪히는 질문이 있다. "이거 유틸 함수 아닌가?"

예를 들어 아래 두 함수를 보자.

// 이건 유틸인가, 도메인 로직인가?
function formatCurrency(amount: number): string {
  return `${amount.toLocaleString()}원`;
}
 
// 이건?
function calculateTax(taxableBase: number): number {
  const bracket = TAX_BRACKETS.find(b => taxableBase <= b.limit)!;
  return Math.floor(taxableBase * bracket.rate - bracket.progressiveDeduction);
}

formatCurrency는 숫자를 문자열로 바꾸는 순수한 표현(Presentation) 로직이다. "원"이라는 단위를 붙이고 천 단위 콤마를 찍는 것은 비즈니스 규칙이 아니라, 사용자에게 어떻게 보여줄지에 관한 것이다. 반면 calculateTax는 "8단계 누진세율 적용"이라는 세법에 근거한 비즈니스 규칙을 담고 있다. 이것은 UI가 없어도 동일하게 적용되어야 하는 도메인의 규칙이다.

필자가 실무에서 사용하는 판단 기준은 이것이다.

"이 로직이 사라지면 비즈니스가 깨지는가, 화면만 깨지는가?"

비즈니스가 깨진다면 도메인 로직이고, 화면만 깨진다면 표현 로직이다. 이 질문 하나로 대부분의 경계는 구분할 수 있다.

하지만 현실은 이렇게 깔끔하지 않다. 가장 까다로운 것은 도메인 로직처럼 생겼는데 실은 표현 로직인 경우이다.

// domain/filing.ts 에 넣었는데... 이게 정말 도메인인가?
function getStatusBadgeColor(status: FilingStatus): string {
  const colors: Record<FilingStatus, string> = {
    draft: 'gray',
    submitted: 'blue',
    reviewing: 'yellow',
    completed: 'green',
    amended: 'purple',
  };
  return colors[status];
}
 
function getStatusDisplayText(status: FilingStatus): string {
  const labels: Record<FilingStatus, string> = {
    draft: '작성 중',
    submitted: '제출 완료',
    reviewing: '검토 중',
    completed: '신고 완료',
    amended: '경정청구',
  };
  return labels[status];
}

getStatusBadgeColor와 getStatusDisplayText는 FilingStatus라는 도메인 개념을 사용하지만, 하는 일은 화면 표현이다. 배지 색상이 바뀌어도 비즈니스는 전혀 깨지지 않는다. 이런 함수를 domain/filing.ts에 넣으면 도메인 모듈이 점점 비대해지고, 진짜 도메인 로직(canAmend, canSubmit)과 표현 로직이 뒤섞이게 된다.

도메인 모델과 ViewModel의 분리

이 문제를 해결하는 실용적인 방법이 있다. 같은 도메인 폴더 안에 ViewModel을 별도 파일로 분리하는 것이다. .ui.ts보다 .viewModel.ts라는 네이밍을 쓰면, MVVM 패턴의 ViewModel 개념과 자연스럽게 연결된다 — "도메인 데이터를 화면에 맞게 변환하는 계층"이라는 역할이 이름에서 바로 드러나기 때문이다.

domains/
└── filing/
    ├── filing.ts              # 도메인 모델 + 도메인 로직
    ├── filing.viewModel.ts    # ViewModel (표현 변환 계층)
    ├── filing.test.ts         # 도메인 로직 테스트
    └── filingMapper.ts        # API ↔ 도메인 변환

// domains/filing/filing.ts — 순수 도메인
export interface TaxFiling {
  id: string;
  status: FilingStatus;
  taxYear: number;
  filingType: FilingType;
  determinedTax: number;
}
 
export type FilingStatus = 'draft' | 'submitted' | 'reviewing' | 'completed' | 'amended';
export type FilingType = 'regular' | 'late' | 'amendment';
 
export function canEdit(filing: TaxFiling): boolean {
  return filing.status === 'draft';
}
 
export function canAmend(filing: TaxFiling): boolean {
  return filing.status === 'completed' && filing.filingType !== 'amendment';
}

// domains/filing/filing.viewModel.ts — 표현 관심사
import type { FilingStatus, FilingType } from './filing';
 
export function getStatusBadgeColor(status: FilingStatus): string {
  const colors: Record<FilingStatus, string> = {
    draft: 'gray',
    submitted: 'blue',
    reviewing: 'yellow',
    completed: 'green',
    amended: 'purple',
  };
  return colors[status];
}
 
export function getStatusDisplayText(status: FilingStatus): string {
  const labels: Record<FilingStatus, string> = {
    draft: '작성 중',
    submitted: '제출 완료',
    reviewing: '검토 중',
    completed: '신고 완료',
    amended: '경정청구',
  };
  return labels[status];
}
 
export function getFilingTypeLabel(type: FilingType): string {
  const labels: Record<FilingType, string> = {
    regular: '정기 신고',
    late: '기한 후 신고',
    amendment: '경정청구',
  };
  return labels[type];
}

핵심은 의존 방향이다. filing.viewModel.ts는 filing.ts를 import하지만, filing.ts는 filing.viewModel.ts를 절대 import하지 않는다. 도메인은 표현을 모르고, 표현이 도메인을 알고 있는 구조이다. 이것이 Robert C. Martin이 말한 의존성 규칙(Dependency Rule)의 축소판이라고 볼 수 있다.

같은 폴더에 두는 이유가 있다. 토스 프론트엔드 챕터에서 강조하는 원칙 — "함께 변경되는 파일을 같은 디렉토리에 배치하라"를 따른 것이다. FilingStatus 타입에 새로운 값(예: 'rejected')이 추가되면 filing.ts와 filing.viewModel.ts 모두 수정해야 한다. 같은 폴더에 있으니 수정 범위가 한눈에 보인다.

도메인 모델의 경계와 응집

도메인 로직을 분리하는 것만큼 중요한 것이 경계를 어디에 그을 것인가이다. 필자가 실무에서 자주 마주치는 경계 판단 문제를 몇 가지 정리해보겠다.

데이터의 경계: 이 필드는 누구의 것인가?

프론트엔드에서 다루는 데이터는 대략 네 가지 출처에서 온다.

1. 서버 데이터: API 응답으로 받은 것 (filing.status, income.grossAmount)
2. 파생 데이터: 서버 데이터로부터 계산된 것 (taxableBase, refundAmount)
3. UI 상태: 화면 제어를 위한 것 (isModalOpen, selectedTab)
4. 사용자 입력: 폼에서 입력 중인 것 (inputAmount, selectedDeductions)

이 네 가지를 하나의 타입에 섞으면 도메인 모델이 오염된다.

// 안티패턴: 모든 것이 섞인 타입
interface TaxFiling {
  // 서버 데이터 (도메인)
  id: string;
  status: FilingStatus;
  determinedTax: number;
 
  // 파생 데이터 (도메인)
  refundAmount: number;
  canAmend: boolean;
 
  // UI 상태 (표현)
  isExpanded: boolean;
  activeStep: number;
 
  // 임시 상태
  editingDeductions: Deduction[];
}

이 타입은 도메인 개념과 UI 상태와 임시 데이터가 한 바구니에 담겨 있다. activeStep이 바뀔 때마다 신고 도메인이 갱신되는 셈이다. (폼 단계가 바뀌는 것은 비즈니스 이벤트가 아니다)

개선 방향은 경계에 따라 타입을 분리하는 것이다.

// 도메인 모델 — 비즈니스 개념만
interface TaxFiling {
  id: string;
  status: FilingStatus;
  taxYear: number;
  filingType: FilingType;
  determinedTax: number;
}
 
// UI 상태 — 화면 제어만
interface FilingFormViewState {
  activeStep: number;
  expandedSections: Set<string>;
}
 
// 사용자 입력 — 폼 상태만
interface DeductionEditForm {
  personalCount: number;
  selectedDeductionIds: string[];
  customExpenseAmount: number;
}

이렇게 하면 각 타입이 하나의 변경 이유만 가진다. 도메인 타입은 세법이 바뀔 때만, UI 상태는 화면 설계가 바뀔 때만, 폼 상태는 입력 UX가 바뀔 때만 수정된다.

응집의 기준: "함께 변하는 것을 함께 두어라"

Evans의 DDD에서 **Aggregate(집합체)**라는 개념이 있다. "관련된 객체들의 클러스터를 하나의 단위로 다루는 것"이다. 프론트엔드에서 이 개념을 그대로 적용할 필요는 없지만, 핵심 원칙은 빌려올 만하다 — 함께 변하는 데이터와 규칙은 함께 둔다.

세금 서비스를 예로 들면, Income(소득)과 ExpenseRate(경비율)는 항상 함께 변한다. 소득 유형이 바뀌면 적용 경비율도 바뀌고, 종합소득금액 계산도 영향을 받는다. 따라서 이것들은 하나의 파일 domain/tax.ts에 응집시킨다.

반면, TaxFiling(신고서)은 세액 계산과 별개로 변할 수 있다. 신고서의 상태 전이 규칙이 바뀌어도 세율 계산 로직은 영향을 받지 않는다. 따라서 domain/filing.ts로 분리하는 것이 맞다.

이렇게 묻자: "A가 변할 때 B도 반드시 변해야 하는가?"
  → Yes: 같은 모듈에 둔다 (Income + ExpenseRate + TaxBracket)
  → No: 분리한다 (Tax 계산 ↔ Filing 상태관리)

Class vs 함수형: 도메인 응집의 두 가지 표현

여기까지 읽으면 한 가지 근본적인 질문이 떠오를 수 있다. 지금까지의 예시는 모두 interface + 순수 함수 조합이었는데, Class로 도메인을 표현하면 응집이 더 자연스럽지 않은가?

맞는 말이다. Class 기반으로 도메인을 표현하면 데이터와 행위가 하나의 객체에 묶이기 때문에, 응집이 코드 구조에서 바로 드러난다.

// Class 기반: 행위가 데이터에 귀속된다
class TaxFilingModel {
  constructor(
    public readonly id: string,
    public readonly status: FilingStatus,
    public readonly taxYear: number,
    public readonly filingType: FilingType,
    public readonly determinedTax: number,
  ) {}
 
  canEdit(): boolean {
    return this.status === 'draft';
  }
 
  canAmend(): boolean {
    return this.status === 'completed' && this.filingType !== 'amendment';
  }
 
  canSubmit(): boolean {
    return this.status === 'draft' && this.determinedTax >= 0;
  }
}
 
// 사용: 주어가 명확하다
const filing = new TaxFilingModel('F-001', 'completed', 2025, 'regular', 547200);
filing.canAmend();  // "이 신고서가 경정청구 가능한가?" — 자연어에 가깝다

filing.canAmend()는 마치 자연어를 읽는 것처럼 직관적이다. 주어(filing)와 동사(canAmend)가 명확하게 결합되어 있다. 마치 jihoon.eat('감자탕')이라고 쓰면 "지훈이가 감자탕을 먹는다"가 바로 읽히는 것과 같다.

반면 함수형 스타일에서는 이렇게 된다.

// 함수형: 행위가 데이터 밖에 있다
canAmend(filing);           // "경정청구가능한가(신고서를)"
eat('jihoon', '감자탕');     // "먹는다(지훈을, 감자탕을)"

주어와 동사의 결합이 느슨해진다. canAmend라는 함수가 TaxFiling과 관련된다는 것은 파일을 열어보거나 타입 시그니처를 확인해야 알 수 있다. 같은 파일에 canAmend(filing), canEdit(filing), calculateTax(taxableBase) 같은 함수들이 섞여 있으면, 어떤 함수가 어떤 도메인에 속하는지 한눈에 파악하기 어려워질 수 있다.

그렇다면 프론트엔드에서는 Class를 써야 하는가?

솔직히 말하면, 답은 **"상황에 따라 다르다"**이다. 하지만 필자의 경험상 React + TypeScript 환경에서는 Class가 만능이 아닌 현실적 이유들이 있다.

1. React 상태 관리와의 마찰

emewjin의 블로그에서도 정확히 이 문제를 지적하고 있다 — "리덕스 스토어에 저장시 인스턴스는 저장할 수 없다. 때문에 매번 classToPlain으로 풀어서 넣어주고, 다시 class로 만들어주어야 했다."

React의 상태 관리는 기본적으로 Plain Object를 전제로 설계되어 있다. useState, useReducer, Redux, Zustand 모두 직렬화 가능한(serializable) 객체를 다룬다. Class 인스턴스를 상태에 넣으면 직렬화/역직렬화 과정에서 메서드가 소실되고, JSON.stringify → JSON.parse 사이클에서 일반 객체로 퇴화한다.

// 이런 상황이 발생한다
const [filing, setFiling] = useState(
  new TaxFilingModel('F-001', 'draft', 2025, 'regular', 0)
);
 
// 상태 업데이트 후 filing은 여전히 TaxFilingModel 인스턴스인가?
// Redux DevTools에서 직렬화할 때는?
// React Server Component에서 전달할 때는?

2. 불변성 보장의 어려움

React는 상태 변경을 **참조 비교(referential equality)**로 감지한다. Class 인스턴스의 프로퍼티를 직접 수정하면 React가 변경을 감지하지 못한다. 매번 새 인스턴스를 생성해야 하는데, 그러면 Class의 이점인 "캡슐화된 상태 변경"이 무색해진다.

// Class의 캡슐화 철학과 React의 불변성 철학이 충돌한다
class DeductionList {
  // Class 철학: 내부 상태를 직접 변경
  addDeduction(item: Deduction) {
    this.items.push(/* ... */);  // React가 변경을 감지 못함!
  }
 
  // React에 맞추려면: 매번 새 인스턴스를 반환
  addDeduction(item: Deduction): DeductionList {
    return new DeductionList([...this.items, /* ... */]);  // 그럼 Class의 의미가...?
  }
}

함수형에서 응집을 확보하는 전략

그렇다면 함수형 스타일에서 eat('jihoon', '감자탕') 같은 느슨한 응집 문제를 어떻게 개선할 수 있을까? 필자가 효과적이라고 느낀 방법 세 가지를 소개한다.

전략 1: 모듈 네임스페이스로 응집하기

가장 직관적인 방법이다. 파일(모듈) 자체를 도메인 단위로 만들고, import 시 네임스페이스를 활용한다.

// domain/filing.ts
export interface TaxFiling { /* ... */ }
export function canEdit(filing: TaxFiling): boolean { /* ... */ }
export function canAmend(filing: TaxFiling): boolean { /* ... */ }
export function canSubmit(filing: TaxFiling): boolean { /* ... */ }

// 사용하는 쪽
import * as FilingModel from '../domain/filing';
 
FilingModel.canEdit(filing);      // "FilingModel의 canEdit" — 소속이 명확
FilingModel.canAmend(filing);
FilingModel.canSubmit(filing);

FilingModel.canAmend(filing)은 filing.canAmend()만큼은 아니지만, 최소한 이 함수가 Filing 도메인에 속한다는 것이 코드에서 바로 드러난다. 함수가 여러 도메인에 걸쳐 섞일 위험도 없어진다.

전략 2: 첫 번째 인자를 도메인 주체로 통일하기

함수형에서 응집을 표현하는 또 다른 컨벤션이 있다. 첫 번째 인자를 항상 "행위의 주체"로 둔다.

// 일관된 규칙: 첫 번째 인자 = 행위의 주체
export function canEdit(filing: TaxFiling): boolean { /* ... */ }
export function canAmend(filing: TaxFiling): boolean { /* ... */ }
export function calculateTotalIncome(income: Income): number { /* ... */ }
export function calculateTax(taxableBase: number): number { /* ... */ }

이 컨벤션을 따르면 canAmend(filing)은 "filing에 대해 canAmend를 물어본다"로 읽힌다. Unix의 파이프라인 사고방식(data |> transform)과도 일맥상통한다. 사실 Go 언어의 메서드 리시버가 정확히 이 패턴이고, Rust의 impl 블록에서 self를 첫 인자로 받는 것도 같은 발상이다.

전략 3: 도메인 객체 생성 함수(Factory)로 행위를 묶기

Class의 응집력이 그리울 때 사용할 수 있는 패턴이다. 팩토리 함수가 도메인 객체와 그 행위를 한 번에 반환한다.

// domain/filing.ts
export function createFilingModel(data: TaxFiling) {
  return {
    ...data,
    canEdit: () => data.status === 'draft',
    canSubmit: () => data.status === 'draft' && data.determinedTax >= 0,
    canAmend: () => data.status === 'completed' && data.filingType !== 'amendment',
  } as const;
}
 
// 사용
const filing = createFilingModel(rawFiling);
filing.canAmend();    // Class처럼 읽히면서도 Plain Object다
filing.canEdit();
 
// JSON.stringify도 되고, 스프레드도 되고, React 상태에도 들어간다

이 패턴은 Class의 표현력(filing.canAmend())과 함수형의 실용성(Plain Object, 직렬화 가능)을 동시에 얻는다. 물론 매번 함수 객체를 새로 만드는 비용이 있지만, 프론트엔드에서 다루는 데이터 규모에서는 성능 문제가 되는 경우가 거의 없다.

어떤 전략을 선택할까?

정리하면 이렇다.

필자의 경험상, 전략 1과 2를 기본으로 가져가고, 특별히 응집이 중요한 핵심 도메인에만 전략 3을 적용하는 것이 균형 잡힌 접근이다. 완벽한 응집을 위해 모든 곳에 Factory를 도입하는 것은 또 다른 과잉 설계가 될 수 있다.

어디까지 분리할 것인가? — 실용적 기준

Clean Architecture 글을 읽다 보면 3~4개 레이어를 나누고 Port/Adapter를 정의하는 이상적인 구조가 나온다. 하지만 현실에서 모든 프로젝트에 이 구조를 적용하는 것은 과잉 설계(over-engineering)가 될 수 있다. Bespoyasov 본인도 이 비용을 인정한다 — "시간 소모, 과도한 코드량, 온보딩 어려움"이 있다고.

필자가 생각하는 실용적 기준은 다음과 같다.

최소한 이것만은 하자

1. 도메인 타입을 API 응답 타입과 분리한다. interface든 type이든, 프론트엔드가 사용하는 도메인 개념을 별도 파일로 정의한다.
2. 비즈니스 규칙이 포함된 로직은 컴포넌트 밖으로 뺀다. domain/ 폴더가 아니어도 좋다. 중요한 것은 React에 의존하지 않는 순수 함수로 만드는 것이다.
3. API 응답 → 도메인 모델 변환을 한 곳에서 한다. Mapper 함수든, Zod 스키마든, 그 한 곳만 수정하면 변경이 전파되지 않는 구조를 만든다.

프로젝트가 복잡해지면 추가로

4. Bounded Context 단위로 폴더를 나눈다. 토스 프론트엔드 챕터에서도 "함께 변경되는 파일을 같은 디렉토리에 배치하라"는 원칙을 강조한다. 도메인 단위로 폴더를 나누면 import 경로가 도메인 경계를 자연스럽게 드러낸다.
5. Use Case 계층을 도입한다. 도메인 로직의 조합이 복잡해지면, "소득 정보 조회 → 경비율 적용 → 공제 항목 계산 → 세액 산출 → 환급액 확정"이라는 시나리오를 하나의 함수로 묶는 Application 계층이 필요해진다.

src/
├── domains/
│   ├── tax/
│   │   ├── tax.ts                  # 세액 계산 도메인 (세율, 공제, 계산 파이프라인)
│   │   ├── tax.viewModel.ts        # 세액 표현 (금액 포맷, 구간 라벨)
│   │   ├── tax.test.ts             # 세액 계산 테스트
│   │   └── incomeMapper.ts         # 홈택스 API ↔ 도메인 변환
│   ├── filing/
│   │   ├── filing.ts               # 신고 상태 도메인 (상태 전이, 권한)
│   │   ├── filing.viewModel.ts     # 신고 표현 (상태 배지, 라벨)
│   │   ├── filing.test.ts
│   │   └── filingMapper.ts
│   └── deduction/
│       ├── deduction.ts            # 공제 항목 도메인 (자격 조건, 한도)
│       └── deduction.viewModel.ts
├── hooks/                           # React 의존 로직
├── components/                      # UI 컴포넌트
└── api/                             # API 호출

세금이라는 하나의 도메인 안에서도 세액 계산(tax), 신고 관리(filing), **공제 항목(deduction)**이 각각 독립된 하위 도메인으로 분리된다. 세율이 바뀌어도 신고 상태 전이 로직은 영향을 받지 않고, 공제 항목이 추가되어도 신고서 제출 플로우는 그대로이다. 이것이 Bounded Context의 실전적 적용이다.

마무리

정리하면, 도메인은 우리가 해결하려는 문제 영역이고, 도메인 모델은 그 문제를 선택적으로 추상화한 개념 체계이며, 도메인 오브젝트 모델은 그 개념 체계를 코드로 구현한 것이고, 도메인 오브젝트는 그 구현 안의 개별 객체이다.

그리고 이 개념들을 프론트엔드에서 실천한다는 것은, 단순히 폴더를 나누는 것이 아니라 여러 겹의 경계를 의식적으로 판단하는 것이다. "이건 비즈니스 규칙인가, 표현 로직인가?" "이 데이터는 도메인 상태인가, UI 상태인가?" "이 함수의 응집은 충분한가?" — 이런 질문을 습관적으로 던지는 것만으로도 코드의 구조는 자연스럽게 좋아진다.

물론 모든 프로젝트에 Clean Architecture의 레이어를 다 갖출 필요는 없다. 단순한 CRUD 앱에 4개 레이어를 나누고 모든 도메인에 Factory 패턴을 적용하는 것은 배보다 배꼽이 더 큰 격이다. Class의 우아한 응집과 함수형의 실용적 유연함 사이에서 정답은 프로젝트의 복잡도와 팀의 컨텍스트가 결정한다.

정답은 없다. 하지만 적어도 **"도메인이 무엇인지 모르고 코드를 짜는 것"**과 "도메인을 인식하고, 경계를 판단하고, 의식적으로 분리하는 것" 사이에는 분명한 차이가 있다. 이 글을 읽는 독자 분들도 자신의 프로젝트에서 "여기서 도메인은 뭘까, 그리고 이 코드는 어디에 있어야 할까?"라는 질문을 한 번쯤 던져보시길 바란다.

참고 자료

• Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software (2003) — 도메인, 도메인 모델, Entity, Value Object 정의
• Martin Fowler, Patterns of Enterprise Application Architecture (2002) — Domain Model 패턴, Anemic Domain Model, Evans Classification
• Robert C. Martin, Clean Architecture (2017) — The Clean Architecture
• Code with Jason — Domains, Domain Models, Object Models, Domain Objects
• Khalil Stemmler — Does DDD Belong on the Frontend?
• Alex Bespoyasov — Clean Architecture on Frontend
• Hudi — 혼란스러운 도메인, 도메인 모델, 도메인 객체 용어 정리
• Roseline — 프론트엔드 아키텍처: UI 개발을 위한 도메인 모델링 전략
• emewjin — 프론트엔드 개발에서 서버 데이터를 모델로 관리한다는 것
• 우아한형제들 기술블로그 — 단위 테스트로 복잡한 도메인의 프론트 프로젝트 정복하기
• 토스 — Frontend Fundamentals
• 토스인컴 — 빠른 속도에서 품질을 지키기 위한 E2E 자동화 여정

평소 코드 리뷰나 리팩토링에 관심이 있었던 필자는, 토스에서 공개한 Frontend Fundamentals 모의고사라는 흥미로운 형식의 과제를 진행하게되었다. 과제는 회의실 예약 앱이 주어지고, 이를 리팩토링하는 과제였다. 테스트 코드가 함께 제공되어 있어서, 리팩토링 과정에서 기능이 깨지지 않았는지 검증할 수 있는 안전망이 갖추어져 있었다.

결과적으로 2일동안 리팩토링을 진행했고, 그 과정에서 느낀 점들을 정리해보려 한다.

코드를 처음 마주했을 때

필자가 코드를 처음 열었을 때 가장 먼저 한 일은 테스트 스펙을 읽는 것이었다. 테스트 코드는 이 애플리케이션이 무엇을 해야 하는지를 가장 정직하게 알려주는 문서이기 때문이다. App.easy.spec.tsx와 App.hard.spec.tsx를 훑으며 애플리케이션의 전체 요구사항을 파악했다.

그다음으로 실제 코드를 살펴보았는데, 눈에 들어온 것은 두 개의 모놀리식 컴포넌트였다.

• ReservationStatusPage 는 400여줄의 컴포넌트로 날짜 선택, 타임라인 시각화, 예약 상세 툴팁, 내 예약 목록, 취소 기능이 하나의 파일에 전부 들어가 있었다.
• RoomBookingPage 는 300여줄의 컴포넌트로 필터, 방 목록, 예약 생성 로직, URL 파라미터 동기화가 하나로 얽혀 있었다.

필자는 코드를 읽으면서 "개선이 필요하다"는 판단 이전에, 먼저 코드의 특성을 분류하는 데 집중했다. 어떤 코드가 도메인 정보를 담고 있고, 어떤 코드가 유틸리티 성격이며, 어떤 코드가 순수한 UI 레이어인지를 구분하는 것이다.

// 도메인 정보: 장비 라벨, 타임 슬롯 등 비즈니스 상수
const EQUIPMENT_LABELS: Record<string, string> = {
  tv: 'TV', whiteboard: '화이트보드', video: '화상장비', speaker: '스피커',
};
 
// 유틸리티: 날짜 포맷, 시간 변환
function formatDate(date: Date): string { ... }
function timeToMinutes(time: string): number { ... }
 
// 서버 상태: 인라인 useQuery, useMutation 호출
const { data: rooms = [] } = useQuery(['rooms'], getRooms);
const { data: reservations = [] } = useQuery(['reservations', date], () => getReservations(date));
 
// UI + 비즈니스 로직 혼재: 필터링, 정렬, 충돌 감지가 JSX 사이에 산재

이런 특성 분류를 해두니, 어디부터 손을 대야 할지가 자연스럽게 보이기 시작했다. 각 코드 영역에 간단한 주석을 달아두며 개선 방향을 메모했다. (마치 지금 회사에 입사했을 때 jquery 기반 프로젝트를 마이그레이션 하는 것과 비슷한 기분이었다)

그렇다면 어디서부터 손을 대야 할까?

리팩토링 전략 수립

필자는 다음과 같은 순서로 리팩토링을 진행하기로 계획했다.

1. 서버 코드 핸들링 : query, mutation 분리
2. 도메인 로직 분리 : Equipment, Room, Reservation 모델
3. 타입 선언 : 도메인 모델 기반의 타입 체계 정리
4. 유틸 함수 분리 : 날짜 포맷, 타임라인 계산 등
5. UI 레이어 분리 : 컴포넌트를 관심사별 호흡 단위로 나누기
6. 추상화 및 관심사 분리 : 에러/로딩 처리, 쿼리 키 관리

이 순서를 선택한 이유는 의존 방향의 바깥에서 안쪽으로 진행하기 위해서다. 인프라(서버 코드, 유틸)부터 정리하고, 도메인 모델을 확립한 뒤, 마지막으로 UI를 다듬는 것이다. 만약 UI 컴포넌트를 먼저 분리하면, 아직 정리되지 않은 도메인 로직과 쿼리 코드를 여러 컴포넌트에 걸쳐 옮겨 다녀야 하는 상황이 생길 수 있다.

전략을 세웠으니, 이제 하나씩 실행에 옮겨보자.

서버 코드와 유틸부터 정리하기

날짜 표시 유틸 분리

가장 먼저 손을 댄 곳은 formatDate 함수였다. 두 페이지에서 동일한 함수가 각각 인라인으로 정의되어 있었기 때문이다.

// utils/formatYYYYMMDD.ts
export function formatYYYYMMDD(date: Date): string {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, '0');
  const date = String(date.getDate()).padStart(2, '0');
  return `${year}-${month}-${date}`;
}

작은 변경이지만, 리팩토링의 첫 커밋으로서 중요한 의미가 있었다. 가장 독립적이고 사이드이펙트가 적은 부분부터 건드려서, 테스트가 여전히 통과하는지 확인하는 워밍업 같은 것이다.

React Query 훅 분리

다음으로 컴포넌트 내부에 직접 작성되어 있던 useQuery, useMutation 호출을 별도의 파일로 분리했다. queryOptions 패턴을 활용하여 쿼리 설정을 재사용 가능한 단위로 만들었다.

이 과정에서 remotes.ts에 있던 API 응답 타입도 명시적으로 정의했다. 기존에는 any로 흘러가던 타입들이 GetRoomsResponse, GetReservationsResponse 등으로 명확해졌다.

인프라 레이어를 정리했으니, 이제 도메인 모델로 눈을 돌려보자.

도메인 모델 분리

리팩토링에서 가장 중요한 전환점은 도메인 모델을 별도의 models/ 디렉토리로 분리한 것이었다.

기존 코드에서는 EQUIPMENT_LABELS, TIME_SLOTS 같은 비즈니스 상수가 컴포넌트 파일 상단에 선언되어 있었다. Room이나 Reservation의 타입도 서버 핸들러(_tosslib/server/types.ts)에만 존재하고, 클라이언트 코드에서는 any에 가까운 상태로 사용되고 있었다.

// models/equipment.ts
export const EQUIPMENT_LABELS = {
  tv: 'TV', whiteboard: '화이트보드', video: '화상장비', speaker: '스피커',
} as const;
 
export type Equipment = keyof typeof EQUIPMENT_LABELS;
export const ALL_EQUIPMENT = Object.keys(EQUIPMENT_LABELS) as Equipment[];

// models/reservation.ts
export interface Room {
  id: string;
  name: string;
  floor: number;
  capacity: number;
  equipment: Equipment[];
}
 
export interface Reservation {
  id: string;
  roomId: string;
  date: string;
  start: string;
  end: string;
  attendees: number;
  equipment: Equipment[];
}

도메인 모델 분리가 왜 중요한가? 비즈니스 로직이 UI 컴포넌트에 종속되어 있으면, 해당 로직을 변경할 때 컴포넌트의 렌더링 로직까지 함께 들여다봐야 한다. 반면 models/ 디렉토리에 독립적으로 존재하면, 비즈니스 규칙의 변경이 UI와 분리된 채로 이루어질 수 있다. 물론 완벽한 분리란 현실적으로 어렵지만, 최소한 "이 로직은 여기 있을 것이다"라고 예측할 수 있는 구조를 만드는 것이 핵심이다.

도메인 모델을 분리했다면, 이제 UI는 얼마나 가벼워질 수 있을까?

컴포넌트 해체 작업

ReservationStatusPage

이 작업이 가장 극적인 변화를 만들어낸 커밋이자 시간을 많이 소요했다. 385줄의 모놀리식 컴포넌트를 다음과 같이 분리했다.

ReservationStatusPage/
├── index.tsx                    # 페이지 레벨
└── components/
    ├── DateSelector.tsx         # 날짜 선택 UI
    ├── ReservationTimeline.tsx  # 타임라인
    └── MyReservation.tsx        # 내 예약 목록 + 취소

분리 기준은 "이 코드가 독립적으로 의미를 가지는가" 였다. 타임라인 시각화는 날짜에 따른 예약 데이터를 받아 그리드를 그리는 독립적인 관심사다. 내 예약 목록은 사용자의 예약 데이터를 조회하고 취소하는 독립적인 관심사다. 이들이 한 파일에 있을 이유는 없었다.

분리 후 index.tsx는 조율자(orchestrator) 역할만 하게 되었다. 상태 관리, 메시지 표시, 하위 컴포넌트 조합을 담당할 뿐, 실제 데이터 페칭이나 렌더링 디테일은 하위 컴포넌트에 위임했다.

RoomBookingPage

예약 페이지도 동일한 원칙으로 분리했다.

RoomBookingPage/
├── index.tsx                    # 페이지 레벨
├── components/
│   ├── BookingFilter.tsx        # 날짜, 시간, 인원, 장비, 층 UI
│   └── AvailableRoomList.tsx    # 예약 가능 방 목록
└── hooks/
    └── useBookingParams.ts      # URL searchParams 기반 상태 관리

이 과정에서 한 가지 흥미로운 선택이 있었다. 초기에는 react-hook-form + zod를 도입해서 폼 유효성 검증을 시도했다. 그런데 최종적으로는 이를 제거하고 커스텀 훅 useBookingParams로 대체했다. 이 결정에 대해서는 뒤에서 더 자세히 이야기하겠다.

여기까지 읽으면 자연스럽게 떠오르는 질문이 하나 있다. 과연 어디까지 추상화해야 할까?

추상화의 적정선

이 섹션이 필자가 이번 모의고사에서 가장 많이 고민한 부분이다.

중첩 조건문, 어디까지 풀어야 할까

방 예약 가능 여부를 판단하는 로직에는 여러 조건이 결합되어 있다. 수용 인원이 충분한지, 필요한 장비가 있는지, 선호 층수가 맞는지, 시간이 겹치지 않는지. 원본 코드에서는 이 모든 조건이 하나의 filter 콜백 안에 인라인으로 작성되어 있었다.

필자는 이를 models/roomFilter.ts로 추출하면서, 각 조건을 이름이 있는 함수로 분리했다.

const isEnoughCapacity = (room: Room, attendees: number) => room.capacity >= attendees;
const hasRequiredEquipment = (room: Room, equipment: Equipment[]) =>
  equipment.every(eq => room.equipment.includes(eq));
const isOnPreferredFloor = (room: Room, floor: number | null) =>
  floor === null || room.floor === floor;
const hasNoTimeConflict = (room: Room, reservations: Reservation[], date: string, start: string, end: string) =>
  !reservations.some(reservation => reservation.roomId === room.id && reservation.date === date && reservation.start < end && reservation.end > start);
 
export function filterAvailableRooms(rooms: Room[], reservations: Reservation[], params: Params): Room[] {
  return rooms
    .filter(room =>
      isEnoughCapacity(room, params.attendees) &&
      hasRequiredEquipment(room, params.equipment) &&
      isOnPreferredFloor(room, params.floor) &&
      hasNoTimeConflict(room, reservations, params.date, params.startTime, params.endTime)
    )
    .sort((a, b) => {
      if (a.floor !== b.floor) return a.floor - b.floor;
      return a.name.localeCompare(b.name);
    });
}

여기서 핵심은 추상화할 수 있는 이름이 명확한 경우에만 함수로 분리했다는 점이다. isEnoughCapacity, hasRequiredEquipment 같은 이름은 구현을 보지 않아도 무엇을 하는지 예측할 수 있다. 만약 이름이 processRoomConditions처럼 모호해질 수밖에 없다면, 그 추상화는 오히려 읽는 사람에게 인지 부하를 줄 수 있다.

물론 이것이 정답이라는 의미는 아니다. 다만 필자의 판단 기준은 "이 함수 이름만 보고 동작을 예측할 수 있는가?" 였다. 예측 가능하다면 추상화하고, 그렇지 않다면 인라인으로 두는 것이 오히려 가독성에 도움이 된다고 생각했다.

searchParams vs form state

예약 필터 상태를 어디에 둘 것인가도 상당히 고민한 부분이었다. 원본 코드에서는 useState로 각 필터 값을 관리하면서, useEffect로 URL searchParams와 동기화하고 있었다.

// 원본: useState + useEffect 동기화 방식
const [date, setDate] = useState(searchParams.get('date') || formatDate(new Date()));
const [startTime, setStartTime] = useState(searchParams.get('startTime') || '');
 
// ... 6개의 개별 상태
useEffect(() => {
  const params: Record<string, string> = {};
  if (date) params.date = date;
 
  // ... 모든 상태를 searchParams에 동기화
  setSearchParams(params, { replace: true });
}, [date, startTime, endTime, ...]);

필자는 처음에 react-hook-form + zod를 도입해서 폼으로 관리하는 방식을 시도했다. 하지만 결국 이를 제거하고 searchParams를 단일 진실 공급원(Single Source of Truth)으로 사용하는 useBookingParams 훅으로 대체했다.

// useBookingParams: searchParams가 곧 상태
export function useBookingParams() {
  const [searchParams, setSearchParams] = useSearchParams();
 
  const params = useMemo<BookingParams>(() => ({
    date: searchParams.get('date') || formatYYYYMMDD(new Date()),
    startTime: searchParams.get('startTime') || '',
    // ...
  }), [searchParams]);
 
  const updateParam = useCallback(<K extends keyof BookingParams>(key: K, value: BookingParams[K]) => {
    setSearchParams(prev => {
      // 기존 파라미터 병합 후 업데이트
      return result;
    }, { replace: true });
  }, [setSearchParams]);
 
  return { params, updateParam };
}

이 결정의 핵심 근거는 "상태가 별개로 움직이는 것이 적합하지 않다" 는 판단이었다. useState와 searchParams가 각각 상태를 가지면, 동기화 시점에 따라 불일치가 발생할 수 있다. 반면 searchParams만을 상태로 사용하면, URL이 곧 애플리케이션 상태가 되어 동기화 문제 자체가 사라진다. 사용자가 URL을 공유하면 동일한 필터 상태가 재현되는 것은 덤이다.

다른 참가자의 후기에서도 비슷한 고민을 발견할 수 있었다. "URL searchParams를 단일 진실 공급원으로 통일했다", "개별 필터 props를 하나의 filter 객체로 통합하는 접근을 택했다." 표현 방식은 다르지만, "흩어진 상태를 하나의 개념으로 묶어야 한다" 는 문제 인식은 동일했다.

안정성

Suspense와 ErrorBoundary

컴포넌트 구조가 확정된 후에 에러/로딩 처리를 추가했다. 순서가 중요한 이유는, 경계(Boundary)를 어디에 설정할지는 컴포넌트 트리가 결정된 후에야 판단할 수 있기 때문이다.

react-error-boundary 라이브러리를 활용하여, 각 독립적인 데이터 페칭 단위마다 ErrorBoundary와 Suspense를 감쌌다. 타임라인이 실패해도 내 예약 목록은 정상적으로 보여야 하고, 그 반대도 마찬가지이기 때문이다.

{/* 각 영역이 독립적으로 에러/로딩을 처리 */}
<ErrorBoundary FallbackComponent={ErrorFallback} resetKeys={[date]}>
  <Suspense fallback={<Loading message="예약 현황을 불러오는 중..." />}>
    <ReservationTimeline date={date} />
  </Suspense>
</ErrorBoundary>
 
<ErrorBoundary FallbackComponent={ErrorFallback}>
  <Suspense fallback={<Loading message="내 예약을 불러오는 중..." />}>
    <MyReservation onCancel={handleCancel} />
  </Suspense>
</ErrorBoundary>

Query Key 중앙 관리

리팩토링 과정에서 쿼리 훅을 분리하다 보니, query key가 여러 파일에 분산되는 문제가 생겼다. mutation의 onSuccess에서 invalidation할 때 어떤 key를 써야 하는지 추적하기 어려워진 것이다.

@lukemorales/query-key-factory를 도입하여 쿼리 키를 중앙에서 관리하도록 변경했다.

// queries/queryKeys.ts
export const roomKeys = createQueryKeys('rooms', {
  list: { queryKey: null, queryFn: () => remotes.getRooms() },
});
 
export const reservationKeys = createQueryKeys('reservations', {
  list: (date: string) => ({ queryKey: [date], queryFn: () => remotes.getReservations(date) }),
  my: { queryKey: null, queryFn: () => remotes.getMyReservations() },
});

이렇게 하면 useSuspenseQueries({ queries: [roomKeys.list, reservationKeys.list(date)] }) 형태로 사용할 수 있어, 쿼리 키와 페칭 함수가 항상 함께 이동한다. 또한 route 경로도 PATHS 상수로 추출하여, 문자열 하드코딩을 제거했다.

출제자의 의도는 무엇이었을까

리팩토링을 마치고 나서, 필자는 한 발 물러서서 생각해보았다. 이 모의고사가 평가하고자 한 것은 무엇이었을까?

다른 참가자들의 후기를 읽으며 흥미로운 공통점을 발견했다. 거의 모든 후기에서 "코드는 읽는 것이 아니라 예측하는 것이다" 라는 문장이 등장했다. 우리의 뇌는 코드를 한 줄 한 줄 해석하는 것이 아니라, 경험에서 쌓인 패턴을 기반으로 예측하며 읽는다는 것이다. 그리고 그 예측이 어긋날 때 인지 부하가 급격히 증가한다.

이 관점에서 보면, 모의고사가 평가하는 것은 단순한 코딩 능력이 아니라 "동료가 읽을 코드를 얼마나 예측 가능하게 만들 수 있는가" 라는 협업 역량인 것이다. (출제자와 동료의 마음을 읽는 것이야말로 진정한 소프트웨어 엔지니어의 역량일지도 모른다)

다른 참가자들의 후기들을 살펴보니, "남이 작성한 코드를 이해하는 것은 쉽지 않다", "인터페이스를 먼저 설계하는 것이 중요하지만, 방대한 기존 코드 앞에서는 그 접근이 흔들릴 수 있다" 는 내용이 공감이 되었다. 필자 역시 비슷한 경험을 했다. 기존 코드가 이미 동작하고 있으면, 그 구조를 합리화하려는 유혹이 생긴다. "이미 돌아가는 코드인데 굳이?"라는 생각 말이다. 하지만 모의고사의 핵심은 바로 그 유혹을 넘어서, "이 코드를 내가 아닌 다른 누군가가 읽었을 때 얼마나 빨리 파악할 수 있는가, 본인의 인지로 문제를 판단하고 해결해나갈 수 있는지" 를 기준으로 판단하는 것이었다.

리팩토링에서 배운 것

리팩토링 순서가 결과를 좌우한다. 바깥(인프라)에서 안쪽(UI)으로 진행하는 것이 중간에 꼬이지 않는 안전한 경로였다. 유틸과 도메인 모델이 정리된 상태에서 컴포넌트를 분리하니, 각 컴포넌트가 무엇에 의존하는지가 명확했다.

추상화의 판단 기준은 "이름"이다. 함수나 변수로 추출했을 때 그 이름이 동작을 설명할 수 있다면 추상화할 가치가 있다. 이름이 모호해질 수밖에 없다면, 인라인이 오히려 나은 선택일 수 있다.

상태의 위치가 곧 아키텍처다. 같이 이동해야 하는 상태는 같은 곳에 두어야 한다. useState와 searchParams를 동기화하는 것보다, searchParams 하나만을 진실 공급원으로 사용하는 것이 구조적으로 더 건강하다.

마무리

과제를 마치고 2명의 동료와 이야기를 나눠보았다. 혼자 코드를 들여다볼 때는 보이지 않던 것들이, 대화를 통해 생각을 풀어나가는 과정에서 드러나기 시작했다. 필자가 당연하다고 넘겼던 구조적 선택에 "왜 그렇게 했어?"라는 질문이 들어오는 순간, 미처 의식하지 못했던 판단의 빈틈이 보이는 것이다.

AI가 코드 작성과 리뷰에 드는 시간을 획기적으로 줄여주고 있는 것은 사실이다. 하지만 그럼에도 코드 리뷰와 데일리 미팅이 여전히 중요하다고 생각하는 이유가 바로 이런 경험에 있다. AI는 코드의 정합성을 검증해줄 수 있지만, "네가 놓친 관점은 이거야" 라고 짚어주는 것은 결국 같은 맥락을 공유하는 동료의 몫이다. 내가 보지 못한 부분에 대한 발견, 그리고 그 발견을 통한 프로덕트의 안정화. 이것이 협업의 본질이 아닐까.

문제를 풀어나가는 과정속에 코드를 작성에는 정답은 없다. 같은 모의고사를 풀었던 다른 참가자들도 각자 다른 경로를 택했고, 각자의 근거를 가지고 있었다. 중요한 것은 "왜 이렇게 짰는가"에 대해 설명할 수 있는 것이다. 이 글을 읽는 분들도 한 번쯤 자신의 코드를 처음 보는 사람의 시선으로 바라보기를 권한다. 그 시선 하나가 코드의 품질을 결정하는 가장 강력한 기준이 될 수 있을 것이다.

필자는 프론트엔드 개발을 하면서 "이 로직을 어디까지 분리해야 하지?", "이 컴포넌트를 어떤 단위로 쪼개야 하지?"라는 고민을 수도 없이 해왔다. 처음에는 단순히 공통된 부분을 뽑아내면 그게 추상화라고 생각했다. 반복되는 코드를 함수로 만들고, 비슷한 컴포넌트의 공통점을 추출해서 하나로 합치는 것. 그런데 이렇게 만들어진 코드가 시간이 지나면서 오히려 손대기 어려운 괴물이 되어가는 경험을 몇 번 하고 나니, 추상화라는 것에 대해 다시 생각해보게 되었다.

이 글에서는 추상화의 본질이 무엇인지, 그리고 프론트엔드 개발에서 추상화를 어떻게 활용해야 좋은 코드를 만들 수 있는지에 대해 필자가 고민해온 내용들을 정리해보려 한다.

추상과 추상화, 이 단어가 의미하는 것

본격적인 이야기에 앞서, "추상"과 "추상화"라는 단어가 프로그래밍에서 정확히 무엇을 의미하는지 짚고 넘어가려 한다. 이 두 단어는 비슷해 보이지만 성격이 꽤 다르다.

**추상(Abstract)**은 상태이자 속성이다. "이것은 추상적이다"라고 말할 때, 그것은 구체적인 세부사항이 생략되어 있고 핵심적인 개념만 남아있는 상태를 뜻한다. Java나 TypeScript에서 abstract 키워드가 붙은 클래스나 메서드가 바로 이런 의미이다. 아직 구체적인 구현이 채워지지 않은, 본질적인 형태만 정의된 미완성의 설계도인 것이다.

**추상화(Abstraction)**는 과정이자 행위이다. 복잡한 대상에서 핵심적인 특징만 남기고 불필요한 세부사항을 제거하여 단순화하는 과정 자체를 말한다. 중요한 것은, 추상화는 "대충 뭉뚱그리는 것"이 아니라 각 수준에서 정확하게 역할을 정의하는 행위라는 점이다.

일상에서 "추상적"이라는 말은 흔히 "모호하다"는 뉘앙스로 쓰인다. 하지만 프로그래밍에서의 추상화는 정반대이다. Edsger Dijkstra는 이렇게 말한 적이 있다.

"추상화의 목적은 모호해지는 것이 아니라, 절대적으로 정확할 수 있는 새로운 의미 수준을 만드는 것이다."

MIT의 John V. Guttag도 비슷한 맥락에서 이렇게 정의했다.

"추상화의 본질은 주어진 맥락에서 관련 있는 정보를 보존하고, 관련 없는 정보를 잊는 것이다."

결국 추상과 추상화를 구분해서 이해하면 이렇다. 추상은 "핵심만 남은 상태"이고, 추상화는 "핵심만 남기는 과정"이다. 우리가 코드를 설계할 때 하는 일은 바로 이 추상화, 즉 복잡한 구현에서 핵심적인 인터페이스만 남기고 나머지를 감추는 과정인 것이다.

그렇다면 이런 추상화가 프로그래밍에서 왜 필요한 걸까?

추상화는 왜 필요한가

추상화가 프로그래밍에서 필요한 근본적인 이유는 의외로 단순하다. 더 복잡한 것을 만들기 위해서이다.

우리가 매일 사용하는 React만 해도 그렇다. 컴포넌트 하나를 렌더링하기 위해 내부적으로는 Virtual DOM 생성, 재조정(Reconciliation), 실제 DOM 조작이라는 복잡한 과정이 일어난다. 하지만 우리는 그런 걸 신경 쓰지 않고 JSX를 작성하면 된다. React가 이 복잡한 과정을 추상화해주었기 때문이다.

// 이 한 줄 뒤에는 VDOM 생성, diffing, DOM 패치라는 복잡한 과정이 숨어있다.
// 하지만 우리는 그걸 몰라도 UI를 만들 수 있다.
<UserProfile name="jihoon" />

예전에는 Webpack을 직접 설정하는 것이 프론트엔드 개발자의 일상이었지만, 지금은 Next.js나 Vite 같은 프레임워크가 번들링 설정을 추상화해버렸다. 덕분에 우리는 번들러의 내부 동작을 몰라도 애플리케이션을 개발할 수 있게 되었고, 그 시간에 비즈니스 로직이나 사용자 경험 같은 더 고차원적인 문제에 집중할 수 있게 되었다.

결국 추상화의 핵심 가치는 이것이다. 복잡한 것을 감추어 단순하게 보이도록 만들고, 각자가 자신의 영역에만 집중할 수 있게 해주는 것. 이 덕분에 우리는 혼자서 모든 것을 이해하지 않아도 점점 더 거대하고 복잡한 소프트웨어를 만들어낼 수 있게 된 것이다.

그렇다면 추상화가 이렇게 좋은 것이라면, 무조건 많이 하면 좋은 걸까?

추상화의 본질은 맥락을 줄여주는 것이다

많은 개발자들이 추상화를 "공통된 부분을 추려내는 것"이라고 인식하고 있다. 틀린 말은 아니지만, 이것은 추상화를 수행하는 기법 중 하나일 뿐 추상화의 본질을 설명해주지는 못한다.

필자가 생각하는 추상화의 본질은 **"코드를 읽는 사람이 알아야 할 맥락을 적절한 수준으로 줄여주는 것"**이다.

간단한 예시를 보자.

type Order = { id: string; status: "pending" | "completed"; amount: number };
 
const orders: Order[] = [
  { id: "a", status: "pending", amount: 10000 },
  { id: "b", status: "completed", amount: 5000 },
  { id: "c", status: "completed", amount: 8000 },
];
 
let total = 0;
for (let i = 0; i < orders.length; i++) {
  if (orders[i].status === "completed") {
    total += orders[i].amount;
  }
}

이 코드를 읽는 개발자는 반복문의 초기화·조건·증감을 파악하고, 인덱스로 원소에 접근하고, 조건을 확인해 분기하고, 외부의 누적 변수가 어떻게 갱신되는지까지 전부 머릿속에 담아야 한다. 정작 이 코드가 하려는 일은 **"완료된 주문들의 합계를 구한다"**는 한 문장인데, 그 한 문장을 이해하기 위해 네 가지 다른 맥락을 동시에 끌어안고 있는 셈이다.

const total = orders
  .filter((order) => order.status === "completed")
  .reduce((sum, order) => sum + order.amount, 0);

filter와 reduce라는 추상화 덕분에 개발자는 "완료된 주문만 골라낸다"와 "금액을 누적한다"는 두 가지 의도만 따라가면 된다. 인덱스 관리, 누적 변수의 선언과 갱신이라는 맥락은 코드 표면에서 사라졌다.

여기서 한 걸음 더 나아갈 수도 있다.

const total = sumCompletedOrders(orders);

이제 코드를 읽는 사람은 이 계산이 배열 순회를 통해 이루어진다는 사실조차 알 필요가 없다. "완료된 주문들의 총액을 구한다"는 비즈니스 의도만 남아있을 뿐이다. 코드가 어떻게(How) 계산되는지가 아니라 무엇을(What) 계산하는지에 집중할 수 있게 된 것이다.

이 관점에서 보면, 우리가 매일 작성하는 React 코드도 수많은 추상화의 조합이라는 사실을 알 수 있다.

import { css } from "@emotion/css";
import { format } from "date-fns";
 
const TodayHeader = () => {
  const now = new Date(); // Date 객체 생성이라는 복잡한 과정을 추상화
  const formatted = format(now, "yyyy-MM-dd"); // 날짜 포맷팅 로직을 추상화
 
  return (
    <h1
      className={css`
        font-size: 1.8rem;
      `}
    >
      {" "}
      {/* CSS-in-JS 처리 과정을 추상화 */}
      Today is {formatted}
    </h1> // React.createElement를 추상화
  );
};
 
// 그리고 위 모든 것을 다시 추상화
<TodayHeader />;

만약 emotion, date-fns, react의 내부 코드가 전부 이 컴포넌트 파일에 펼쳐져 있다면 어떨까? 어디서부터 읽어야 할지, 어떤 부분이 비즈니스 로직이고 어떤 부분이 라이브러리 코드인지 구분하기 어려울 것이다. 추상화가 각 영역의 맥락을 적절히 감춰주었기 때문에 우리는 "오늘 날짜를 보여준다"는 본질에만 집중할 수 있는 것이다.

그렇다면 실제로 코드를 설계할 때, 추상화를 어떤 방향으로 접근해야 할까?

추상화 수준이 높다, 낮다는 것

추상화를 이야기할 때 빠질 수 없는 개념이 **추상화 수준(Level of Abstraction)**이다. 코드의 추상화 수준이 "높다" 혹은 "낮다"는 것은 도대체 무슨 뜻일까?

추상화 수준이 낮은 코드는 컴퓨터가 수행하는 구체적인 절차에 가까운 코드이다. 문자열을 직접 파싱하고, 인덱스로 배열을 순회하고, 바이트를 조작하는 것. 어떻게(How) 동작하는지가 적나라하게 드러나 있다.

추상화 수준이 높은 코드는 비즈니스 도메인이나 문제 영역의 언어로 표현된 코드이다. checkout(cart), approveRequest(id), publishArticle(draft) 같은 것. 무엇을(What) 하는지가 드러나 있고, 어떻게 하는지는 감춰져 있다.

Robert C. Martin은 Clean Code에서 이 개념을 **"함수당 하나의 추상화 수준(One Level of Abstraction per Function)"**이라는 원칙으로 정리했다. 하나의 함수 안에 높은 수준과 낮은 수준의 코드가 섞여 있으면, 읽는 사람은 "이게 핵심 로직인가, 아니면 세부 구현인가?"를 매 줄마다 판단해야 하기 때문이다.

실제 코드로 보면 이 문제가 명확해진다.

// 추상화 수준이 뒤섞인 함수
async function registerUser(name: string, email: string, password: string) {
  // 높은 수준: 입력 검증
  if (!name || !email) throw new Error("Invalid input");
 
  // 낮은 수준: 이메일 정규식 직접 검사
  const emailRegex = /^[A-Za-z0-9+_.-]+@(.+)$/;
  if (!emailRegex.test(email)) throw new Error("Invalid email");
 
  // 낮은 수준: 비밀번호 해싱 직접 구현
  const encoder = new TextEncoder();
  const data = encoder.encode(password);
  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
  const hashedPassword = btoa(
    String.fromCharCode(...new Uint8Array(hashBuffer)),
  );
 
  // 높은 수준: 사용자 저장
  const user = { name, email, password: hashedPassword };
  await userRepository.save(user);
 
  // 높은 수준: 환영 이메일 발송
  await sendWelcomeEmail(user);
}

이 함수를 읽는 사람은 "사용자 등록 흐름"이라는 높은 수준의 맥락을 따라가다가, 갑자기 정규식 패턴과 해시 버퍼 조작이라는 낮은 수준의 맥락으로 끌려 내려간다. 그러다 다시 userRepository.save라는 높은 수준으로 점프한다. 이렇게 추상화 수준이 오르락내리락하면, 읽는 사람의 머릿속도 함께 오르락내리락하게 된다.

같은 함수를 추상화 수준을 맞춰서 다시 작성하면 이렇게 된다.

// 추상화 수준이 일관된 함수
async function registerUser(name: string, email: string, password: string) {
  validateInput(name, email);
  const hashedPassword = await hashPassword(password);
  const user = createUser(name, email, hashedPassword);
  await userRepository.save(user);
  await notificationService.sendWelcomeEmail(user);
}

모든 문장이 같은 높이의 추상화 수준에서 이야기하고 있다. 이메일 검증이 어떤 정규식을 쓰는지, 비밀번호 해싱이 어떤 알고리즘을 쓰는지는 각각의 하위 함수가 책임진다. 이 함수를 읽는 사람은 오직 "사용자 등록의 전체 흐름"이라는 하나의 맥락에만 집중하면 된다.

Martin은 이것을 **"내리막 규칙(The Stepdown Rule)"**이라고도 부른다. 코드를 위에서 아래로 읽을 때, 마치 신문 기사처럼 위에는 큰 그림이, 아래로 내려갈수록 세부사항이 나와야 한다는 것이다.

Kent Beck도 Smalltalk Best Practice Patterns에서 동일한 원칙을 Composed Method 패턴으로 제시했다.

"프로그램을 하나의 식별 가능한 작업을 수행하는 메서드들로 나누고, 하나의 메서드 안의 모든 연산은 같은 추상화 수준에 있어야 한다."

결국 이 모든 이야기가 하나로 귀결된다. 하나의 함수는 하나의 추상화 수준에서만 이야기해야 한다. 이것만 지켜도 코드의 가독성은 눈에 띄게 달라진다.

그렇다면 추상화의 방향은 어떻게 잡아야 할까? 구체적인 것에서 시작해야 할까, 추상적인 것에서 시작해야 할까?

공통점 추출이 아닌, 부품의 조립으로 생각하기

OOP에서 흔히 말하는 "구체적인 것들의 공통점을 뽑아내어 추상적인 것을 정의하라"는 가이드라인이 있다. 이 접근법 자체가 틀린 것은 아니지만, 필자는 이 방식에 너무 얽매이면 현재의 요구사항에 갇힌 설계를 만들어낼 위험이 있다고 생각한다.

예를 들어보자. 요구사항에 A, B, C라는 버튼이 있고, 세 버튼 모두 파란색 둥근 모양이며 차이점은 라벨 텍스트뿐이라고 하자.

// 공통점을 뽑아낸 설계
const BlueRoundButton = ({ label }: { label: string }) => {
  return <button className="blue round">{label}</button>;
};

현재 요구사항은 완벽하게 충족된다. 그런데 며칠 뒤 기획자가 말한다.

"B 버튼의 색상을 변경할 수 있게 해주세요."

이 순간 BlueRoundButton이라는 이름부터 어색해진다. 색상 prop을 추가하면 되긴 하지만, 애초에 "파란색 둥근 버튼"이라는 구체적인 공통점에서 출발한 설계가 변경에 취약했던 것이다. (이 정도는 양반이다. 현실에서는 "버튼을 둥글게 말고 네모로 바꿔주세요"가 날아온다)

이런 상황이 반복되다 보면 자연스럽게 깨닫게 되는 것이 있다. 구체적인 요구사항에서 공통점을 뽑아내는 방식은, 추상화된 결과물마저도 현재의 요구사항만을 반영하게 되기 쉽다는 것이다.

그래서 필자가 선호하는 접근은 반대 방향이다. 구체적인 것에서 추상을 뽑아내는 것이 아니라, 추상적인 부품들을 먼저 생각하고 이것들을 조립하여 구체적인 것을 만드는 방식이다.

토스트 알림 컴포넌트를 만든다고 생각해보자. 처음 요구사항은 단순하다. "저장이 완료되면 하단에 짧은 안내 메시지를 띄워주세요." 공통점 추출 방식으로 접근하면 이렇게 된다.

// 현재 요구사항의 공통 특성에서 출발한 설계
type ToastProps = {
  message: string;
  hasAction?: boolean;
  actionLabel?: string;
  onAction?: () => void;
};
 
const Toast = ({ message, hasAction, actionLabel, onAction }: ToastProps) => (
  <div className="toast">
    <span>{message}</span>
    {hasAction && <button onClick={onAction}>{actionLabel}</button>}
  </div>
);

현재 요구는 완벽히 다뤄진다. 그런데 며칠 뒤 기획자가 "성공 / 경고에 따라 왼쪽에 아이콘을 넣어주세요"라고 말한다. hasIcon, iconName이 추가된다. 곧이어 "업로드 진행률 바가 붙은 토스트도 필요해요"라는 요구가 날아온다. progress prop이 또 하나 늘어난다. 이 과정을 몇 번 반복하고 나면 Toast는 열 개가 넘는 props를 가진 채, 이 조합은 되고 저 조합은 안 되는 숨겨진 규칙까지 암기해야 하는 컴포넌트가 된다. (그리고 대개 그 규칙은 주석으로도 남지 않는다)

애초에 **"토스트는 이런 모양이어야 한다"는 현재 시점의 구체적 상(像)**에서 출발한 설계가 변경에 취약했던 것이다.

부품 조립 방식으로 접근하면 이야기가 달라진다.

// 부품을 조립하는 설계
const Toast = ({ children }: PropsWithChildren) => (
  <div className="toast">{children}</div>
);
 
Toast.Icon = ({ name }: { name: "check" | "warn" | "info" }) => {
  /* ... */
};
Toast.Message = ({ children }: PropsWithChildren) => <span>{children}</span>;
Toast.Action = ({
  children,
  onClick,
}: PropsWithChildren<{ onClick: () => void }>) => (
  <button onClick={onClick}>{children}</button>
);
Toast.Progress = ({ value }: { value: number }) => {
  /* ... */
};
 
// 필요한 부품만 골라 조립한다
<Toast>
  <Toast.Message>저장되었습니다</Toast.Message>
</Toast>;
 
<Toast>
  <Toast.Icon name="check" />
  <Toast.Message>업로드 완료</Toast.Message>
  <Toast.Action onClick={undo}>실행 취소</Toast.Action>
</Toast>;
 
<Toast>
  <Toast.Progress value={0.4} />
  <Toast.Message>파일 전송 중...</Toast.Message>
</Toast>;

"토스트는 무언가를 담는 얕은 컨테이너"라는 변하지 않는 본질과, "그 안에 무엇이 담기는가"라는 변하기 쉬운 구체가 분리되었다. 이제 Toast 내부를 건드리지 않고도 새로운 부품을 얼마든지 추가하거나, 기존 부품을 새로운 조합으로 배치할 수 있다. prop 조합의 유효성 규칙도 사라진다. 단순히 넣고 싶은 것을 넣으면 되는 것이다.

물론 경험이 많은 개발자라면 "처음부터 IoC로 설계하면 되는 거 아니냐"고 할 수 있다. 맞는 말이다. 하지만 그런 판단이 가능한 이유는 과거에 수많은 삽질을 통해 "어디가 변경되기 쉬운 부분인지"에 대한 감각이 쌓였기 때문이다. (쉽게 말해 짬바다)

이런 감각이 아직 부족한 상황이라면, "이 기능은 어떤 부품들로 이루어져 있고, 각 부품은 어떻게 조립되어야 하는가"라는 질문에서 출발하는 것이 변경에 열린 설계를 만들어내기 훨씬 수월하다.

여기까지 읽으면 자연스럽게 떠오르는 질문이 하나 있다. 그렇다면 부품을 어떤 기준으로 나누고, 외부에 어떻게 표현해야 할까?

좋은 추상화를 위한 세 가지 원칙

1. 표현에 대해 고민하기

추상화된 모듈의 가장 중요한 덕목은, 소스코드를 까보지 않아도 동작을 유추할 수 있어야 한다는 것이다. Kent Beck은 이것을 "의도를 드러내는 이름(Intention-Revealing Name)" 패턴이라고 불렀고, 이름을 간결하게 지을 수 없다면 추상화 자체를 다시 고민해봐야 한다고 말했다.

우리가 이를 위해 사용할 수 있는 도구는 크게 두 가지다. 이름과 타입이다.

// 이름과 타입만으로 동작을 유추할 수 있는 함수
function addDays(date: Date, amount: number): Date;
 
// 도대체 뭘 하는 건지 알 수 없는 함수
function add(a: any, b: any): any;

addDays는 이름만 봐도 날짜에 일수를 더한다는 것을 알 수 있고, Date를 받아서 Date를 반환한다는 타입 정보가 이를 뒷받침한다. 내부에서 Date.prototype.getDate를 어떻게 다루는지 같은 구현 세부사항은 몰라도 된다.

반면 add(a: any, b: any): any는? 뭘 더하는 건지, 결과가 뭔지 전혀 감을 잡을 수 없다. 결국 소스코드를 까봐야만 사용할 수 있게 되고, 추상화의 장점을 잃어버리는 것이다.

이때 이름을 짓는 방식 자체가 추상화 수준을 반영한다는 점에 주목할 필요가 있다. 프로그래밍에서 함수 이름은 대체로 동사 + 명사 조합으로 이루어지는데, 어떤 동사를 선택하느냐에 따라 그 함수가 어느 수준의 추상화에서 동작하는지가 드러난다.

추상화 수준이 낮은 쪽에서 자주 쓰이는 동사들이 있다. parse, encode, decode, serialize, read, write, push, pop 같은 것들이다. 이 단어들은 데이터의 물리적인 변환이나 자료구조의 직접적인 조작을 암시한다.

중간 수준에서는 fetch, save, load, validate, convert, transform 같은 동사들이 등장한다. 기술적인 동작이지만, 그 동작의 의도가 어느 정도 드러나는 수준이다.

추상화 수준이 높은 쪽에서는 register, checkout, approve, publish, submit 같은 동사들이 쓰인다. 이 단어들은 비즈니스 도메인의 언어이다. 내부에서 어떤 기술적 절차가 일어나는지는 전혀 드러나지 않고, 사용자의 행위나 비즈니스 프로세스만이 표현된다.

// 낮은 수준: 기술적 동작이 드러남
function parseJSON(text: string): object;
function encodeBase64(data: Uint8Array): string;
 
// 중간 수준: 의도가 드러나되 기술적 맥락이 남아있음
function fetchUserById(id: string): Promise<User>;
function validateEmail(email: string): boolean;
 
// 높은 수준: 비즈니스 의도만 드러남
function registerUser(form: RegistrationForm): Promise<User>;
function approveLeaveRequest(requestId: string): Promise<void>;

Robert C. Martin은 Clean Code에서 이에 대해 **"짧고 수수께끼 같은 이름보다 길고 서술적인 이름이 낫다"**고 말했다. 또한 **"하나의 개념에는 하나의 단어를 사용하라"**는 원칙도 제시했는데, 같은 맥락의 동작에 fetch, retrieve, get을 혼용하면 읽는 사람이 "이 셋이 다른 동작인가?"라고 혼란을 겪게 되기 때문이다.

이 원칙은 React 컴포넌트와 훅의 네이밍에도 그대로 적용된다.

// 컴포넌트: 추상화 수준에 따라 이름의 구체성이 달라진다
<Button />                // 낮은 수준: 범용 UI 프리미티브
<SearchInput />           // 중간 수준: UI + 맥락이 결합
<SubmitOrderButton />     // 높은 수준: 비즈니스 의도가 이름에 담김
 
// 이벤트 핸들러: on*은 선언적 인터페이스, handle*은 구현
<Form onSubmit={handleSubmit} />           // on = 외부에 노출하는 이름
const handleSubmit = (data: FormData) => { // handle = 내부 구현의 이름
  await registerUser(data);
};
 
// 훅: use + 목적을 나타내는 이름
const user = useAuth();                    // 인증 상태를 관리하는 훅
const [items, setItems] = useCartItems();  // 장바구니 항목을 관리하는 훅
const { isOpen, toggle } = useModal();     // 모달 상태를 관리하는 훅

Jeff Atwood는 Coding Horror에서 Manager라는 접미사의 문제를 지적한 적이 있다. UrlManager라는 이름은 URL을 풀링하는 건지, 검증하는 건지, 생성하는 건지 전혀 알 수 없다. UrlBuilder, UrlValidator, UrlPool처럼 구체적인 역할을 드러내는 이름이 훨씬 낫다. 이름이 모호하다는 것은, 그 모듈의 책임 자체가 모호하다는 신호일 수 있는 것이다.

결국 좋은 이름이란 그 코드가 어떤 추상화 수준에서 동작하는지를 읽는 사람에게 즉시 알려주는 이름이다.

2. 입력의 자유도를 의도적으로 설계하기

추상화된 모듈을 설계할 때 자주 마주치는 고민이 있다. "기능을 어디까지 열어줄 것인가?"이다. 이 결정에 따라 모듈을 사용하는 개발자의 경험이 크게 달라진다.

// 기능이 닫힌 컴포넌트
const Button = ({ children }: PropsWithChildren) => {
  return <button>{children}</button>;
};
 
// 기능이 완전히 열린 컴포넌트
const Button = (props: ComponentProps<"button">) => {
  return <button {...props} />;
};

첫 번째 버튼은 children만 받을 수 있다. onClick도, type도, disabled도 설정할 수 없다. 대신 사용하는 사람은 고민할 것이 없다.

두 번째 버튼은 button 엘리먼트의 모든 속성을 받을 수 있다. 자유도가 높지만, 사용하는 입장에서는 수십 개의 prop 중 뭘 써야 할지 고민하게 된다. 필자는 이런 상황을 **"컴포넌트가 개발자에게 고민을 강요한다"**고 표현한다.

정답은 없다. 다만 모듈의 목적과 사용자에 따라 적절한 수준을 찾아야 한다. 디자인 시스템의 기본 버튼이라면 제한된 Props로 일관성을 지키는 것이 나을 수 있고, 범용 유틸리티 컴포넌트라면 유연하게 열어주는 것이 나을 수 있다.

비유하자면 신디사이저와 디지털 피아노의 차이와 같다. 오디오 전문가에게는 파형을 직접 다룰 수 있는 신디사이저가 적합하지만, 단순히 피아노를 치고 싶은 사람에게는 기능이 제한된 디지털 피아노가 더 좋은 경험을 제공한다. 사용자가 원리를 알 필요가 없는 상황에서 넓은 입력을 제공하면 혼란만 가중되고, 반대로 다양한 상황에 대응해야 하는데 입력을 제한하면 사용처가 막혀버린다.

3. 추상화의 단위를 적절하게 유지하기

추상화의 단위, 즉 "어디까지를 하나의 모듈로 묶을 것인가"도 중요한 고민이다.

프론트엔드에서 흔히 보는 안티패턴 중 하나는 Custom Hook의 과도한 추출이다.

// 이 훅은 단 하나의 컴포넌트에서만 사용된다
const useUserProfileData = () => {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
 
  useEffect(() => {
    fetchUser()
      .then(setUser)
      .finally(() => setLoading(false));
  }, []);
 
  return { user, loading };
};

하나의 컴포넌트에서만 사용되는 로직을 굳이 훅으로 분리하면, 오히려 코드를 읽는 사람이 두 개의 파일을 오가며 맥락을 파악해야 한다. 추상화가 맥락을 줄여주기는커녕 늘려버린 것이다.

반대로, 하나의 훅에 너무 많은 것을 담는 것도 문제다.

// 관련 없는 관심사가 하나의 훅에 뒤섞여 있다
const useEverything = () => {
  const auth = useAuth();
  const theme = useTheme();
  const analytics = useAnalytics();
  const toast = useToast();
  // ...20줄 더
  return { auth, theme, analytics, toast /* ... */ };
};

이런 "God Hook"은 테스트하기 어렵고, 한 가지를 수정하면 관련 없는 부분까지 영향을 받을 수 있다.

React 공식 문서에서도 이런 말을 하고 있다.

"처음부터 Hook으로 분리해야 한다는 압박을 느낄 필요는 없다."

추상화의 적절한 단위를 판단하는 기준은 **"이 분리가 코드를 읽는 사람의 맥락을 실제로 줄여주는가?"**이다. 만약 분리한 결과 오히려 맥락이 분산되어 파악이 어려워진다면, 그 추상화는 아직 때가 아닌 것이다.

가능하면 추상화를 하지 말자

여기까지 읽으면 "그래서 추상화를 언제 해야 하는 건데?"라는 질문이 남을 수 있다. 필자의 생각은 이렇다. 기본 전제는 추상화를 하지 않는 것이어야 한다.

이것은 필자만의 생각이 아니다. Sandi Metz는 이렇게 말했다.

"중복은 잘못된 추상화보다 훨씬 비용이 싸다. (Duplication is far cheaper than the wrong abstraction.)"

명확한 추상화 신호가 보이지 않는 한, 코드를 있는 그대로 두는 것이 잘못된 추상화를 만들어놓고 나중에 풀어헤치는 것보다 저점이 높다. 잘못된 추상화가 만들어지는 과정은 대략 이렇다.

1. 코드 A와 코드 B에서 비슷한 패턴이 보인다.
2. "DRY 원칙이니까 공통 함수로 뽑아야지!" 하고 추상화한다.
3. 코드 C에서도 비슷한 패턴이 보여서 같은 함수를 쓰되, 약간 다른 동작을 위해 매개변수를 하나 추가한다.
4. 코드 D, E에서도 사용하게 되면서 조건문과 매개변수가 계속 늘어난다.
5. 이제 이 함수는 모든 곳에서 사용되지만, 아무도 건드리기 두려워하는 코드가 된다.

// 처음에는 단순했던 함수가...
const formatUserName = (user: User) => `${user.firstName} ${user.lastName}`;
 
// 요구사항이 추가될 때마다 매개변수가 늘어나고...
const formatUserName = (
  user: User,
  includeMiddleName?: boolean,
  format?: "full" | "short" | "initials",
  locale?: string,
  honorific?: boolean,
) => {
  if (format === "initials") {
    /* ... */
  }
  if (includeMiddleName && user.middleName) {
    /* ... */
  }
  if (honorific && locale === "ko") {
    /* ... */
  }
  // ...끝없는 분기
};

이런 상황에 빠졌다면, Sandi Metz가 제안하는 해법은 명확하다. 추상화된 코드를 각 사용처에 다시 인라인하고, 각 사용처에서 불필요한 코드를 제거한 뒤, 깨끗해진 상태에서 진짜 공통점이 보이면 그때 다시 추상화한다. "가장 빠른 전진은 뒤로 돌아가는 것이다."

그렇다면 추상화를 해야 할 때는 언제인가? 필자가 느끼는 추상화 신호는 대략 이런 것들이다.

• 일관성이 깨지고 있다. 똑같은 로직인데 어떤 컴포넌트에서는 인라인으로, 어떤 컴포넌트에서는 별도 함수로 분리되어 있다. 같은 계산 로직이 사방에 흩어져 있다.
• 내부 구조가 외부에 불필요하게 노출되고 있다. 외부에서 알 필요 없는 구현 세부사항을 호출자가 일일이 다루고 있다.
• 자신의 행위가 계속 노출되고 있다. 모듈이 자기 내부의 절차를 숨기지 못하고, 사용하는 쪽에서 그 절차를 그대로 따라가야 한다.

문제는, 이런 신호를 감지하는 것 자체는 대체로 단순한데, 실제로는 이 신호를 무시하고 더 "중요한" 요구사항을 충족하는 데 집중하게 되기 쉽다는 것이다. 일정에 쫓기거나 기능 구현에 몰두하다 보면, "일단 동작하니까 나중에 정리하자"가 되고, 그 나중은 좀처럼 오지 않는다.

여기서 한 가지 더 중요한 것은 일관된 추상화 기준을 유지하는 것이다. 코드베이스 안에서 같은 종류의 로직이 어떤 곳에서는 인라인으로, 어떤 곳에서는 함수로, 또 어떤 곳에서는 커스텀 훅으로 분리되어 있다면, 새로 코드를 읽는 사람은 "이 차이에 의도가 있는 건가?"라고 혼란스러워한다. 추상화를 하든 안 하든, 팀 안에서 기준이 일관되어야 한다.

Joel Spolsky가 2002년에 제시한 **"새는 추상화의 법칙(The Law of Leaky Abstractions)"**도 이 맥락에서 기억해둘 만하다.

"모든 비자명한 추상화는 어느 정도 새는 법이다."

TCP는 불안정한 네트워크를 안정적인 연결처럼 보이게 추상화하지만, 케이블이 끊기면 그 추상화는 깨진다. React는 UI 업데이트를 선언적으로 추상화하지만, 리렌더링 최적화를 위해서는 결국 내부 동작을 이해해야 한다. 완벽한 추상화는 존재하지 않기에, 추상화를 할 때는 **"이 추상화가 깨졌을 때 사용자가 대응할 수 있는가?"**까지 고민해야 한다.

Spolsky의 말처럼 "추상화는 우리의 작업 시간을 절약해주지만, 학습 시간을 절약해주지는 않는다."

추상화는 체화의 영역이다

필자가 동료와 추상화에 대해 이야기를 나눈 적이 있는데, 그때 나온 이야기가 인상 깊었다. 추상화 신호를 감지하고, 적절한 시점에 적절한 수준으로 분리하는 것은 결국 감각의 영역이라는 것이다.

물론 앞서 이야기한 원칙들, 추상화 수준을 맞추고, 이름을 잘 짓고, 입력 자유도를 설계하는 것은 분명히 중요하다. 하지만 실제로 코드를 작성하는 순간에 이런 원칙들을 하나하나 떠올리면서 "이걸 분리할까 말까?"를 따지는 접근은 오히려 흐름을 깨뜨릴 수 있다. 마치 시합 중에 잽을 던질 때 팔꿈치 각도를 의식하면 오히려 타이밍을 놓치는 것처럼, 코드를 짤 때도 추상화는 의식적 판단이 아닌 자연스러운 감각에서 나와야 하는 것이다.

코드를 쭉 짜다가 뭔가 거부반응이 올라오는 순간이 있다. "이 로직이 여기 있으면 안 되는 것 같은데", "이 컴포넌트가 너무 많은 것을 알고 있는 것 같은데"라는 느낌. 그 느낌이 바로 추상화 신호이고, 이것을 자연스럽게 감지하고 반응할 수 있는 것이 체화인 것이다.

다만 이 감각은 하루아침에 만들어지지 않는다. 수많은 패턴을 학습하고, 다양한 코드를 읽고, 직접 삽질을 겪어봐야 비로소 **"이건 분리해야 할 것 같은데"**라는 감이 자연스럽게 올라오기 시작한다. 나중에 동료가 "왜 이걸 분리했어?"라고 물었을 때, "이건 OO이기 때문에 분리했어"라고 자연스럽게 설명할 수 있다면 그것이 체화된 것이다.

어떤 분야든 마찬가지인 것 같다. 외워서 잘하려고 하면 오히려 판단이 어려워지고, 결국은 큰 흐름만 가져가되 디테일은 자연스럽게 채워져야 한다. 그리고 그 자연스러움은 결국 평소에 쌓아놓은 다양한 패턴과 경험에서 나오는 것이다.

마치며

정리하면, 프로그래밍에서 추상화란 복잡한 것을 감추어 단순해 보이게 만들고, 코드를 읽는 사람이 필요한 맥락에만 집중할 수 있게 해주는 행위이다.

좋은 추상화를 위해 기억해둘 것들을 다시 한번 짚어보자면 이렇다.

• 기본 전제는 추상화를 하지 않는 것이다. 명확한 신호가 보일 때 비로소 분리하자.
• 하나의 함수는 하나의 추상화 수준에서만 이야기하자.
• 이름과 타입으로 동작을 충분히 표현하여, 소스코드를 까보지 않아도 사용할 수 있게 만들자.
• 입력의 자유도를 모듈의 목적과 사용자에 맞게 의도적으로 설계하자.
• 잘못된 추상화 위에 덧붙이기보다, 풀어헤치고 다시 시작하는 용기를 갖자.
• 그리고 이 모든 것을 의식하지 않아도 자연스럽게 나올 수 있도록 다양한 패턴을 체화하자.

물론 이 글에서 필자가 이야기한 것이 정답은 아니다. 추상화의 적절한 수준은 비즈니스 상황, 팀의 구성, 프로젝트의 성격에 따라 달라질 수 밖에 없다. 다만 한 가지 변하지 않는 것이 있다면, 추상화의 궁극적인 목적은 사람이 이해하기 좋은 코드를 만드는 것이라는 점이다.

이 글을 읽는 분들도 각자의 코드베이스에서 "이 추상화가 정말 맥락을 줄여주고 있는가?"라는 질문을 한번 던져보시길 바란다. 그 질문 하나만으로도 코드를 바라보는 시각이 조금은 달라질 것이라 생각한다.

참고한 자료

이 글은 여러 원전과 선행 아티클에서 많은 영감을 받았다. 직접 인용한 구절의 출처와, 사고의 틀을 잡는 데 도움이 된 글들을 함께 남긴다.

• Evan Moon, 「추상, 그리고 추상화」 — 이 글의 전체적인 구성과 **"추상화는 맥락을 줄이는 것"**이라는 관점은 이 아티클에서 가장 큰 영향을 받았다.
• 박서진, 「좋은 코드를 위한 나의 선택, 신중하게 코드 작성하기」 (Toss SLASH 23 발표) — "공통점 추출"이 아닌 **"부품의 조립"**으로 접근하라는 관점은 이 발표에서 출발했다.
• Robert C. Martin, Clean Code — "함수당 하나의 추상화 수준", Stepdown Rule, 의도를 드러내는 네이밍 규칙(2장, 3장).
• Kent Beck, Smalltalk Best Practice Patterns — Composed Method / Intention-Revealing Name 패턴.
• Sandi Metz, “The Wrong Abstraction” — 잘못된 추상화가 쌓여가는 과정과, 풀어헤치고 다시 시작하는 용기에 대한 논의.
• Joel Spolsky, “The Law of Leaky Abstractions” — 완벽한 추상화는 존재하지 않는다는 관점.
• Edsger W. Dijkstra, "The Humble Programmer" (1972 ACM Turing Award Lecture) — 추상화의 목적에 대한 고전적 정의.
• John V. Guttag, Introduction to Computation and Programming Using Python — 추상화의 본질에 대한 정의.
• React 공식 문서, Reusing Logic with Custom Hooks — Hook 분리의 압박에 대한 가이드.
• Jeff Atwood, “i-shall-call-it-somethingmanager” (Coding Horror) — Manager 접미사의 모호함에 대한 지적.

예전에는 내가 필요한 부분만 빠르게 훑고 넘어가는 일이 많았지만, 최근엔 코어 기능을 응용하거나 프로젝트에 직접 접목해야 하는 일이 잦아지면서 더 깊이 있는 이해와 분석이 필요해졌다.

아마 이 글을 읽는 많은 분들이 단순한 관심을 넘어서, 실질적인 오픈소스 기여를 목표로 하고 있으리라 생각한다. 그래서 이 글은 단순한 맞춤법 수정이나 사소한 버그 픽스가 아닌, 내가 어떤 방식으로 AI를 활용해 오픈소스의 핵심 로직을 탐구하고, 구조적 이해를 바탕으로 한 의미 있는 기여를 위한 접근 방법에 초점을 맞추어 정리해보려 한다.

AI를 활용한 오픈소스 탐구

“AI를 활용해 오픈소스를 공부한다” 고 하면 막연하게 느껴질 수 있다.

실제로 오픈소스 코드베이스는 방대한 경우가 많아, 모든 내용을 AI에게 학습시키는 건 아직 불가능하다. (가벼운 용량의 라이브러리면 가능할 것 같지만..)

그래서 나는 아래와 같은 계획을 세우고, 그에 맞춰 AI를 효율적으로 활용해왔다.(요즘 claude 4.0 모델을 사용하고있다.)

1. 관심 있는 라이브러리를 포크한다.

2. 핵심 로직 한 부분을 선정하고, 관련 로직들을 탐색하며 구조를 파악한다.

3. 명확한 구조를 보여주는 로직을 중심으로 AI에게 학습시킨다.

4. AI와의 대화를 통해 메인테이너의 설계 의도와 방향성을 추정한다.

5. 이해되지 않는 부분은 질문 리스트로 정리한다.

6. 각 질문에 대해 가설을 세우고, AI에게 흐름 설명을 요청하며 검증한다.

7. 이해한 내용이 타당하다면, 실제 개선 PR을 위한 브랜치를 만들어 기여를 시도한다.

이렇게 보면 이해가 되지 않는 부분이 많을 것 같아 가장 최근에 공부하고 기여해본 TanStack Route 라우팅 탐색 최적화 (PR #4513) 을 가지고 이야기해보겠다.

관심 있는 라이브러리 선택해보자.

가장 먼저 관심 가지고 깊게 분석해볼 라이브러리를 선택하는 것이 첫 번째다. 나는 다음의 기준을 우선순위로 두었다.

• 회사에서 실제로 사용 중인 라이브러리
• 사내에서 사용하는 버전과 공식 최신 버전 간의 간극이 큰 라이브러리
• 유사 기능을 가진 다른 라이브러리들과의 구조 비교가 가능한 라이브러리

나는 최근 회사에서 react-router를 사용하고 있었는데, 앞으로 tanstack-router로 교체해보는 것이 더 나은 선택일 수 있을지 고민하게 되었다. 계기는 우연히 본 Reddit 게시글이었다. (물론 새로운 라이브러리가 나올때마다 쉽게 바꾸고 대응할 수 없겠지만, 관심은 가져야한다고 생각한다.)

• React Router v7이 Remix의 구조적 영향을 크게 받았으며, 점점 Remix 중심의 방향으로 진화하고 있다는 내용.
• React Router v7과 TanStack Router의 차이점이 무엇인가요?

이 내용이 궁금해져 react-router의 버전 히스토리를 살펴보았고, 그 대안으로 떠오른 tanstack-router가 눈에 들어왔다. 보다 명확한 비교와 판단을 위해 tanstack/router 레포지토리를 포크하고 본격적인 분석을 시작했다.

TanStack 라이브러리 성장 속도가 엄청 빠르다.
 
처음 tanstack/query 만 서버상태관리를 위해 사용했다.
 
그러다 정신차리고 보니, router, store, db, form 등 라이브러리들을 쏟아내고있다.
 
모든 라이브러리를 알지 못해도 현재 사용하고있는 아래 라이브러리의 코어 로직은 탐구해봐야겠다고 생각했다.
 
- react-router
- 클라이언트 상태관리 라이브러리(zustand, jotai, recoil)
- react-hook-form

핵심 로직 한 부분을 선정하고, 공부해보자.

처음부터 코어 로직들을 다 살펴보겠다는 목표를 가지고 탐구를 시작했다.

하지만 코어 로직이 상당히 비대하고, 깊은 이해도를 가지기에는 많은 시간이 소비가 되어 원래의 목표를 달성하기 전에 절망에 빠져버렸다. 그래서 내가 중점으로 살펴볼 핵심 로직을 정하고 그 로직을 중심으로 연결된 로직들을 살펴보는 방식을 취했다.

내가 tanstack-router를 살펴보려 했을 때 가장 먼저 궁금했던 것은 성능 병목과 구조적 효율성이었다. 특히 다음 세 가지가 주요 관찰 포인트였다.

• TanStack Router는 성능 측면에서 얼마나 최적화되어 있을까?
• 기존 react-router와 비교했을 때, 제공하는 메서드나 API의 호환성이 충분할까?
• 실무에서 마이그레이션을 진행한다면 비용이 얼마나 들까?

이 중 가장 먼저 확인해야 할 것은 라우팅 트리 매칭 방식이었고, 이에 관련된 matchRoutesInternal을 집중적으로 탐색하게 되었다.

학습한 로직을 중심으로 AI에게 학습시킨다.

코드를 분석하다 보니 matchRoutesInternal 함수가 라우트 트리를 전부 순회하며 매칭하는 구조로 작성되어 있다는 점이 눈에 띄었다.

메인 로직과 연관된 함수들을 보았다. getMatchedRoutes 함수를 통해 경로 매칭하고 내부에 파라미터 파싱 및 검증, 검색 파라미터 검증 로직들이 서로 연관되어있다.

이 방식은 트리 깊이가 깊거나, 라우트 수가 많아질수록 성능 병목이 발생할 수 있는 구조라고 생각해보았다. 그래서 학습한 로직과 matchRoutesInternal 함수와 연관된 로직들을 AI 에게 학습시켜보았다.

메인테이너의 설계 의도와 방향성 파악하기

기존 로직을 AI와 함께 분석하며, 왜 현재 구조가 이런 방식으로 설계되었는지, 이 구조가 어떤 문제를 풀기 위해 존재하는지 메인테이너의 입장에서 고민해보았다.

단순히 “어떤 부분이 효율적이고, 어떤 부분이 비효율적이다”라고 판단하는 것이 아니라, 이 방식이 왜 선택되었고, 어떤 조건에서 성능 문제가 생기는지를 파악하는 것이 중요했다.

Claude 4.0 모델 을 아래처럼 활용해보았다.

이해되지 않는 부분은 질문 리스트로 정리해보기

분석 도중 다음과 같은 의문이 생겼다.

• “왜 전체 트리를 매번 순회하는가?”
• “자식 노드를 가지는 경우에도 모든 경로를 전수조사해야 하는 구조인가?”
• “이 방식은 현재 구조에서 최적의 선택일까, 아니면 단순한 구현상의 디폴트인가?”

이러한 질문 리스트를 바탕으로, 더 효율적인 구조로 대체할 수 있을지 가설을 세우며 AI 를 활용해 더 깊이있게 matchRoutesInternal 을 탐구해보았다.

가설 검증해보기

이후 나는 다음과 같은 가설을 세웠다.

매번 트리를 순회하지 않고, Trie 기반의 정적 라우트 매칭 구조로 바꾼다면 성능을 개선할 수 있지 않을까?

이 아이디어를 바탕으로 RouteTrie 구조를 새로 작성하고, 기존의 matchRoutesInternal 로직을 대체해 성능을 개선하는 방안을 구현했다.

또한 자체적으로 테스트 파일을 구성해 가설을 검증했고, 아래 개선사항을 확인했다. (내가 작성했던 테스트는 PR 올리는 과정에 삭제했는데, 메인테이너가 추가 테스트 파일을 작성해 PR 에 추가해줬다.)

• A → B → A와 같이 이전 페이지로 빠르게 돌아오는 경우, A 페이지 데이터가 캐시에 유지
• 동시 네비게이션 시 사용자가 링크를 빠르게 여러 번 클릭할 때 발생할 수 있는 데이터 손실을 방지
• 페이지 데이터를 새로 고치는 도중 다른 페이지로 이동했다가 돌아올 때 캐시된 데이터가 유지

검증이 옳다면 실제 개선 PR을 위한 브랜치를 만들어보자.

검증 결과 성능 병목이 실제로 존재했고, 내가 제안한 구조가 이를 개선할 수 있다는 확신이 들었다. 이에 개선된 로직을 기반으로 PR을 올렸고, 메인테이너가 이를 받아들여 최종적으로 공식 반영되었다.

마무리하며

이 글에서는 어떤 코드를 어떻게 수정했는지를 설명하려는 것이 아니다. 더 중요한 것은, 이런 흐름으로 오픈소스를 탐구하고 이해하는 방식이 나한테 많은 도움이 되었다는 것을 알려주고 싶었다.

처음에는 단순한 의문에서 출발했지만, 핵심 로직을 직접 탐색하고, AI를 활용해 설계를 파악하며, 작은 가설을 세워 검증하고, 실제 기여까지 연결해보는 일련의 과정을 거치면서 단순한 학습 이상의 깊이 있는 이해와 개발자로서의 성장을 경험할 수 있었다.

이런 방식으로 지난 2개월 동안 여러 오픈소스 라이브러리들을 분석하고, 그 중 일부는 실제로 개선하며 기여의 보람도 느낄 수 있었다.

• TanStack DB refetch 로직 개선 (PR #122)
• TanStack Store selector 의존성 개선 (PR #198)

그리고 요즘 제일 많이 탐구하고 있는 toss 의 오픈소스들

오픈소스를 분석해보는 것은 엄청 어렵고, 거창한게 아니다.

내가 사용하는 도구가 왜 이렇게 만들어졌는지에 대한 ‘왜’에서 출발해, 작은 질문과 개선 의지를 가지고 접근해본다면 누구나 만들고 기여해볼 수 있다고 생각한다.

이 글을 작성한 이유는 혼자 공부하다 보니 너무 어렵고, 이게 적합한 개선인지 이 부분에 대해 다른 사람들은 어떻게 생각하는지 궁금해졌기 때문이다.

누군가와 함께 특정 라이브러리의 구조를 뜯어보고, 토론하고, 분석하며 함께 기여하는 과정을 만들 수 있다면 얼마나 좋을까?

그래서 아래에 해당하면 연락한번 주셔도 좋겠습니다! 같이 공부하고 분석해보면 좋을것같다. 링크드인, jihoon7705@gmail.com 또는 댓글로 연락 주셔도 좋습니다!

• 오픈소스에 관심 있지만 어디서 시작할지 막막한 분
• 프론트엔드 직무에 밀접한 코어 라이브러리에 흥미 있는 분
• 구조와 설계에 대한 분석을 좋아하는 분
• AI를 활용한 오픈소스 학습법에 관심 있는 분

이번 글에서는 실무에서 as const의 활용 사례를 중심으로 활용과 원리까지 깊이 있게 다뤄보려 한다.

as const

as const는 TypeScript에서 값을 리터럴 타입으로 고정(literal narrowing) 하기 위한 단언문이다.

const button = "primary"; // 타입: string
const button = "primary" as const; // 타입: "primary"

배열이나 객체에 쓰면 해당 구조를 읽기 전용(readonly)으로 만들면서 각 요소의 타입을 리터럴로 고정한다.

const status = ["idle", "loading"] as const;
// 타입: readonly ["idle", "loading"]

이처럼 값을 변경 불가능한 상수로 명시하고, 타입도 좁게 고정되도록 만드는 것이 핵심이다.

TanStack Query – query key 안정성 확보

const queryKey = ["user", userId] as const;
useQuery({ queryKey, queryFn });

여기서 as const를 쓰지 않으면 queryKey는 (string | number)[]로 추론되어 타입 안정성이 떨어진다.

반면 as const를 쓰면 queryKey가 정확히 readonly ["user", string]이 되어, query key가 고정된 식별자로 취급되고, 캐싱/비교/인밸리데이션에서도 더 안정적으로 작동한다.

React Router – 라우팅과 같은 객체 구조의 키값 고정

const router = createBrowserRouter([
  { path: "/home", element: <HomePage /> },
  { path: "/about", element: <AboutPage /> }
] as const);

React Router는 내부적으로 라우트 배열을 순회하면서 타입을 추론하려고 하기 때문에, as const로 선언해주면 각 path의 리터럴 값("/home", "/about")을 정확히 추론할 수 있다.

이를 통해 라우트 기반 자동완성, 타입 기반 네비게이션 제어가 가능해진다.

as const를 쓰지 않아야 할 때

무조건 좁은 타입이 좋은 건 아니다. 다음과 같은 경우는 오히려 as const를 쓰지 않는 것이 낫다.

let status = "idle" as const;

이렇게 하면 status는 절대 다른 문자열을 가질 수 없기 때문에, 동적으로 상태를 변경해야 하는 경우엔 적절치 않다.

function update(type: "create" | "delete") {}
update("create" as const); // 불필요

함수 시그니처가 리터럴 타입을 받는 경우, 이미 문자열 리터럴을 넣으면 타입이 자동으로 좁혀진다. 명시적 as const는 오히려 코드만 장황해질 수 있다.

내부 동작 원리 – const assertion의 타입화

TypeScript에서 as const는 해당 값은 readonly로 간주되고, 가능한 한 좁은 타입으로 리터럴 추론을 한다.

const obj = { a: 1, b: "x" } as const;
// 타입: { readonly a: 1; readonly b: "x"; }

이는 일종의 const assertion으로, 값 자체는 JS에서 변하지 않지만 타입도 함께 고정시키는 것이 특징이다.

배열, 객체, 튜플 등에 모두 적용 가능하며, 유형 안정성(type safety)을 명시적으로 선언하는 수단이다.

기술적으로 조금 더 깊게 들어가면

TypeScript는 as const를 만나면 해당 값 전체를 readonly로 처리하며, 내부 속성 하나하나를 리터럴 타입으로 고정한다.

이는 내부적으로 const T: { readonly a: 1, readonly b: "x" } 같은 형태로 변환된다.

제네릭 함수에서 as const된 인자를 넘기면, 추론된 타입이 정확한 리터럴 형태로 유지되기 때문에 타입 제한, 자동완성, 추론 정확도가 크게 향상된다.

특히 readonly 튜플로 바뀐다는 점에서, 배열 기반 추론(예: query key 등)에 매우 큰 이점을 준다.

const key = ["user", 1] as const;
type Key = typeof key; // readonly ["user", 1]

만약 as const 없이 선언했다면 Key는 (string | number)[]이 되었을 것이고, 타입 정합성은 깨졌을 것이다.

enum과 비슷하지만 다르다.

as const와 enum은 모두 값 집합을 고정시키는 용도로 사용되지만, 아래와 같은 차이가 있다.

type Mode = (typeof MODES)[number];
 
const MODES = ["light", "dark"] as const;
 
enum ModeEnum {
  Light = "light",
  Dark = "dark",
}

대부분의 경우 불필요한 런타임 비용 없이 타입만 고정하고 싶을 때는 as const가 더 효율적이다.

이번 글에서는 회사에서 useCallback을 사용하던 중, 함수 참조에 대한 개념을 간과한 채 디버깅에 시간을 낭비했던 경험을 반성하는 의미로 내용을 정리해보았다.

useCallback

React 컴포넌트가 리렌더링될 때, 함수 선언도 함께 다시 실행된다. 이는 매번 새로운 메모리 참조를 가진 함수 객체가 생성된다는 뜻이다. 이렇게 생성된 함수가 useEffect의 의존성 배열(deps)에 포함되어 있다면, 의도치 않은 재실행이 발생할 수 있다. 또 자식 컴포넌트에 props로 해당 함수를 전달할 경우, 참조가 바뀌면서 memoization이 무효화되어 불필요한 리렌더링이 일어날 수 있다.

이때 useCallback은 지정한 deps가 변경되지 않는 한 함수의 참조를 유지해, 불필요한 연산과 리렌더링을 방지할 수 있도록 도와준다.

const memoizedFn = useCallback(fn, deps);

참조(reference)

자바스크립트에서 함수는 객체다. 따라서 다음 두 코드는 완전히 다른 동작을 한다.

const handleClick = useCallback(() => {
  console.log('dd');
}, []);
 
return (
  <>
    <button onClick={handleClick}>1번</button>
    <button onClick={() => handleClick()}>2번</button>
  </>
);

위 코드를 보면, onClick={handleClick}은 useCallback에 의해 메모이제이션된 함수 참조를 그대로 전달한다.

반면, onClick={() => handleClick()}은 렌더링될 때마다 새로운 함수 객체를 생성한다.

즉, useCallback으로 만든 함수를 불필요하게 감싸는 순간, 참조 유지의 이점은 사라진다.

• onClick={handleClick}은 불필요한 리렌더링을 방지할 수 있다. (정상)

• onClick={() => handleClick()}은 useCallback의 이점을 완전히 무효화한다. (잘못된 사용)

자식 컴포넌트에 영향이 있을까?

React는 props가 바뀌었는지를 Object.is()로 비교한다. 따라서 () => handleClick()은 매번 새로운 함수 객체이기 때문에 아래 상황에서는 Child가 매번 리렌더링된다.

<Child onClick={() => handleClick()} />

반면, onClick={handleClick}은 useCallback에 의해 참조가 유지되므로, Child가 리렌더링되지 않는다.

Object.is()

React는 함수형 컴포넌트가 리렌더링될 때 props가 이전과 달라졌는지를 판단하기 위해 Object.is()를 사용한다. 특히 React.memo, useMemo, useCallback 등 메모이제이션 관련 최적화 기법에서 이 비교 방식은 매우 중요한 역할을 한다.

Object.is(value1, value2)는 두 값이 같은 값인지(SameValue 알고리즘) 를 비교하는 JavaScript 내장 함수로, ===와 매우 유사하지만 몇 가지 미묘한 차이가 있다.

NaN === NaN 에서 ===는 false를 반환하지만 Object.is()는 true를 반환한다. 그리고 +0 === -0 에서 ===는 true를 반환하지만 Object.is()는 false를 반환한다.

즉, Object.is()는 보다 정밀한 동일성 비교를 수행하고, NaN, +0, -0 등의 케이스에서도 오동작하지 않도록 설계된 함수다. 그래서 React 에서 Object.is()를 사용하여 props가 이전과 달라졌는지를 판단한다.

브라우저/엔진 관점에서의 최적화

모던 자바스크립트 엔진(V8 등)은 함수 객체를 반복적으로 생성하고 해제하는 과정에서 GC(가비지 컬렉션) 비용이 증가할 수 있다. 특히 다음과 같은 경우에 성능 저하가 발생할 수 있다

• 컴포넌트 리렌더링 시 새로운 함수 객체가 매번 생성되는 경우
• 렌더된 DOM에 이벤트 핸들러가 대량으로 등록되는 경우
• 내부적으로 클로저 환경이 계속해서 새롭게 생성되어 메모리 누수가 발생할 가능성이 있는 경우

이는 브라우저 엔진이 매 렌더마다 생성된 함수를 개별적인 클로저 컨텍스트와 함께 추적해야 하기 때문이다. GC 타이밍이 UI 업데이트와 맞물릴 경우 프레임 드롭이나 UI 랙으로 이어질 수 있다.

그래서 useCallback을 통해 함수 참조를 고정하고, 컴포넌트 외부에서 클로저 생성을 피한 구조를 최적화한다.

그럼 언제 () => fn()을 써도 괜찮을까?

useCallback이 항상 정답은 아니다. 함수 내부에서 최신 props나 상태(state) 를 참조해야 하는 경우, 외부에 고정된 함수를 쓰면 stale closure 문제가 발생할 수 있다.

<button onClick={() => doSomething(id)}>삭제</button>

예를 들어 id가 렌더링 시점에 따라 바뀌는 값이라면, useCallback으로 감싸도 이 id가 stale(오래된 값)일 수 있다.

React 19의 useEvent

React 19 이전에는 ahooks의 useMemoizedFn이 유사한 역할을 수행할 수 있는 방법이 있었다. (적극적으로 사용되지 않았던 것 같다.)

React 19에서는 useEvent 훅이 공식화되었다. 이 훅은 이벤트 핸들러에서 최신 상태나 props를 안정적으로 참조할 수 있도록 돕는다. 내부적으로는 stable reference를 유지하되, 내부 로직에서는 항상 최신 값을 읽도록 구현되어 있다.

결론

디버깅을 하다 보면, 평소에 잘 알고 있다고 생각했던 훅이나 개념들이 실제로는 완전히 이해되지 않았던 부분이라는 걸 깨닫게 된다.

그래서 문제의 명확한 원인을 빠르게 파악하기 위해서는, 익숙한 개념일수록 다시 한번 정확히 이해하고 있는지 점검해보는 태도가 반드시 필요하다는 것을 다시 한번 느꼈다.

참고 자료

• React 공식 문서: Hooks FAQ - useCallback
• V8 엔진의 함수 생성 및 GC 정책: v8.dev

어떤 것부터 시작해야 하지?

프론트엔드 개발자로 일하며, 나는 매일 스스로의 부족함을 마주한다. 그리고 미래를 위해 갖춰야 할 역량은 끝도 없이 쏟아진다.

불안함에 동아리와 스터디를 시작했다. 좋은 동료들을 만난 만큼, 자연스럽게 나를 그들과 비교하게 되었다.

• 어떤 이는 디자인 시스템에 관심이 많아 직접 구축하며 UI 개발에 깊이 몰입한다.
• 또 다른 이는 DevOps와 인프라에 관심을 갖고 Docker와 쿠버네티스를 학습한다.
• 어떤 이는 UX를 넘어 DX를 고민하며 직접 라이브러리를 만들기도 한다.

그들과 나를 비교할수록, 나는 한없이 깊은 심해 속으로 가라앉는다. 불안속에서 허우적대다 문득 정신을 차리고, 하나씩 해보기로 결심했다.

운이 좋게도 나는 빠르게 취업할 수 있었다.

하지만 독학으로 '당장 필요한 기술'만 익혔던 나는 실무에서 기초 실력의 부족함을 크게 느꼈다. 그래서 다시 JavaScript부터 차근차근 공부하기 시작했다.

공부와 실무를 병행하며 사내 프로젝트를 진행하다 보니, 자연스럽게 프로덕트 안정화와 기능 개발에 관심이 생겼다. 오랜 시간 동안 다양한 라이브러리를 도입하고, 아키텍처 구조를 고민하며 컨벤션을 직접 기획했다. 이 모든 것을 바탕으로 대규모 리팩토링을 진행했고, 프론트엔드 안정화를 위해 밤낮을 고민했다.

작은 불편을 줄이기 위해 시작한 일이었지만, 점차 '더 개선할 수 있는 일은 무엇일까?' 를 스스로 묻기 시작했다.

Proof of Concept 기반 DX 개선

작게 시작한 사내 개선은 어느새 내 욕심이 되어 있었고, 그만큼 더 깊은 학습을 필요로 했다. JS조차 끝이 없는 세계지만, 완벽하지 않은 상태에서도 나는 다음 단계(Infra와 DevOps)로 나아갔다.

Docker로 이미지를 만들고, CI/CD 환경을 구성하기 위한 공부를 시작했고, 공부한 내용을 바탕으로 사내에서 PoC를 진행했다. 몇 주간의 노력 끝에 눈에 보이는 성과를 만들어냈지만, 곧 의문이 들기 시작했다.

“이게 정말 효과적인 개선일까? 내가 제대로 해낸 게 맞을까?”

앞서 배포환경에 대한 회고도 진행하지 못한채 새로운 문제들이 생겼다.

사내에서는 반복적인 문법 오류로 인한 이슈들이 끊임없이 발생했고, 각기 다른 개발자들이 일관성 없는 코드를 작성하며, 수정과 에러가 이어졌다.

“이걸 어떻게 줄일 수 있을까?”

그쯤 여러가지 라이브러리를 찾아보았고, 특히 Toss의 es-toolkit를 관심있게 살펴보았다.

그리고 사내에서 사용하는 문법을 통용하는 내부 패키지를 만들어보자는 결정을 내렸다. 그렇게 다시, 또 하나의 시도를 시작했다.

배우고 있는 JS, 성능 최적화, 추상화, 클라우드, 인프라 개념들이 정리가 안된채 머릿속을 휘저었지만, 진행하던 공부를 멈추고 프로젝트를 개발했고, 실사용까지 완료했다.

그 결과, 사내 패키지를 기반으로 코드 작성이 일관되면서 코드 리뷰가 수월해졌고, 개별 함수 단위로 구성된 내부 유틸 패키지를 통해 tree-shaking 부담도 줄었다.외부 라이브러리 의존도를 낮추면서, 신규 프로젝트 투입 시 학습 비용과 초기 에러 발생률도 줄어들었다

표면적으로는 성공이었다. 하지만 조직내에서 내 역할에 대한 검증을 해줄 리더의 부재로, 제대로 검증받을 기회는 없었다.

그래도 내가 문제를 찾고, 주도적으로 도전해볼 수 있다는 자신감 을 얻었다.

물론 여전히 어설프고, 새 개념이 등장하면 어색하고 두려운 나지만, 그 불안은 학습으로 어느 정도 극복할 수 있다는 사실도 함께 깨달았다.

어느덧 3년 차.

프론트엔드라는 직무뿐 아니라, 세상의 모든 직무는 끝없이 배워야 하는 길 위에 있다. 나는 그동안 두 번의 이직 준비를 했다. 한 번은 좋은 결과가 있었고, 지금은 많은 고민 속에 새로운 도전을 진행하고 있다.

두려움 속에서 멈춰도 괜찮다. 계획을 세우는 것도, 무작정 시작하는 것도 좋다. 다만 실패를 두려워해서, 아무것도 하지 않는 것만은 피했으면 좋겠다.

그동안 나는 수많은 책을 사고, 인강을 듣고, 스터디를 운영하고, 클라우드 자격증을 준비하며 시도했다. 그 과정에서 많은 시도들을 끝까지 이어가지 못했다. (물론, 일부는 ‘끝’ 이 어디인지조차 명확하지 않기에 단정짓기도 어렵다.)

그때는 그런 나를 ‘실패했다’ 고 생각했다. 하지만 그건 실패가 아니라, ‘그저 과정이었다’ 는 것을.

SIPE

올해 초, 나는 ‘SIPE’ 라는 동아리 활동을 마무리했다. (물론 DND, DevOcean 등 다양한 동아리 활동도 진행했지만)

그곳에서 멋진 사람들을 만나며 자극받기도 했고, 비교 속에서 열등감을 느끼기도 했다.

동아리는 나에게 큰 동기였고, 주도적으로 스터디와 프로젝트를 운영하며 성장의 체감도 분명했다.

하지만 지나친 의존을 끊기 위해 동아리를 그만두기로 결심했을 때, “혼자서도 잘할 수 있을까?” 하는 불안이 밀려왔다.

그리고 벌써 4개월이 지났다. 코딩 테스트와 TypeScript 공부는 자주 멈췄지만, 코드를 쓰고, 책을 읽고, 아키텍처와 도메인 분리를 고민하며 오픈소스 기여도 해보았다.

그동안 내가 느낀 것들을 정리해보면, 아주 단순하다.

• 무언가를 처음부터 잘하는 사람은 없다.
• 한 가지만 잘하는 것도 좋지만(물론 이 방법이 내가 생각하는 성공의 지름길이겠지만), 필요한 것을 찾아 다양하게 해보는 것도 충분히 멋지다
• 단, 자주 나를 객관화하고, 부족한 점을 정리해보자.
• 그리고 계속해보자. 끈기 있게. 포기하지 말자.

지금 어떤 선택을 하든, 어떤 고민을 하든, 불안한 건 너무나 당연하다.

올해의 절반이 지나가는 이 시점, 도전의 좌절과 빠르게 흘러간 시간에 회의감이 들 수도 있다.

하지만, 그것들은 결코 나쁜 시간이 아니다. 나이키에서 자주 본 문구처럼, Just do it. 그저 해보자.

그러면 언젠가 우리는, 지금보다 훨씬 더 나은 사람이 되어 있을 것이다.

이 글을 마무리 하며

하루를 마칠 때면 스스로에게 이렇게 말한다.

“짧은 시간이지만, 정말 많은 걸 해냈어. 오늘도 수고했어.”

그리고 아침이 되면, 나에게 말한다.

"그만 자고 일어나"

나는 끊임없이 불안을 느끼는 사람이지만, 그만큼 계속 무엇인가 하는 사람이다.

그래. 나는 T 다.

올해 절반을 보내며 스스로에 대한 정리로 글을 마무리 해보겠다.

내가 느끼는 부족함

• 논리적인 대화
• 어려운 코드 읽기
• 프로그래밍 언어, CS 지식
• 한 가지 목표를 끝까지 끌고 가는 끈기
• 비즈니스 도메인 분리 및 아키텍처 설계를 위한 코드 작성 역량

올해 남은 시간 동안 내가 해보고 싶은 일

• 발표 많이 하기
• 오픈 소스 많이 읽고, 생산성 높여주는 라이브러리 주도적 개발해보기
• 코드 리뷰 많이 하기 (부족하지만 코드리뷰 요청 해주시면 열심히 해보겠다..)
• ‘추상화와 분리’ 를 고려해서 구현 많이 해보기 (이런 주제에 관심이 있으시면 언제든지 연락해주세요)
• 건강 챙기기 (제일 중요한데 제일 못한다. 나는 돼지다.)

필자가 React를 처음 접했을 때, "Fiber" 라는 단어는 면접 단골 질문 정도로만 인식되었다. "React의 렌더를 위해 작업 단위를 나눠서 처리"라는 한 줄짜리 정의를 외우고, 그게 전부인 줄 알았다. 하지만 실제로 React의 소스코드를 들여다보기 시작하면서, Fiber가 단순한 개념이 아니라 React 렌더링의 모든 것을 관장하는 런타임 아키텍처라는 사실을 깨닫게 되었다.

그때 React 소스코드를 처음 열었을 때의 충격은 아직도 잊을 수 없다. "이게... 다 뭐지?" 싶었다.

이 글에서는 "Fiber가 뭐예요?"라는 질문에 "작업 단위를 나눠서 처리하는 거요"라고 대답하는 수준을 넘어, Fiber가 왜 탄생했고, 어떻게 설계되었으며, 그 구조가 React의 Concurrent Features를 어떻게 가능하게 만드는지까지 깊이 있게 파헤쳐 보려 한다.

왜 Fiber가 등장했을까?

이 질문에 답하려면 먼저 Fiber 이전의 세상, 즉 React 15까지 사용되던 Stack Reconciler가 어떤 문제를 가지고 있었는지 이해해야 한다.

Stack Reconciler는 이름 그대로 재귀(recursive) 호출 기반의 재조정 엔진이었다. 컴포넌트 트리를 위에서 아래로 재귀적으로 순회하면서, 한 번 렌더링을 시작하면 전체 트리를 끝까지 처리해야만 멈출 수 있었다. 이것은 마치 전화 통화 중에 상대방이 말을 끝낼 때까지 절대 끊을 수 없는 것과 같은 상황이었다. (상대방이 3시간짜리 인생 상담을 시작했는데 중간에 끊을 수 없다고 생각해보라. 끔찍하다.)

Stack Reconciler은 구체적으로 다음과 같은 한계가 있었다.

• 렌더링 중 중단 불가: 모든 트리를 한 번에 처리해야 했으므로, 복잡한 UI에서는 메인 스레드가 수십~수백 밀리초 동안 점유되었다
• 우선순위 개념 부재: 사용자가 버튼을 클릭하든, 백그라운드 데이터가 갱신되든, 모든 업데이트가 동일한 방식으로 처리되었다
• 애니메이션/제스처 대응 어려움: 60fps를 유지하려면 한 프레임당 약 16ms 안에 모든 작업이 끝나야 하는데, 재귀 렌더링은 이를 보장할 수 없었다
• 에러 발생 시 전체 앱 중단: 컴포넌트 트리 어딘가에서 에러가 발생하면 전체 앱이 멈추는 문제가 있었다

이러한 한계를 극복하기 위해 React 팀은 작업을 쪼개고, 우선순위를 매기고, 필요하면 중단하고 재개할 수 있는 새로운 실행 모델을 고민했다. 그리고 그 결과물이 바로 React Fiber인 것이다.

Andrew Clark가 작성한 react-fiber-architecture 문서는 이 설계의 핵심 사상을 담고 있으며, Fiber를 이해하는 데 가장 중요한 참고 자료다. (이 문서를 작성하고 얼마 안 되어 React 팀에 합류한 것으로 보인다.)

Stack vs Fiber

그렇다면 Stack Reconciler와 Fiber Reconciler는 코드 수준에서 어떻게 다른 것일까?

재귀 기반의 Stack Reconciler

function renderComponent(component) {
  const element = component.render();
  element.props.children.forEach(child => renderComponent(child)); // 재귀 호출
}

Stack 방식은 이렇게 자식 컴포넌트를 만나면 즉시 재귀 호출로 들어간다. 이 방식의 문제는 JavaScript의 콜 스택(call stack)에 직접 의존한다는 점이다. 재귀 호출이 깊어지면 콜 스택에 프레임이 쌓이고, 이 모든 프레임이 해소될 때까지 브라우저의 메인 스레드는 다른 일을 할 수 없다.

쉽게 말해, 콜 스택이 비워질 때까지 브라우저는 꼼짝도 할 수 없는 상태가 되는 것이다.

위 영상을 보면 Stack Reconciler가 렌더링하는 동안 메인 스레드가 완전히 블로킹되는 모습을 확인할 수 있다.

반복 기반의 Fiber Reconciler

Fiber는 재귀를 반복(iterative loop) 으로 대체했다. 콜 스택 대신 자체적인 가상 스택을 메모리 위에 구현한 것이다. 각 Fiber 노드가 곧 하나의 "스택 프레임"이 되며, 이 노드들은 JavaScript 객체(힙 메모리)에 존재하기 때문에 언제든 중단하고 나중에 다시 이어갈 수 있다.

function performWork(deadline) {
  while (nextUnitOfWork && deadline.timeRemaining() > 5) {
    nextUnitOfWork = performUnitOfWork(nextUnitOfWork);
  }
  requestIdleCallback(performWork); // 나눠서 실행
}

위 코드는 Fiber의 초기 개념 모델을 보여준다. 핵심은 while 루프 안에서 한 번에 하나의 작업 단위(unit of work)만 처리하고, 시간이 부족하면 루프를 빠져나와 브라우저에게 제어권을 돌려준다는 것이다.

(초기에는 requestIdleCallback을 활용하는 방식이었지만, 실제 React는 이를 사용하지 않는다. 이유는 뒤에서 자세히 다룬다.)

Fiber 방식에서는 렌더링 중에도 사용자 이벤트(버튼 클릭, 타이핑 등)에 즉시 반응할 수 있다. 작업을 잘게 쪼개 실행하기 때문에, 브라우저가 숨 쉴 틈이 생기는 것이다.

두 방식의 차이를 직접 체험해보고 싶다면 여기를 클릭하면 된다. Stack Reconciler와 Fiber Reconciler의 동작 차이를 눈으로 확인할 수 있다.

이것이 바로 Andrew Clark이 문서에서 강조한 Fiber의 핵심 목표다.

• 작업을 일시 중지하고 나중에 다시 돌아올 수 있다
• 서로 다른 유형의 작업에 우선순위를 부여할 수 있다
• 이전에 완료된 작업을 재사용할 수 있다
• 더 이상 필요 없는 작업을 중단할 수 있다

Fiber Node 내부 구조

여기까지 읽으면 자연스럽게 떠오르는 질문이 하나 있다. "그래서 Fiber 노드는 내부적으로 어떻게 생겼는가?"

React 팀은 Fiber의 내부 구현에 대한 공식 문서를 별도로 제공하지 않고 있다. 하지만 Andrew Clark의 react-fiber-architecture 문서와 실제 React 소스코드(ReactFiber.js)를 통해 그 구조를 파악할 수 있다.

Fiber 노드를 필자는 작업 지시서(Work Order) 에 비유하고 싶다. 공장에서 제품을 조립할 때, 각 작업 지시서에는 "이 부품이 어떤 종류인지", "어떤 재료를 사용하는지", "다음에 어떤 작업을 해야 하는지", "우선순위는 어떤지"가 적혀 있다. Fiber 노드도 마찬가지다.

ReactElement와 FiberNode

Fiber를 이해하려면 먼저 ReactElement와 FiberNode를 구분해야 한다. 이 둘은 자주 혼동되지만 전혀 다른 존재다.

// ReactElement — React.createElement()가 반환하는 가벼운 객체
export interface ReactElement {
  type: string | Function; // 문자열(HTML 태그) 또는 함수(컴포넌트)
  props: {
    [key: string]: any;
    children: ReactElement[];
  };
  key: string | null;
  ref: any;
  _owner: FiberNode | null;
}

ReactElement는 UI의 설계도에 불과하다. "이런 컴포넌트를 이런 props로 렌더링해달라"는 요청서일 뿐, 실제 렌더링 로직이나 상태는 담고 있지 않다.

반면 FiberNode는 이 설계도를 바탕으로 React가 내부적으로 생성하는 런타임 작업 단위다. ReactElement에는 없는 tag, stateNode, child/sibling/return, memoizedState, updateQueue, lanes 같은 필드들이 여기에 존재한다.

React가 ReactElement의 type을 보고 FiberNode를 생성할 때, tag 값이 결정된다.

• type이 함수이고 prototype.isReactComponent가 있으면 → tag = ClassComponent(1)
• type이 함수이면 → tag = FunctionComponent(0)
• type이 문자열("div" 등)이면 → tag = HostComponent(5)

tag는 FiberNode의 종류를 나타내는 숫자 상수다. ReactWorkTags.js에 정의되어 있으며, FunctionComponent(0), ClassComponent(1), HostRoot(3), HostComponent(5), HostText(6) 등 약 25가지 이상의 태그가 존재한다. React는 이 tag 값을 기반으로 beginWork에서 어떤 처리 로직을 실행할지 결정하는 것이다.

type은 재조정(reconciliation) 과정에서 핵심적인 역할을 한다. React가 이전 렌더링의 Fiber와 새 엘리먼트를 비교할 때 가장 먼저 확인하는 것이 바로 type이다. (이 값은 ReactElement에서 FiberNode로 그대로 전달된다.)

• 이전에도 div였고 이번에도 div라면, React는 해당 Fiber 노드를 재사용하여 props만 업데이트한다
• 이전에는 div였는데 이번에는 span으로 바뀌었다면, React는 기존 Fiber를 버리고 새 Fiber를 생성한다

key 역시 ReactElement에서 FiberNode로 전달되는 값으로, 주로 리스트(배열) 렌더링 시에 사용된다. key가 없으면 React는 리스트 아이템의 순서가 변경되었을 때 어떤 아이템이 어디로 이동했는지 정확히 알 수 없다. 이로 인해 불필요한 DOM 조작이 발생하거나, 컴포넌트의 내부 상태가 의도치 않게 유지 또는 소실될 수 있다.

child, sibling, return

React Fiber가 재귀 대신 반복을 사용할 수 있는 비밀이 바로 여기에 있다.

function 부모() {
  return [<자식1/>, <자식2/>];
}

child는 컴포넌트의 render가 반환한 첫 번째 자식 요소를 가리킨다. 위 예제에서는 <자식1/>이 해당된다. sibling은 동일한 부모를 가진 다음 형제 요소를 의미한다. <자식1/>의 sibling은 <자식2/>이다. return은 현재 Fiber 노드의 처리가 끝난 뒤 되돌아갈 부모 Fiber를 가리킨다. <자식1/>과 <자식2/>의 return은 모두 부모이다.

이 세 필드가 만들어내는 구조는 단일 연결 리스트(Singly Linked List) 형태의 트리다. 일반적인 트리 구조에서는 자식 배열(children[])을 두는 것이 직관적이지만, Fiber는 의도적으로 이를 피했다.

왜일까? 배열 기반의 자식 구조에서는 순회를 위해 인덱스를 관리해야 하고, 중간에 중단했다가 재개할 때 "어디까지 처리했는지"를 별도로 추적해야 한다. 반면 linked list 구조에서는 현재 노드의 참조만 기억하면 언제든 이어서 순회할 수 있다. 이것이 Fiber가 중단과 재개를 자연스럽게 지원할 수 있는 구조적 기반인 것이다.

React는 이 구조를 기반으로 깊이 우선 탐색(DFS) 순서로 노드를 순회한다. child를 따라 내려가고(beginWork), 리프 노드에 도달하면 sibling을 확인하고, 형제가 없으면 return을 따라 올라가는(completeWork) 방식이다.

pendingProps와 memoizedProps

pendingProps는 해당 Fiber가 처리를 시작할 시점에 전달된 새로운 props를 의미하며, memoizedProps는 이전 렌더링에서 처리가 완료된 이전 props를 나타낸다.

이 두 값이 동일하다면, React는 "이 컴포넌트에는 변경이 없다"고 판단하여 이전 렌더링 결과를 그대로 재사용할 수 있다. 이것이 바로 bailout 최적화의 핵심 메커니즘이다.

마찬가지로 memoizedState는 해당 Fiber의 훅(hooks) 상태를 저장하며, updateQueue는 아직 처리되지 않은 상태 업데이트(setState 호출들)를 연결 리스트로 관리한다.

stateNode

stateNode는 Fiber 노드가 가리키는 실제 인스턴스를 참조한다.

• HostComponent(div, span 등)의 경우: 실제 DOM 노드
• ClassComponent의 경우: 클래스 인스턴스
• HostRoot의 경우: FiberRoot 객체

이 필드는 Fiber의 가상 세계와 브라우저의 실제 DOM을 연결하는 다리 역할을 한다.

더블 버퍼링: current 트리와 workInProgress 트리

Fiber를 이해하는 데 있어 빠뜨릴 수 없는 핵심 개념이 바로 **더블 버퍼링(Double Buffering)**이다.

이 개념을 이해하기 위해 게임 그래픽을 떠올려보자. 게임에서 화면을 그릴 때, 현재 화면에 직접 픽셀을 그리면 반쯤 그려진 프레임이 사용자에게 보이는 화면 깜빡임(tearing) 현상이 발생한다. 이를 방지하기 위해 게임 엔진은 두 개의 버퍼를 사용한다. 하나의 버퍼에 다음 프레임을 완전히 그린 후, 완성되면 화면에 표시되는 버퍼를 한 번에 교체하는 것이다.

React Fiber도 정확히 같은 전략을 사용한다.

currentFiber.alternate === workInProgressFiber;
workInProgressFiber.alternate === currentFiber;

current 트리는 현재 화면에 반영되어 있는 Fiber 트리. 사용자가 보고 있는 UI의 상태를 나타내고, workInProgress 트리는 다음 렌더링을 위해 백그라운드에서 준비 중인 Fiber 트리를 나타낸다.

두 트리는 alternate 속성으로 서로를 참조한다. 모든 변경 작업은 workInProgress 트리에서 수행되며, 작업이 완료되면 root.current = finishedWork 한 줄로 트리가 교체된다. 이전의 workInProgress가 새로운 current가 되고, 이전의 current는 다음 렌더링에서 workInProgress로 재활용되는 것이다.

function createWorkInProgress(current, pendingProps) {
  let workInProgress = current.alternate;
  if (workInProgress === null) {
    // 최초 렌더: 새 Fiber를 생성하고 alternate를 연결
    workInProgress = createFiber(current.tag, pendingProps, current.key, current.mode);
    workInProgress.stateNode = current.stateNode; // DOM 노드는 공유!
    workInProgress.alternate = current;
    current.alternate = workInProgress;
  } else {
    // 재렌더: 기존 alternate를 재사용, effect만 초기화
    workInProgress.pendingProps = pendingProps;
    workInProgress.flags = NoFlags;
    workInProgress.subtreeFlags = NoFlags;
    workInProgress.deletions = null;
  }
  // lanes, child, memoizedState 등을 복사
  workInProgress.childLanes = current.childLanes;
  workInProgress.child = current.child;
  // ...
}

여기서 핵심을 짚어보자. stateNode(실제 DOM 노드)는 current와 workInProgress 사이에서 공유된다. Fiber 객체를 매번 새로 만드는 것이 아니라, 기존 alternate를 재사용하면서 변경된 필드만 업데이트한다. 이 덕분에 매 렌더마다 가비지 컬렉션(GC) 부담 없이 효율적으로 트리를 구성할 수 있는 것이다.

만약 props나 state에 변경이 없다면? 해당 서브트리를 통째로 건너뛰는 bailout 최적화가 가능해진다. 게임의 더블 버퍼링이 프레임 단위의 최적화라면, Fiber의 더블 버퍼링은 컴포넌트 단위의 최적화까지 가능하게 만드는 것이다.

pendingWorkPriority => Lanes

그렇다면 Fiber는 어떻게 "이 작업이 더 중요하다"는 것을 판단하는 것일까?

expirationTime의 한계

초기 Fiber는 pendingWorkPriority라는 숫자 기반의 우선순위를 사용했고, 이후 expirationTime이라는 단일 숫자로 발전했다. 만료 시간이 가까울수록 높은 우선순위를 의미했는데, 이 방식에는 근본적인 한계가 있었다.

단일 숫자로는 "이 업데이트는 A 그룹에 속하고, 저 업데이트는 B 그룹에 속한다"는 식의 유연한 분류가 불가능했기 때문이다. 예를 들어 사용자 입력과 Transition 업데이트가 동시에 발생했을 때, expirationTime 기반에서는 범위(range) 비교로만 분류할 수 있었고, 특정 업데이트만 선택적으로 처리하는 데 한계가 있었다.

Lane

이 문제를 해결하기 위해 Andrew Clark이 PR #18796에서 도입한 것이 Lane 시스템이다.

Lane을 이해하기 위해 고속도로를 떠올려보자. 고속도로에는 여러 차선(lane)이 있고, 각 차선은 서로 다른 용도를 가진다. 1차선은 추월 차선(긴급), 2차선은 주행 차선(일반), 갓길은 비상용이다. 각 차량(업데이트)은 자신의 성격에 맞는 차선에 배정되고, 고속도로 관리 시스템(스케줄러)은 어떤 차선의 차량을 먼저 통과시킬지 결정한다.

React의 Lane도 이와 같다. 각 업데이트에 비트 하나(lane) 를 할당하고, 비트 연산으로 그룹을 만들고 비교하는 것이다.

// 각 업데이트는 하나의 lane(단일 비트)을 가진다
const SyncLane =             /*  */ 0b0000000000000000000000000000010;
const InputContinuousLane =  /*  */ 0b0000000000000000000000000001000;
const DefaultLane =          /*  */ 0b0000000000000000000000000100000;
const TransitionLane1 =      /*  */ 0b0000000000000000000000100000000;
const IdleLane =             /*  */ 0b0001000000000000000000000000000;
 
// 배치(batch)는 여러 비트의 OR 조합이다
const SyncUpdateLanes = SyncLane | InputContinuousLane | DefaultLane;
 
// 특정 lane이 batch에 포함되는지 확인은 단순 비트 연산
const isIncluded = (lane & lanes) !== 0;

총 31개의 lane이 31비트 정수에 들어가도록 설계되어 있는데, 이는 V8 엔진의 SMI(Small Integer) 최적화를 활용하기 위함이다. 31비트 이하의 정수는 V8에서 포인터 태깅으로 처리되어 힙 할당 없이 스택에서 직접 연산할 수 있다. 주요 lane의 우선순위는 낮은 비트일수록 높다.

이 구조 덕분에 React는 비트 연산 한 번으로 어떤 작업을 먼저 처리할지 결정할 수 있게 되었다. getNextLanes() 함수는 pendingLanes에서 가장 높은 우선순위의 lane 그룹을 골라내고, 중단된(suspended) lane은 건너뛰며, 데이터를 받은(pinged) lane은 우선 재시도하는 등의 정교한 스케줄링이 가능해진 것이다.

또한 기아 상태(starvation) 방지를 위해 각 lane에 만료 시간이 부여된다. Sync/InputContinuous는 250ms, Transition은 5000ms가 지나면 expiredLanes에 추가되어 동기적으로 강제 처리된다. 아무리 우선순위가 낮아도 영원히 무시당하지는 않는다는 뜻이다. (우선순위가 낮다고 영원히 무시당하면 그건 우선순위 시스템이 아니라 차별 시스템이다.)

Fiber의 output

여기까지 Fiber의 구조를 살펴봤다면, 이제 궁금해지는 것이 하나 있다. 이 Fiber 노드들이 어떻게 실제 DOM으로 변환되는 것일까?

output은 실제 DOM에 적용될 수 있는 구체적인 DOM 노드 정보를 의미한다. 여기서 중요한 구분이 있다.

// 사용자 정의 컴포넌트 — output 없음
function 아바타() {
  return <img src="profile.jpg" />;
}
 
// 호스트 컴포넌트 — output 생성
<img src="profile.jpg" />
<div className="프로필" />

호스트 컴포넌트(div, span, img 등)만 실제 DOM 노드를 생성한다. 브라우저는 <아바타/>가 뭔지 모른다. 사용자 정의 컴포넌트는 추상화된 개념이기 때문에, 결국 호스트 컴포넌트로 분해되어야 브라우저가 이해할 수 있다.

이 과정을 좀 더 구체적으로 살펴보자.

function 프로필() {
  return (
    <div className="프로필">
      <아바타 />
      <유저정보 />
    </div>
  );
}
 
function 아바타() {
  return <img src="profile.jpg" alt="프로필" />;
}
 
function 유저정보() {
  return (
    <div>
      <h2>홍길동</h2>
      <p>개발자</p>
    </div>
  );
}

이 컴포넌트들이 만들어내는 Fiber 트리와 output의 관계는 다음과 같다.

프로필 (출력: 없음, 컴포넌트 함수)
  │
  └─► div.프로필 (출력: <div class="프로필">...</div>)
       │
       ├─► 아바타 (출력: 없음, 컴포넌트 함수)
       │    │
       │    └─► img (출력: <img src="profile.jpg" alt="프로필">)
       │
       └─► 유저정보 (출력: 없음, 컴포넌트 함수)
            │
            └─► div (출력: <div>...</div>)
                 │
                 ├─► h2 (출력: <h2>홍길동</h2>)
                 │
                 └─► p (출력: <p>개발자</p>)

output 수집은 아래에서 위로 진행된다. 먼저 리프(호스트) 노드에서 DOM이 생성된다.

// 호스트 컴포넌트들이 실제 DOM 정보 생성
img_fiber.output = createDOMElement('img', {
  src: 'profile.jpg',
  alt: '프로필'
});
 
h2_fiber.output = createDOMElement('h2', {}, '홍길동');
p_fiber.output = createDOMElement('p', {}, '개발자');

그 다음 부모 호스트 컴포넌트가 자식들의 output을 수집한다.

// div 노드가 자식들의 출력을 수집
유저정보_div_fiber.output = createDOMElement('div', {}, [
  h2_fiber.output,  // <h2>홍길동</h2>
  p_fiber.output    // <p>개발자</p>
]);
 
// 최상위 div가 모든 자식 출력을 수집
프로필_div_fiber.output = createDOMElement('div', {className: '프로필'}, [
  img_fiber.output,           // <img src="profile.jpg" alt="프로필">
  유저정보_div_fiber.output   // <div><h2>홍길동</h2><p>개발자</p></div>
]);

마지막으로, 사용자 정의 컴포넌트는 자식의 output을 그대로 전달한다.

// 사용자 정의 컴포넌트는 자식의 출력을 위로 전달
아바타_fiber.output = img_fiber.output;
유저정보_fiber.output = 유저정보_div_fiber.output;
프로필_fiber.output = 프로필_div_fiber.output;

Fiber의 스케줄링

Fiber의 핵심 가치가 "작업을 나눌 수 있다"는 것이라면, 실제로 그 "나누기"를 수행하는 곳은 어디일까? 바로 Work Loop이다.

Work Loop: Fiber 순회의 심장

React의 렌더링은 ReactFiberWorkLoop.js에 정의된 Work Loop에서 시작된다. React는 상황에 따라 두 가지 Work Loop를 사용한다.

// 동기 렌더링: 중단 없이 모든 Fiber를 처리
function workLoopSync() {
  while (workInProgress !== null) {
    performUnitOfWork(workInProgress);
  }
}
 
// 동시성 렌더링: 시간 제한 내에서 작업을 나누어 처리
function workLoopConcurrent(nonIdle) {
  if (workInProgress !== null) {
    const yieldAfter = now() + (nonIdle ? 25 : 5);
    do {
      performUnitOfWork(workInProgress);
    } while (workInProgress !== null && now() < yieldAfter);
  }
}

두 함수의 차이를 주목하라. workLoopSync는 workInProgress가 null이 될 때까지 무조건 돈다. 반면 workLoopConcurrent는 시간 제한을 두고, 시간이 초과되면 루프를 빠져나온다.

여기서 흥미로운 것은 yield 간격의 차이다. Transition이나 Retry 같은 non-idle 작업(사용자가 체감할 수 있는 업데이트) 은 25ms 간격으로 양보하고, idle 작업(사용자가 아무것도 안 하고 있을 때 처리해도 되는 낮은 우선순위 작업) 은 5ms 간격으로 양보한다. non-idle 작업에 25ms를 부여하는 이유는 의도적으로 애니메이션을 약 30fps 수준으로 제한하여, transition 렌더링이 다른 작업을 기아 상태로 만드는 것을 방지하기 위함이다.

performUnitOfWork

performUnitOfWork는 하나의 Fiber 노드를 처리하는 함수다. Fiber 순회의 핵심이 이 함수에 담겨 있다.

function performUnitOfWork(unitOfWork) {
  const current = unitOfWork.alternate;
  const next = beginWork(current, unitOfWork, renderLanes);
  unitOfWork.memoizedProps = unitOfWork.pendingProps;
 
  if (next !== null) {
    workInProgress = next;
  } else {
    completeUnitOfWork(unitOfWork);
  }
}

beginWork는 현재 노드를 처리하고 첫 번째 자식을 반환한다. 그리고 pendingProps를 memoizedProps로 확정하고 자식이 있으면 자식으로, 없으면 completeUnitOfWork를 호출한다

beginWork

beginWork는 Fiber 노드를 위에서 아래로 순회하며, 각 노드에서 필요한 계산을 수행하는 함수다. ReactFiberBeginWork.js에 정의되어 있으며, 내부적으로 Fiber의 tag에 따라 거대한 switch문으로 분기한다.

function beginWork(current, workInProgress, renderLanes) {
  // bailout 체크: props와 context가 변경되지 않았다면 스킵
  if (current !== null) {
    const oldProps = current.memoizedProps;
    const newProps = workInProgress.pendingProps;
    if (oldProps === newProps && !hasContextChanged()) {
      return bailoutOnAlreadyFinishedWork(current, workInProgress, renderLanes);
    }
  }
 
  switch (workInProgress.tag) {
    case FunctionComponent:
      return updateFunctionComponent(current, workInProgress, ...);
    case ClassComponent:
      return updateClassComponent(current, workInProgress, ...);
    case HostComponent:
      return updateHostComponent(current, workInProgress, ...);
    case SuspenseComponent:
      return updateSuspenseComponent(current, workInProgress, ...);
    // ... 약 25가지 이상의 케이스
  }
}

핵심은 맨 위의 bailout 체크다. props와 context가 이전과 동일하다면 bailoutOnAlreadyFinishedWork로 해당 서브트리를 통째로 건너뛴다. 이것이 React의 성능 최적화에서 가장 중요한 경로 중 하나다.

beginWork의 반환값은 첫 번째 자식 Fiber이다. 자식이 있으면 그 자식이 다음 workInProgress가 되고, 없으면(null) completeUnitOfWork로 진입한다.

completeWork

completeWork는 리프 노드에서 시작하여 부모 방향으로 올라가며 작업을 마무리하는 함수다.

function completeUnitOfWork(unitOfWork) {
  let completedWork = unitOfWork;
  do {
    // 1. completeWork로 현재 노드의 작업 마무리 (DOM 생성 등)
    completeWork(current, completedWork, renderLanes);
 
    // 2. 형제가 있으면 형제로 이동 (다시 beginWork 시작)
    const siblingFiber = completedWork.sibling;
    if (siblingFiber !== null) {
      workInProgress = siblingFiber;
      return;
    }
 
    // 3. 형제가 없으면 부모로 올라감
    completedWork = completedWork.return;
    workInProgress = completedWork;
  } while (completedWork !== null);
}

completeWork에서 수행하는 주요 작업은 다음과 같다.

• HostComponent의 경우: 실제 DOM 노드를 생성(createInstance)하고, 자식 DOM들을 append한다. 이미 존재하는 DOM이라면 변경된 props를 수집하여 updateQueue에 저장한다.
• bubbleProperties(): 자식들의 flags를 subtreeFlags로 집계한다. 이 정보는 Commit Phase에서 서브트리 스킵 최적화에 사용된다.

순회를 정리하면 이렇다. child를 따라 내려가고(beginWork) -> 리프에서 완료 후 sibling으로 이동 -> 형제가 없으면 return을 따라 올라감(completeWork). 이것이 Fiber의 깊이 우선 탐색 순서인 것이다.

requestIdleCallback을 버린 이유

앞서 Fiber의 개념 모델에서 requestIdleCallback을 사용하는 코드를 보여줬는데, 실제 React는 이를 사용하지 않는다. 그 이유는 명확하다.

• 호출 빈도가 너무 낮다 : 진정한 "유휴 시간(브라우저가 할 일이 없는 시간)"에만 호출되어, 바쁜 페이지에서는 React 작업이 무한정 지연될 수 있다. Dan Abramov도 "requestIdleCallback is called too infrequently to be useful for scheduling React work"라고 언급한 바 있다.
• 브라우저 호환성 문제 : Safari는 오랫동안 이를 구현하지 않았고, 브라우저마다 동작이 달랐다.
• 20ms 상한 : idle deadline의 상한이 있어 React가 원하는 수준의 예측 가능한 타이밍 제어가 불가능했다.

그 다음으로 requestAnimationFrame + 프레임 예산 추정 방식을 시도했지만, React의 작업이 vsync(모니터가 수직 귀선을 완료한 시점에 맞춰 프레임 출력을 동기화하는 기술) 주기에 맞출 필요가 없다는 판단하에 이 역시 폐기되었다.

MessageChannel

최종적으로 React는 MessageChannel을 선택했다.

if (typeof MessageChannel !== 'undefined') {
  const channel = new MessageChannel();
  channel.port1.onmessage = performWorkUntilDeadline;
  schedulePerformWorkUntilDeadline = () => channel.port2.postMessage(null);
} else {
  schedulePerformWorkUntilDeadline = () => setTimeout(performWorkUntilDeadline, 0);
}

왜 setTimeout이 아닌 MessageChannel일까? setTimeout은 HTML 스펙에 따라 5회 이상 중첩되면 최소 4ms의 지연이 강제된다. 반면 MessageChannel은 이런 제한 없이 다음 이벤트 루프 틱에서 즉시 매크로태스크로 실행된다. 5ms 단위로 작업을 쪼개는 Fiber에게 4ms의 인위적 지연은 치명적이기 때문이다.

(5ms 중 4ms가 대기 시간이라면, 실질적으로 일하는 시간은 1ms뿐이다. 이건 워라밸이 아니라 그냥 밸이다.)

React의 Scheduler 패키지는 내부적으로 두 개의 min-heap(최소 힙) 을 관리한다.

timerQueue (대기실)                    taskQueue (실행 대기열)
┌──────────────────┐                  ┌──────────────────┐
│ 아직 시작 시간이     │   startTime      │ 지금 실행 가능한     │
│ 안 된 태스크들       │ ──경과 시──→      │ 태스크들           │
│                  │                  │                  │
│ 정렬: startTime   │                  │ 정렬: expiration  │
│ (빠른 순)          │                  │ Time (임박한 순)   │
└──────────────────┘                  └──────────────────┘

taskQueue는 "지금 당장 실행할 수 있는" 태스크들의 큐다. expirationTime(= startTime + timeout)이 작을수록, 즉 만료가 임박할수록 먼저 실행된다. timerQueue는 "아직 실행 시점이 오지 않은" 태스크들의 대기실이다. 현재 시간이 startTime을 넘는 순간 taskQueue로 이동한다.

그렇다면 expirationTime을 결정하는 timeout은 어떻게 정해질까? 각 업데이트의 우선순위(Priority Level)에 따라 고유한 timeout이 부여된다.

우선순위          timeout        만료까지         예시
─────────────────────────────────────────────────────────
Immediate        -1ms          즉시 만료         flushSync
UserBlocking     250ms         0.25초           클릭, 입력
Normal           5,000ms       5초              일반 setState
Low              10,000ms      10초             startTransition
Idle             ~1,073,741,823ms  ~12.4일      오프스크린 렌더링

Immediate는 생성 즉시 만료된다. taskQueue에 들어가자마자 최우선으로 실행되는 것이다. (태어나자마자 만료라니, 좀 서글픈 운명이긴 하다.) UserBlocking의 250ms는 사람이 "반응이 느리다"고 느끼는 임계치(100~300ms)에 맞춘 값이다. 클릭했는데 0.25초 안에 반응이 없으면 사용자는 불쾌해진다. Normal의 5초는 넉넉해 보이지만, 이는 "최악의 경우에도 반드시 처리한다"는 보장이다. 실제로는 앞선 작업이 끝나면 곧바로 실행된다. Idle의 약 12.4일은 사실상 무한이다. 다른 모든 작업이 끝나야 비로소 실행된다. (12일 동안 브라우저를 안 닫고 있을 일은 거의 없으니, 무한이라고 봐도 무방하다.)

이 timeout 값들은 동시에 기아 상태(starvation) 방지 메커니즘이기도 하다. 아무리 우선순위가 낮아도 timeout이 지나면 만료 상태가 되어 강제 실행된다. 높은 우선순위 작업이 계속 들어온다고 해서 낮은 우선순위 작업이 영원히 무시당하는 일은 없는 것이다.

Scheduler의 shouldYieldToHost()는 작업 시작 이후 경과 시간이 frameInterval(기본 5ms, SchedulerFeatureFlags.js에서 정의)을 초과했는지를 확인하여 메인 스레드에 제어권을 돌려줄지 결정한다.

Render Phase와 Commit Phase

지금까지 Fiber의 구조와 스케줄링을 살펴봤다. 이제 이 모든 것이 어떻게 조합되어 실제 UI 업데이트가 이루어지는지 전체 흐름을 정리해보자.

Fiber는 내부적으로 Render Phase와 Commit Phase라는 두 단계를 거친다. 이 분리는 React의 동시성 모델을 가능하게 만드는 핵심 설계인 것이다. Fiber의 작동 흐름을 직접 확인하고 싶다면 아래 이미지를 클릭하면 된다.

Render Phase

Render Phase는 UI에 어떤 변경이 필요한지 계산하는 단계다. 이 단계에서는 DOM에 실제로 아무런 영향을 주지 않는다. 그리고 가장 중요한 특성은 비동기적으로 중단 및 재개가 가능하다는 것이다.

이 단계는 앞서 살펴본 beginWork와 completeWork 중심으로 동작한다.

beginWork(fiber) 에서는 각 Fiber의 타입(FunctionComponent, ClassComponent, HostComponent 등)에 따라 적절한 로직을 실행한다. 그리고 자식 Fiber 노드를 생성하고 연결한다. props가 이전과 동일하다면 memoization을 활용해 스킵할 수 있다(bailout)

completeWork(fiber) 에서는 DOM 생성 작업이나 effect 정보를 준비한다. 그리고 bubbleProperties()를 통해 자식들의 flags를 subtreeFlags로 집계하고, 부모 방향으로 올라가며 정보를 보완한다

이 단계에서 DOM을 직접 수정하지 않기 때문에, 언제든 작업을 중단하고 나중에 다시 시작하더라도 사용자에게 불완전한 UI가 노출되지 않는다. 이것이 Concurrent 모드의 기반인 것이다.

subtreeFlags

Render Phase에서 각 Fiber에는 어떤 부수 효과(side effect)가 필요한지 비트 플래그로 기록된다. ReactFiberFlags.js에 정의된 주요 플래그를 살펴보자.

• Placement : 새 노드를 DOM에 삽입
• Update : DOM 속성 업데이트 필요
• ChildDeletion : 자식 노드 삭제 필요
• Ref : ref 연결/해제 필요
• Passive : useEffect 콜백 실행 필요
• Snapshot : getSnapshotBeforeUpdate 실행
• Callback : 라이프사이클 콜백 실행

이전 React(~16)에서는 firstEffect -> nextEffect -> lastEffect로 연결된 linked list를 사용하여 부수 효과가 있는 Fiber만 모아뒀다. 하지만 이 방식은 언마운트된 Fiber의 참조가 남아 메모리 누수를 일으키는 문제가 있었고, Suspense 같은 새로운 패턴을 효율적으로 처리하기 어려웠다.

React 17부터는 이 effect list를 제거하고 subtreeFlags 방식으로 전환했다(PR #19381). completeWork 단계에서 bubbleProperties()가 자식들의 flags를 부모로 집계한다.

function bubbleProperties(completedWork) {
  let subtreeFlags = NoFlags;
  let child = completedWork.child;
  while (child !== null) {
    subtreeFlags |= child.subtreeFlags;
    subtreeFlags |= child.flags;
    child = child.sibling;
  }
  completedWork.subtreeFlags |= subtreeFlags;
}

이 구조의 가장 큰 장점은 Commit Phase에서 서브트리 전체를 스킵할 수 있다는 것이다. 만약 어떤 Fiber의 subtreeFlags & MutationMask === NoFlags라면, 그 서브트리에는 DOM 변경이 필요한 노드가 전혀 없으므로 통째로 건너뛸 수 있다. 이전의 linked list 방식에서는 불가능했던 최적화다.

Commit Phase

Commit Phase는 Render Phase에서 계산된 변경 사항을 실제 DOM에 반영하는 단계다. 이 단계는 항상 동기적으로 수행되며, 한 번 시작하면 끝까지 중단 없이 실행된다. 사용자가 반쯤 업데이트된 UI를 보게 되는 것을 방지하기 위함이다.

Commit Phase는 내부적으로 다음과 같은 세밀한 순서로 동작한다.

1. Before Mutation Phase : commitBeforeMutationEffects()
   • DOM이 변경되기 전에 현재 DOM 상태를 읽는다. getSnapshotBeforeUpdate 라이프사이클이 여기서 실행된다. 이 시점에서 current 트리는 아직 화면의 상태를 나타내므로, DOM의 스크롤 위치나 크기 같은 정보를 안전하게 캡처할 수 있다.
2. Mutation Phase : commitMutationEffects()
   • 실제 DOM 조작이 수행되는 단계다. 새 노드 삽입, 기존 노드 수정, 불필요한 노드 삭제가 모두 여기서 일어난다. componentWillUnmount도 이 시점에 실행되는데, 아직 current가 이전 트리를 가리키고 있으므로 이전 상태를 읽을 수 있기 때문이다.
3. 트리 교체 : root.current = finishedWork
   • 더블 버퍼링의 핵심이다. workInProgress 트리가 current 트리로 승격된다. 이 교체가 Mutation 후, Layout 전에 실행되는 이유가 중요하다. componentWillUnmount는 이전 트리를 읽어야 하므로 Mutation 단계에서 실행되어야 하고, componentDidMount/componentDidUpdate는 새 트리를 읽어야 하므로 Layout 단계에서 실행되어야 하기 때문이다.
4. Layout Phase : commitLayoutEffects()
   • DOM 변경이 완료된 후, 새 DOM 상태를 기반으로 하는 작업들이 실행된다.
     • componentDidMount, componentDidUpdate 실행
     • useLayoutEffect 콜백 실행
     • 이 시점에서 current는 이미 새 트리를 가리키므로, DOM을 읽으면 업데이트된 값을 얻을 수 있다
5. Passive Effects (비동기)
   • useEffect의 cleanup과 setup은 별도로 스케줄링되어 비동기적으로 실행된다. 이들은 DOM 변경에 의존하지 않는 부수 효과(데이터 패칭, 이벤트 구독 등)를 처리하기 위한 것이므로, 동기적으로 실행할 필요가 없다. 이를 비동기로 처리함으로써 브라우저가 먼저 화면을 그릴 수 있도록 양보하는 것이다.

Concurrent Features와 Fiber

지금까지 살펴본 Fiber의 모든 설계(더블 버퍼링, Lane 기반 우선순위, 중단 가능한 Work Loop)가 실제로 어떤 사용자 경험을 가능하게 만드는지, React 18 이후의 Concurrent Features를 통해 확인해보자.

useTransition

startTransition(() => setState(...))을 호출하면, 해당 업데이트에는 TransitionLane이 부여된다. 14개의 TransitionLane이 라운드로빈(작업을 순서대로 돌아가며 하나씩 배정하는 방식)으로 할당되어 충돌을 방지한다.

TransitionLane은 SyncLane이나 DefaultLane보다 우선순위가 낮기 때문에, 사용자 입력 같은 긴급 업데이트가 들어오면 transition 렌더링을 중단하고 긴급 업데이트를 먼저 처리할 수 있다. 이 동안 화면에는 current 트리(이전 상태)가 유지되고, transition은 workInProgress 트리에서 백그라운드로 진행된다.

여기서 더블 버퍼링의 가치가 빛난다. 중단된 transition 렌더링은 workInProgress 트리에만 영향을 미치고, 사용자가 보는 화면(current 트리)은 전혀 손상되지 않는 것이다.

isPending 플래그는 이 transition이 아직 완료되지 않았음을 나타내어, 로딩 인디케이터를 보여주는 등의 처리가 가능하다.

useDeferredValue

useDeferredValue(value)는 최초 렌더링에서는 전달된 value를 그대로 반환한다. 이후 렌더링에서 현재 렌더가 긴급한 경우, 이전의 memoized 값을 반환하고 TransitionLane으로 새로운 렌더를 스케줄링한다. 지연된 렌더링은 Transition과 마찬가지로 중단 가능하다

개념적으로는 startTransition과 유사하지만, 업데이트를 디스패치하는 쪽이 아니라 값을 수신하는 쪽에서 적용하는 차이가 있다. 검색 입력란의 텍스트는 즉시 반영하되, 검색 결과 목록의 렌더링은 지연시키는 것이 대표적인 사용 사례다.

Suspense

컴포넌트가 <Suspense> 내부에서 Promise를 throw하면 throwException이 이를 캐치하고 해당 Fiber를 Incomplete로 마킹한다. 그리고 return 체인을 따라 올라가며 가장 가까운 Suspense 경계를 탐색하고, Suspense 경계가 fallback UI를 표시하도록 전환한다. Promise가 resolve되면 markRootPinged로 해당 lane을 ping하고, React가 suspended 서브트리를 다시 렌더링한다

Concurrent 모드에서는 suspended 컴포넌트의 형제(sibling) 노드들을 계속 렌더링할 수 있어, 하나의 데이터 요청이 전체 트리의 렌더링을 차단하지 않는다. 이것이 가능한 이유는 Fiber의 linked list 구조 덕분에 sibling으로의 이동이 자유롭기 때문이다.

Streaming SSR과 Selective Hydration

React 18의 renderToPipeableStream은 Suspense 경계를 활용한다.

• 서버: Suspense 경계가 suspend되면, fallback HTML을 먼저 전송하고 데이터가 준비되면 나중에 <script> 태그로 실제 콘텐츠를 스트리밍한다
• 클라이언트 (Selective Hydration): 각 Suspense 경계가 독립적으로 hydration될 수 있다. 사용자가 아직 hydration되지 않은 영역을 클릭하면, SelectiveHydrationLane을 통해 해당 경계의 hydration을 우선적으로 처리한 뒤 이벤트를 디스패치한다

이 모든 것이 가능한 이유는 각 Suspense 경계가 독립적으로 스케줄링 가능한 Fiber 노드이기 때문이다. 결국 Fiber 아키텍처의 "작업을 나누고, 우선순위를 매기고, 중단/재개할 수 있다"는 핵심 설계가 이러한 기능들의 토대가 되는 것이다.

마치며

이 글에서 다룬 내용을 한 문장으로 요약하면, React Fiber는 재귀를 반복으로 바꾸고, 콜 스택을 힙으로 옮겨, 렌더링을 중단하고 재개할 수 있게 만든 아키텍처다.

이를 위해 linked list 기반의 트리 구조, 더블 버퍼링, Lane 기반 우선순위 시스템, MessageChannel 기반 스케줄러 등 수많은 정교한 설계가 조합되었다. 그리고 이 모든 것은 결국 사용자가 느끼는 UI의 반응성을 극대화하는 것 이라는 목표를 향하고 있다.

물론 Fiber의 내부 구현은 React 버전이 올라갈 때마다 계속 변화하고 있으며, 이 글에서 다룬 내용 역시 특정 시점의 스냅샷에 불과하다. 하지만 "작업을 나누고, 우선순위를 매기고, 중단하고 재개할 수 있다"는 Fiber의 핵심 철학만큼은 앞으로도 변하지 않을 것이라 생각한다.

이 글을 통해 React Fiber가 단순한 면접 키워드가 아닌, React의 모든 기능을 떠받치는 런타임 아키텍처라는 점이 전달되었기를 바란다. 정답은 없지만, 이 글을 읽는 독자분들도 소스코드를 직접 들여다보며 각자만의 이해를 쌓아가기를 바란다.

출처

• Andrew Clark — React Fiber Architecture
• React 소스코드 — ReactFiberWorkLoop.js
• React 소스코드 — ReactFiberBeginWork.js
• React 소스코드 — ReactFiberCompleteWork.js
• React 소스코드 — ReactFiberLane.js
• React 소스코드 — ReactFiberFlags.js
• React 소스코드 — ReactFiber.js (createWorkInProgress)
• React 소스코드 — Scheduler.js
• React 소스코드 — SchedulerFeatureFlags.js
• PR #18796 — Initial Lanes implementation
• PR #19381 — Remove effect list (firstEffect/nextEffect)
• Issue #7942 — Fiber Principles: Contributing To Fiber
• React 18 Working Group — New Suspense SSR Architecture (Discussion #37)
• React 18 Working Group — Concurrent Scheduling Specifics (Discussion #27)
• React 18 Working Group — useDeferredValue (Discussion #129)
• React 18 Working Group — Selective Hydration (Discussion #130)
• React v18.0 Blog Post

이번 글에서는 Vite 개발 서버 내부에서 이 함수가 어떤 역할을 하는지, 어떤 순서로 동작하는지, 그리고 실제 사용하면서 주의할 점은 무엇인지까지 정리해본다.

TransformRequest란?

Vite의 개발 서버는 브라우저로부터의 HTTP 요청을 인터셉트하여, 요청된 모듈을 즉석에서 변환(transform) 후 제공한다. 이 핵심 과정을 담당하는 내부 함수가 바로 transformRequest(url, serverContext)이다. 이 함수는 Vite의 플러그인 시스템과 깊이 연관되어 있으며, 다음과 같은 정교한 파이프라인을 통해 동작한다.

1. 모듈 식별 및 로딩 (Module Identification & Loading)

• 요청된 url을 기준으로 Vite의 모듈 해석 로직 (Module Resolution)을 통해 실제 파일 시스템 경로 또는 가상 모듈 ID를 확정한다.
• 확정된 ID를 사용하여 load 훅을 호출하는 플러그인을 통해 모듈의 원본 코드를 로드한다. 기본적으로는 파일 시스템에서 직접 파일을 읽어오지만, 플러그인을 통해 커스텀 로딩 로직을 구현할 수 있다.

2. 플러그인 기반 코드 변환 (Plugin-driven Code Transformation)

• 로드된 코드는 Vite에 등록된 플러그인들의 transform 훅 체인을 통과한다. 각 플러그인은 transform(code, id, options) 훅을 통해 코드를 분석하고 수정할 기회를 갖는다.
• 이 과정에서 Babel, PostCSS, SASS/LESS 전처리기 등 다양한 변환 작업이 순차적으로 적용될 수 있다. 플러그인은 코드 문자열뿐만 아니라 AST(Abstract Syntax Tree) 레벨에서의 조작도 수행할 수 있으며, 소스맵(source map) 생성 및 관리를 지원한다.
• Vite는 이 과정에서 모듈 간의 의존성을 파악하여 모듈 그래프(Module Graph)를 구축하고, HMR(Hot Module Replacement)을 위한 데이터를 수집한다.

3. 내장 변환기 적용 (Built-in Transformers Application)

• 플러그인 변환 이후, 필요한 경우 Vite의 내장 변환기가 동작한다. 대표적으로 esbuild가 사용되어 TypeScript, JSX, TSX 파일을 매우 빠른 속도로 순수 JavaScript로 트랜스파일한다.
• .css 파일의 경우, PostCSS 처리 및 CSS Modules, HMR을 위한 래핑(wrapping) 등이 이루어진다.
• .vue 또는 .svelte 같은 SFC(Single File Component)는 해당 플러그인의 transform 훅에서 이미 처리되었을 가능성이 높지만, 이 단계에서 추가적인 Vite 내부 처리가 적용될 수 있다.

4. 결과 집계 및 반환 (Result Aggregation & Return)

• 모든 변환 과정을 거친 최종 코드(result.code)와 함께, 디버깅을 위한 소스맵(result.map), 그리고 플러그인들이 전달한 추가 메타데이터(result.meta)를 포함하는 객체를 반환한다.
• 이 결과는 HTTP 응답으로 브라우저에 전달되거나, 서버 사이드 렌더링(SSR) 시에는 서버 측 실행 환경에서 사용된다.

그러면 아래 예시 코드를 활용해 Vite 개발 서버 환경에서 특정 모듈의 변환 결과를 확인해보자.

const result = await server.transformRequest("/src/main.ts", {
  html: server.config.root + "/index.html",
});
 
if (result) {
  console.log(result.code);
}

server는 현재 실행 중인 ViteDevServer의 인스턴스를 가리킨다. 이 객체는 Vite 개발 서버의 다양한 기능과 설정에 접근할 수 있는 진입점 역할을 한다.

server.transformRequest(url, options) 에서 url은 변환을 요청할 모듈의 URL 경로로, 예시에서는 '/src/main.ts'로, 프로젝트 소스 디렉토리 내의 main.ts 파일이다. 이 URL은 웹 브라우저가 요청하는 경로와 유사한 형태를 가진다.

options은 변환 과정에 영향을 줄 수 있는 추가적인 컨텍스트 정보를 제공하는 객체이다. 예시코드에서 html: server.config.root + '/index.html'로, 현재 변환 요청이 어떤 HTML 파일을 기준으로 이루어지는지를 명시한다. server.config.root는 Vite 프로젝트의 루트 디렉토리를 나타내며, 여기에 /index.html을 더해 일반적으로 프로젝트의 메인 HTML 파일 경로를 지정한다.

이 정보는 특정 플러그인이 HTML 컨텍스트에 따라 다르게 동작하거나, CSS @import 경로 해석, 혹은 SSR(Server-Side Rendering) 시 에셋 번들링 등에서 활용될 수 있다.

내부 구조를 코드와 함께 보기

Vite의 transformRequest 함수의 실제 구현은 HMR, 소스맵 처리, 캐싱 전략 등 다양한 요소가 고려되어 상당히 어렵고 정교하다. 그렇기에 핵심적인 처리 흐름을 간략화하여 살펴보자.

핵심은 "ID 해석 → 로드 → (플러그인 & esbuild) 변환 → 캐싱 및 반환" 의 흐름으로 요약할 수 있다. 이 과정을 통해 Vite는 요청된 모듈을 효율적으로 처리하고 빠른 개발 서버 성능을 제공한다. 이 부분을 명심하고 아래 설명을 따라가보자.

// 실제 transformRequest 함수의 시그니처 및 초기 캐시 확인 로직 (간략화)
export async function transformRequest(
  environment: DevEnvironment,
  url: string,
  options: TransformOptions = {},
): Promise<TransformResult | null> {
  // (옵션 기본값 설정, 서버 닫힘 상태 확인 등의 전처리 로직이 여기에 위치합니다.)
 
  //    동일한 URL과 옵션에 대한 요청이 이미 처리 중인지 확인합니다.
  const cacheKey = `${options.html ? "html:" : ""}${url}`;
  const pending = environment._pendingRequests.get(cacheKey);
 
  if (pending) {
    // 이미 진행 중인 요청이 있고, 해당 요청이 현재 시점에서도 유효하다면
    return pending.request;
  }
 
  // 새로운 변환 작업 시작
  return result;
}

1단계 : 초기화 및 캐시 확인

요청 URL과 컨텍스트를 기반으로 캐시 키를 생성한다. 이미 동일한 요청이 진행 중인지 확인하고, 있다면 그 결과를 기다린다. 모듈이 마지막으로 무효화된 시간을 기준으로 최신 상태인지 확인한다.

실제 Vite 소스코드에서는 doTransform, loadAndTransform 등의 내부 함수로 분리되어 처리한다. 그리고 에러 처리, HMR을 위한 소프트 무효화(soft invalidation) 처리, 의존성 최적화 연동 등 훨씬 더 많은 세부 로직이 포함되어 있다.

2단계 : URL 정규화 및 모듈 ID 해석

URL에서 불필요한 쿼리(예: 타임스탬프)를 제거한다. 그리고 pluginContainer.resolveId(url)를 호출하여 플러그인을 통해 URL을 실제 파일 시스템 경로 또는 고유 ID로 변환한다. (예: '/src/main.ts' -> '/Users/username/my-project/src/main.ts')

이렇게 변환된 ID를 기준으로 모듈 그래프에서 기존 모듈 정보를 조회하고, 유효한 캐시가 있다면 반환한다.

3단계 : 코드 로드 (Load)

pluginContainer.load(id)를 호출하여 등록된 플러그인들의 load 훅을 실행한다. 플러그인이 모듈 코드를 반환하면 그 코드를 사용하고, 그렇지 않으면 파일 시스템에서 직접 파일을 읽어온다. 로드된 코드에서 인라인 소스맵이 있다면 추출한다.

4단계 : 코드 변환 (Transform)

pluginContainer.transform(code, id, { inMap: map })을 호출하여 등록된 모든 플러그인의 transform 훅이 순차적으로 실행되어 코드를 변환한다. (예: Vue SFC 처리, PostCSS 변환, 사용자 정의 변환 등)

TypeScript, JSX, TSX와 같은 파일은 Vite에 내장된 esbuild 플러그인 또는 관련 플러그인에 의해 JavaScript로 매우 빠르게 트랜스파일된다. 각 플러그인은 코드와 소스맵을 입력받아, 수정된 코드와 소스맵을 다음 플러그인으로 전달하거나 최종 결과로 반환한다.

5단계 : 소스맵 후처리

변환 과정에서 생성되거나 수정된 소스맵을 정규화한다. 원본 소스 내용을 소스맵에 포함시키거나(injectSourcesContent), 특정 소스 파일을 무시하는(sourcemapIgnoreList) 등의 후처리를 적용한다.

이 다음 단계에서 SSR 환경을 위한 추가 변환을 할 수 있다.

6단계 : 결과 생성 및 캐싱

최종적으로 변환된 코드, 소스맵, ETag(캐싱용) 등을 포함하는 결과 객체를 생성한다. 만약 모듈 처리 중에 해당 모듈이 무효화되지 않았다면, 이 결과를 모듈 그래프에 캐싱하여 다음 요청 시 빠르게 재사용할 수 있도록 한다.

transformRequest이 왜 중요한가?

transformRequest 함수는 Vite의 핵심 기능인 모듈 핫 리로딩(HMR)을 가능하게 하는 중추적인 역할을 한다. 개발 중 코드가 변경되면, transformRequest는 해당 모듈만 신속하게 다시 읽어 변환하고 브라우저에 전달하여 즉각적인 화면 업데이트를 제공한다.

또한, 개발자가 특정 플러그인을 개발하거나 기존 플러그인의 동작을 디버깅할 때 매우 유용하다. 예를 들어, custom transform 훅이 예상대로 작동하는지 테스트하거나, TypeScript, JSX, Vue SFC와 같은 파일이 JavaScript로 어떻게 변환되는지 그 결과를 직접 추적하고 확인할 수 있다.

이처럼 transformRequest는 Vite의 빠른 개발 경험을 제공하고, 플러그인 생태계를 확장하며, 코드 변환 과정을 투명하게 만들어 개발자에게 강력한 분석 도구를 제공한다는 점에서 매우 중요하다.

연관 이슈 및 참고자료

• Nuxt에서 transformRequest 관련 이슈
  → SSR 환경에서 transform이 누락되는 버그 사례
• Vite JavaScript API 문서
  → createServer, transformRequest, ssrLoadModule 등의 공식 API 가이드
• esbuild transform API
  → TypeScript → JavaScript로 변환되는 과정 이해에 필수

마치며

transformRequest()는 Vite 개발 서버에서 가장 중요한 처리 로직 중 하나다.
단순히 내부용 API로 보기보다는, 플러그인 개발, 변환 디버깅, 성능 분석 시 활용할 수 있는 강력한 도구로 이해하면 좋다.