프로젝트 구조

flutter create로 만든 프로젝트에는 Dart 코드, 패키지 설정, 플랫폼별 폴더가 함께 들어 있습니다. 이 장에서는 각 파일과 폴더가 어떤 역할을 하는지, 그리고 의존성과 에셋을 어떻게 관리하는지 살펴봅니다.

전체 모습

hello_app/
├── lib/
│   └── main.dart          # 앱 진입점
├── test/
│   └── widget_test.dart   # 기본 위젯 테스트
├── android/               # Android 프로젝트(Gradle)
├── ios/                   # iOS 프로젝트(Xcode)
├── web/                   # index.html, 아이콘, manifest
├── windows/               # Windows 데스크톱(CMake)
├── macos/                 # macOS 데스크톱(Xcode)
├── linux/                 # Linux 데스크톱(CMake)
├── pubspec.yaml           # 패키지 설정
├── pubspec.lock           # 확정된 의존성 버전
└── analysis_options.yaml  # 정적 분석(린트) 규칙

build/와 .dart_tool/은 빌드할 때 자동으로 생기는 폴더이므로 버전 관리에 넣지 않습니다. 새 프로젝트의 .gitignore에 이미 들어 있습니다.

lib: 앱 코드

앱의 Dart 코드는 모두 lib 아래에 둡니다. 처음에는 main.dart 하나뿐이지만, 앱이 커지면 화면, 위젯, 데이터 계층별로 폴더를 나눕니다. Flutter가 강제하는 구조는 없으며, 흔히 쓰는 방식은 다음과 같습니다.

lib/
├── main.dart
├── app.dart              # MaterialApp, 테마, 라우팅
├── screens/              # 화면 단위 위젯
│   ├── home_screen.dart
│   └── detail_screen.dart
├── widgets/              # 여러 화면에서 쓰는 위젯
├── models/               # 데이터 클래스
└── services/             # API 호출, 저장소

다른 파일을 불러올 때는 패키지 경로를 씁니다. pubspec.yaml의 name이 hello_app이라면 다음과 같습니다.

import 'package:flutter/material.dart';
import 'package:hello_app/screens/home_screen.dart';
import 'package:hello_app/models/todo.dart';

파일 이름은 home_screen.dart처럼 소문자와 밑줄(snake_case)을, 클래스 이름은 HomeScreen처럼 대문자로 시작하는 이름(UpperCamelCase)을 쓰는 것이 Dart의 관례입니다.

pubspec.yaml: 패키지 설정

pubspec.yaml은 앱의 이름, 버전, Dart SDK 범위, 의존성, 에셋을 적는 설정 파일입니다.

name: hello_app
description: "A new Flutter project."
publish_to: 'none'
version: 1.0.0+1

environment:
  sdk: ^3.5.0

dependencies:
  flutter:
    sdk: flutter
  cupertino_icons: ^1.0.8
  http: ^1.2.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^5.0.0

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    # 데이터 파일은 하나씩 적을 수도 있습니다
    - assets/data/config.json

위 버전 숫자는 예시이며, 실제 값은 flutter create와 flutter pub add가 그때의 최신 버전으로 채웁니다. version: 1.0.0+1에서 + 앞은 사용자에게 보이는 버전 이름, 뒤는 스토어가 구분하는 빌드 번호입니다.

패키지는 pub.dev에서 찾아 명령으로 추가합니다.

# 의존성 추가(pubspec.yaml 이 자동으로 수정됨)
flutter pub add http

# 개발용 의존성 추가
flutter pub add --dev mocktail

# pubspec.yaml 을 직접 고친 뒤 내려받기
flutter pub get

# 새 버전이 있는 패키지 확인
flutter pub outdated

pubspec.lock은 실제로 내려받은 버전을 기록합니다. 앱 프로젝트에서는 이 파일을 커밋해 모든 개발자와 빌드 서버가 같은 버전을 쓰게 합니다.

에셋: 이미지, 글꼴, 데이터 파일

앱에 포함할 파일은 pubspec.yaml의 flutter: assets:에 등록해야 빌드에 들어갑니다. 폴더 이름 끝에 /를 붙이면 그 폴더의 파일 전체가 포함됩니다(하위 폴더는 따로 적어야 합니다).

import 'dart:convert';
import 'package:flutter/services.dart' show rootBundle;

// 이미지 에셋 표시
Image.asset('assets/images/logo.png', width: 120);

// 텍스트·JSON 에셋 읽기
Future<Map<String, dynamic>> loadConfig() async {
  final text = await rootBundle.loadString('assets/data/config.json');
  return jsonDecode(text) as Map<String, dynamic>;
}

글꼴은 flutter: fonts: 항목에 family와 파일 경로를 적어 등록하고, TextStyle(fontFamily: '이름')으로 씁니다.

플랫폼 폴더

android, ios, web, windows, macos, linux 폴더는 각 플랫폼의 실제 네이티브 프로젝트입니다. 평소에는 건드릴 일이 적지만 다음 경우에는 직접 수정합니다.

• 앱 이름, 아이콘, 권한: Android는 android/app/src/main/AndroidManifest.xml, iOS는 ios/Runner/Info.plist
• Android 패키지 이름(applicationId), 최소 SDK, 서명 설정: android/app/build.gradle.kts(이전 프로젝트는 build.gradle)
• iOS 번들 식별자와 서명: Xcode에서 ios/Runner.xcworkspace를 열어 설정
• 웹 페이지 제목과 PWA 정보: web/index.html, web/manifest.json

나중에 플랫폼을 추가하려면 프로젝트 폴더에서 flutter create --platforms=web,windows .를 실행합니다.

analysis_options.yaml

이 파일은 flutter_lints 패키지의 권장 규칙을 불러옵니다. flutter analyze를 실행하면 규칙 위반과 잠재적 오류를 보여 주며, 편집기도 같은 결과를 실시간으로 표시합니다. dart format .으로 코드 서식을 맞출 수 있습니다.

정리

• Dart 코드는 lib, 테스트는 test, 플랫폼별 네이티브 프로젝트는 각 플랫폼 폴더에 있습니다.
• pubspec.yaml에 의존성, 버전, 에셋, 글꼴을 적고 flutter pub add로 패키지를 추가합니다.
• 에셋은 pubspec.yaml에 등록해야 앱에 포함됩니다.
• 권한, 아이콘, 서명 같은 플랫폼 설정은 해당 플랫폼 폴더에서 수정합니다.