FSD 그리고 배럴 파일! 성능과 아키텍처 사이의 균형 찾기

FSD 아키텍처와 함께 생각해보기

FSD 와 배럴 파일

 

Vue3에서 React.js로 프로젝트를 마이그레이션하면서 Feature-Sliced Design(FSD) 아키텍처를 도입하기로 결정했습니다. 그 과정에서 배럴 파일(barrel files)에 대한 고민이 생겼고, 최근 몇 년 사이에 이에 대한 관점이 많이 바뀌었다는 것을 발견했습니다.

 

배럴 파일이란?

배럴 파일은 여러 모듈을 하나의 파일(주로 index.js 또는 index.ts)에서 다시 내보내는 패턴입니다. 이 패턴은 코드 정리와 import 문을 단순화하는 데 도움이 됩니다.

 

배럴 파일 전 후

 

배럴 파일 없이:

// 각 파일에서 개별적으로 가져오기 
import { Button } from "../components/Button"; 
import { TextField } from "../components/TextField"; 
import { Checkbox } from "../components/Checkbox";

 

배럴 파일 사용 시:

// 하나의 경로에서 모든 컴포넌트 가져오기 
import { Button, TextField, Checkbox } from "../components";

 

배럴 파일의 실제 구현

일반적인 배럴 파일 (components/index.ts):

// 와일드카드 내보내기 (권장하지 않음) 
export * from './Button'; 
export * from './TextField'; 
export * from './Checkbox'; 

// 또는 명시적 내보내기 (권장) 
export { Button } from './Button'; 
export { TextField } from './TextField'; 
export { Checkbox } from './Checkbox';

 

배럴 파일의 성능 문제

Marvin의 JavaScript 생태계 속도 개선: 배럴 파일 문제 글에서 지적한 바와 같이, 배럴 파일은 다음과 같은 성능 문제를 일으킬 수 있습니다:

1. 모듈 그래프 복잡성 증가: 배럴 파일이 증가할수록 모듈 간 의존성 그래프가 복잡해집니다.
2. 불필요한 모듈 로딩: 특히 와일드카드 내보내기(export * from)를 사용할 경우, 실제로 필요하지 않은 모듈까지 로드될 수 있습니다.

 

모듈 그래프 비교

배럴 파일 없이:

App.js
├── Button.js
├── TextField.js
└── Checkbox.js

 

배럴 파일 사용 시:

App.js
└── components/index.js
    ├── Button.js
    ├── TextField.js
    └── Checkbox.js

 

성능 테스트 결과 예시

모듈 수배럴 파일 없음배럴 파일 사용차이

모듈 수	배럴 파일 없음	배럴 파일 사용	차이
10개	150ms	180ms	+20%
50개	450ms	630ms	+40%
100개	820ms	1250ms	+52%

 

참고: 이 수치는 예시용이며, 실제 프로젝트에서는 다양한 요인에 따라 달라질 수 있습니다.

 

FSD 아키텍처에서의 배럴 파일

Feature-Sliced Design(FSD)은 배럴 파일과 유사한 패턴을 의도적으로 활용합니다. 이는 단순히 코드 작성의 편의성을 위한 것이 아니라, 아키텍처의 구조와 목적을 반영한 결정입니다.

FSD는 애플리케이션을 기능 단위로 분할하고 계층화된 구조를 만드는 것을 목표로 합니다. 이 구조에서 각 레이어(layer)와 슬라이스(slice)는 명확한 책임과 역할을 가집니다. 배럴 파일과 유사한 패턴을 사용함으로써, FSD는 다음과 같은 이점을 얻습니다:

• 캡슐화: 각 모듈의 내부 구현을 숨기고 공개 API만을 노출합니다.
• 의존성 관리: 상위 레이어가 하위 레이어에만 접근할 수 있도록 제한합니다.
• 재사용성: 공통 기능을 쉽게 공유하고 재사용할 수 있게 합니다.
• 유지보수성: 코드 구조를 일관되게 유지하여 개발자가 쉽게 이해하고 수정할 수 있게 합니다.

이러한 구조는 대규모 프로젝트에서 코드의 조직화와 관리를 용이하게 만들어, 장기적으로 프로젝트의 확장성과 유지보수성을 향상시킵니다. 따라서 FSD에서 배럴 파일과 유사한 패턴의 사용은 단순한 편의성을 넘어서, 아키텍처의 핵심 원칙을 실현하기 위한 전략적 선택이라고 볼 수 있습니다.

 

FSD에서의 배럴 파일 활용 - 실제 경험과 팁

FSD 아키텍처를 실제 프로젝트에 적용해본 경험에 따르면, 배럴 파일(Public API)의 주요 이점 중 하나는 유지보수성 향상입니다. 이에 대해 이너서클 재직자 과정에서 만난 동료 개발자분께서 다음과 같은 인사이트를 공유해주셨어요:

"FSD를 사용하면서 느낀 바로는, Public API를 활용하는 주된 이유 중 하나가 유지보수에 있습니다. 예를 들어, entities/user의 스키마가 일부 변경되더라도 features/loginUser, features/registerUser 등에서 import 구문을 변경할 필요가 없어집니다."

이는 FSD의 핵심 원칙 중 하나인 모듈 간 의존성 관리와 일치하는 관점입니다.

 

배럴 파일 생성 자동화

대규모 프로젝트에서 매번 수동으로 배럴 파일(Public API)을 관리하는 것은 번거로울 수 있습니다. 이를 해결하기 위한 실용적인 접근 방법으로, 배럴 파일을 자동으로 생성하는 스크립트를 활용할 수 있습니다.

예를 들어:

pnpm api features/loginUser

이러한 CLI 명령어를 통해 features/loginUser 내부의 모듈을 자동으로 분석하고, 명시적으로 내보내는 배럴 파일을 생성할 수 있습니다. 이때 _로 시작하는 파일이나 폴더는 내부용으로 간주하여 자동으로 제외할 수 있습니다.

 

명시적 내보내기의 중요성

앞서 언급했듯이, 와일드카드 내보내기(export * from './module')는 권장되지 않습니다. 대신, 명시적 내보내기를 사용하면 성능 이슈를 최소화하면서도 FSD의 이점을 충분히 활용할 수 있습니다.

// Good: 명시적 내보내기
export { LoginForm } from './LoginForm';
export { useAuth } from './useAuth';
export type { User } from './types';

이러한 접근 방식은 모듈의 공개 API를 명확히 정의하고, 불필요한 의존성을 방지하며, 코드의 가독성과 유지보수성을 향상시킵니다. 좀 더 상세한 예시를 들어볼게요.

스크립트에 대한 폴더 구조 예시:

project-root/
├── src/
│   ├── features/
│   │   └── loginUser/
│   │       ├── ui/
│   │       ├── model/
│   │       └── index.ts (자동 생성될 파일)
│   └── ... (다른 FSD 폴더들)
├── scripts/
│   └── generate-barrel.ts
├── package.json
└── tsconfig.json

 

scripts/generate-barrel.ts 파일의 내용:

import fs from 'fs';
import path from 'path';

function generateBarrel(directory: string) {
  const files = fs.readdirSync(directory);
  const exports: string[] = [];

  files.forEach(file => {
    if (file.startsWith('_') || file === 'index.ts') return;

    const filePath = path.join(directory, file);
    const stats = fs.statSync(filePath);

    if (stats.isDirectory()) {
      exports.push(`export * from './${file}';`);
    } else if (file.endsWith('.ts') || file.endsWith('.tsx')) {
      const name = path.parse(file).name;
      exports.push(`export { ${name} } from './${name}';`);
    }
  });

  const content = exports.join('\n') + '\n';
  fs.writeFileSync(path.join(directory, 'index.ts'), content);
}

const targetDir = process.argv[2];
if (!targetDir) {
  console.error('Please specify a target directory');
  process.exit(1);
}

const fullPath = path.resolve(process.cwd(), targetDir);
generateBarrel(fullPath);
console.log(`Barrel file generated for ${fullPath}`);

 

package.json에 스크립트 추가:

{
  "scripts": {
    "api": "ts-node scripts/generate-barrel.ts"
  }
}

이제 pnpm api features/loginUser 명령어를 실행하면, src/features/loginUser/index.ts 파일이 자동으로 생성되거나 업데이트됩니다! 아래부터는 좀 더 일반적인 예시를 들어볼게요.

 

FSD 기본 폴더 구조:

src/
├── app/        # 글로벌 설정, 스타일, 프로바이더
├── processes/  # 비즈니스 프로세스
├── pages/      # 페이지 컴포넌트
├── widgets/    # 복합 UI 블록
├── features/   # 사용자 인터랙션
├── entities/   # 비즈니스 엔티티
└── shared/     # 공유 유틸리티, UI 키트

 

FSD에서의 배럴 파일 사용 예시

features/auth/index.ts (적절한 배럴 파일 사용):

// 명시적 내보내기 - 공개 API를 명확히 정의
export { LoginForm } from './ui/LoginForm';
export { useAuth } from './model/useAuth';
export type { AuthUser } from './model/types';

 

균형 잡힌 접근법: 실제 구현 예시

1. 구조화된 배럴 파일 사용:

features/
├── auth/
│   ├── ui/
│   │   ├── LoginForm.tsx
│   │   └── RegisterForm.tsx
│   ├── model/
│   │   ├── useAuth.ts
│   │   └── types.ts
│   └── index.ts  # 아키텍처 경계에만 배럴 파일 사용
└── userProfile/
    ├── ui/
    ├── model/
    └── index.ts

 

2. 명시적 내보내기:

// features/auth/index.ts
// 명시적 내보내기로 공개 API 정의
export { LoginForm } from './ui/LoginForm';
export { RegisterForm } from './ui/RegisterForm';
export { useAuth } from './model/useAuth';
export type { User, AuthCredentials } from './model/types';

 

3. FSD 아키텍처 규칙에 따른 가져오기:

// 잘못된 방식: 레이어 우회
import { Button } from '@/shared/ui/Button';

// 올바른 방식: 아키텍처 경계 존중
import { Button } from '@/shared/ui';

 

4. 실제 React 컴포넌트 예시:

// features/auth/ui/LoginForm.tsx
import { useState } from 'react';
import { Button, TextField } from '@/shared/ui';
import { useAuth } from '../model/useAuth';
import type { AuthCredentials } from '../model/types';

export const LoginForm = () => {
  const [credentials, setCredentials] = useState({
    email: '',
    password: ''
  });
  const { login, isLoading } = useAuth();

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    login(credentials);
  };

  return (
    
      <TextField
        label="Email"
        value={credentials.email}
        onChange={(e) => setCredentials(prev => ({
          ...prev,
          email: e.target.value
        }))}
      />
      <TextField
        type="password"
        label="Password"
        value={credentials.password}
        onChange={(e) => setCredentials(prev => ({
          ...prev,
          password: e.target.value
        }))}
      />
      
        {isLoading ? 'Logging in...' : 'Login'}
      
    
  );
};

 

현대적 도구의 영향

최신 빌드 도구들은 배럴 파일의 성능 문제를 일부 완화할 수 있습니다:

 

번들러별 최적화 설정:

Vite 설정 예시:

// vite.config.js
export default {
  build: {
    target: 'esnext',
    minify: 'esbuild',
    rollupOptions: {
      output: {
        manualChunks(id) {
          // 최적화된 청크 설정
        }
      }
    }
  }
}

 

Webpack 설정 예시:

// webpack.config.js
module.exports = {
  optimization: {
    usedExports: true, // 트리 쉐이킹 활성화
    moduleIds: 'deterministic',
    splitChunks: {
      chunks: 'all',
    }
  }
}

 

성능 측정 - 실시간 프로젝트 모니터링

// build-analyzer.ts
import { performance } from 'perf_hooks';

export function measureBuildTime(taskName: string, task: () => void) {
  const startTime = performance.now();
  task();
  const endTime = performance.now();
  console.log(`Task "${taskName}" took ${endTime - startTime}ms`);
}

// 사용 예시
measureBuildTime('Module compilation', () => {
  // 빌드 로직
});

 

결론 - 프로젝트 규모별 권장 접근법

 

소규모 프로젝트 (10,000줄 이하)

src/
├── components/
│   └── index.ts  # 배럴 파일 사용 가능
├── hooks/
│   └── index.ts  # 배럴 파일 사용 가능
└── utils/
    └── index.ts  # 배럴 파일 사용 가능

 

중간 규모 프로젝트 (10,000~50,000줄)

src/
├── features/
│   ├── feature1/
│   │   └── index.ts  # 아키텍처 경계에만 배럴 파일
│   └── feature2/
│       └── index.ts
└── shared/
    ├── ui/
    │   └── index.ts  # 명시적 내보내기 사용
    └── lib/
        └── index.ts  # 명시적 내보내기 사용

 

대규모 프로젝트 (50,000줄 이상)

src/
├── app/
├── processes/
├── pages/
│   └── index.ts  # 엄격하게 제한된 배럴 파일
├── widgets/
│   └── index.ts  # 엄격하게 제한된 배럴 파일
├── features/
│   └── [각 기능별]/
│       └── index.ts  # 공개 API만 명시적 내보내기
├── entities/
│   └── [각 엔티티별]/
│       └── index.ts  # 공개 API만 명시적 내보내기
└── shared/
    └── [각 모듈별]/
        └── index.ts  # 성능 측정 후 결정

 

 

배럴 파일의 사용은 결국 개발 경험과 성능 사이의 균형을 찾는 문제라 생각합니다.

FSD 아키텍처를 도입한다면, 배럴 파일의 장단점을 인식하고 프로젝트의 규모와 팀의 필요에 맞게 적절히 조절하는 것이 중요할 것 같아요.

명확한 아키텍처 경계, 명시적인 내보내기, 그리고 현대적인 빌드 도구를 활용한다면, 배럴 파일의 이점을 취하면서도 성능 문제를 최소화할 수 있습니다!