Flutter 프로젝트 폴더 구조 완벽 가이드: 확장 가능한 아키텍처 설계

플러터(Flutter)는 공식적으로 강제하는 폴더 구조가 없기 때문에, 프로젝트 규모와 팀의 협업 방식에 따라 일관성 있고 확장 가능한 구조를 직접 설계하는 것이 중요합니다.
아래는 실무와 커뮤니티에서 검증된 폴더링 베스트 프랙티스와 그 이유를 정리한 가이드입니다.

---

플러터 프로젝트의 기본 구조

일반적으로 플러터 프로젝트는 아래와 같은 최상위 구조를 가집니다.

/android
/ios
/web
/assets
/lib
  main.dart
  ...
pubspec.yaml

• /lib: 앱의 핵심 소스코드가 위치하는 곳
• /assets: 이미지, 폰트 등 정적 리소스
• main.dart: 앱 진입점

---

lib 폴더 내부의 베스트 폴더링 패턴

레이어 기반 구조(Layer-first)

/models: 데이터 모델 클래스
/screens: 각 화면별 UI 코드
/widgets: 여러 화면에서 재사용되는 커스텀 위젯
/services: 외부 API, DB, SharedPreferences 등 비즈니스 로직
/utils: 유틸리티 함수, 상수, 헬퍼 클래스
/providers or /state: 상태 관리 관련 코드(Provider, Riverpod, Bloc 등)

이 구조는 규모가 작거나 중간 크기의 프로젝트에 적합하며, 각 레이어별 역할이 명확해 유지보수와 협업에 용이합니다.

기능(Feature) 기반 구조(Feature-first)

/lib
  /features
    /auth
      /data
      /domain
      /presentation
    /profile
      /data
      /domain
      /presentation
  /core
  /common
  main.dart

• /features: 기능(도메인) 단위로 폴더 분리, 각 기능별로 data/domain/presentation 계층을 둠
• /core: 앱 전역에서 공통으로 사용하는 유틸, 테마, 라우팅 등
• /common: 여러 기능에서 재사용되는 위젯, 리소스 등

이 구조는 대규모, 엔터프라이즈 앱, 여러 팀이 동시에 개발하는 프로젝트에서 강력한 확장성과 모듈성을 제공합니다.

---

기타 폴더 및 리소스 관리

추가 폴더 구성

• /assets: images, fonts, icons 등 정적 파일을 하위 폴더로 분류
  • 예: /assets/images, /assets/icons
• /config: 환경설정, 라우팅, 테마 등 앱 전역 설정 파일
• /test: 단위/위젯/통합 테스트 코드

---

폴더링 실전 팁

핵심 개발 원칙

• 공통 위젯/유틸은 core/common/utils로 분리
• assets는 pubspec.yaml에 반드시 등록
• 기능별로 폴더를 나누면 팀 단위 병렬 개발에 유리
• 상태 관리(Provider, Bloc 등)는 별도 폴더에 모아 관리
• 패키지, 서비스, 데이터 계층 분리는 유지보수와 테스트에 필수
• 폴더/파일명은 소문자+언더스코어 권장

---

추천 폴더 구조 예시

Layer-first 예시

/lib
  /models
  /screens
  /widgets
  /services
  /utils
  /providers
  main.dart

Feature-first + Clean Architecture 예시

/lib
  /features
    /login
      /data
      /domain
      /presentation
    /home
      /data
      /domain
      /presentation
  /core
  /common
  main.dart

실전 상세 구조 예시

/lib
  /core
    /constants
    /theme
    /routing
    /utils
  /features
    /authentication
      /data
        /models
        /repositories
        /datasources
      /domain
        /entities
        /usecases
        /repositories
      /presentation
        /pages
        /widgets
        /providers
    /dashboard
      /data
      /domain
      /presentation
  /shared
    /widgets
    /services
    /models
  main.dart

---

마무리

소규모/중규모: 레이어 기반 구조(models, screens, widgets, services 등)
대규모/팀 개발: 기능(Feature) 기반 구조(features/도메인별 하위 계층)
공통 원칙: 일관성, 재사용성, 확장성, 테스트 용이성
정답은 없지만 관례는 있습니다. 자신이 속해있는 프로젝트의 성격과 팀의 개발 문화에 맞게 구조를 설계하고, 초기부터 폴더링 원칙을 정해두면 유지보수와 협업이 훨씬 쉬워집니다.
프로젝트 시작 단계에서 팀원들과 폴더 구조에 대한 합의를 이루고, 일관된 네이밍 컨벤션을 유지하는 것이 성공적인 Flutter 프로젝트 관리의 핵심입니다.