---

Giải thích cấu trúc thư mục của một dự án Flutter

Khi bắt đầu học Flutter, một trong những điều quan trọng nhất là hiểu rõ cấu trúc thư mục của dự án. Bài viết này sẽ giúp bạn nắm vững cách Flutter tổ chức code và tài nguyên trong một dự án.

Tổng quan cấu trúc dự án Flutter

Khi tạo một dự án Flutter mới bằng lệnh flutter create my_app, bạn sẽ thấy cấu trúc thư mục như sau:

my_app/
├── android/
├── ios/
├── lib/
├── test/
├── web/
├── windows/
├── macos/
├── linux/
├── pubspec.yaml
├── README.md
└── .gitignore

Thư mục lib/ – Nơi chứa code chính

Thư mục lib/ là nơi quan trọng nhất, chứa toàn bộ code Dart của ứng dụng Flutter.

Cấu trúc cơ bản của lib/

lib/
├── main.dart
└── (các file .dart khác)

File main.dart

main.dart là file entry point của ứng dụng Flutter. Đây là nơi ứng dụng bắt đầu chạy:

import 'package:flutter/material.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: HomePage(),
    );
  }
}

Cấu trúc lib/ được khuyến nghị

Khi dự án phát triển, bạn nên tổ chức code theo cấu trúc sau:

lib/
├── main.dart
├── models/          # Data models
│   ├── user.dart
│   └── product.dart
├── screens/         # Các màn hình
│   ├── home_screen.dart
│   ├── login_screen.dart
│   └── profile_screen.dart
├── widgets/         # Custom widgets
│   ├── custom_button.dart
│   └── custom_card.dart
├── services/        # Business logic, API calls
│   ├── api_service.dart
│   └── auth_service.dart
├── utils/           # Utilities, helpers
│   ├── constants.dart
│   └── helpers.dart
└── providers/       # State management (nếu dùng Provider)
    └── user_provider.dart

Thư mục android/ – Code Android native

Thư mục android/ chứa code Android native, được sử dụng khi build ứng dụng cho Android.

Cấu trúc android/

android/
├── app/
│   ├── build.gradle
│   ├── src/
│   │   └── main/
│   │       ├── AndroidManifest.xml
│   │       ├── kotlin/
│   │       └── res/
│   └── build/
├── build.gradle
└── settings.gradle

File quan trọng:

• AndroidManifest.xml: Cấu hình ứng dụng Android (permissions, activities, etc.)
• build.gradle: Cấu hình build và dependencies cho Android
• kotlin/: Code Kotlin native (nếu cần)

Khi nào cần chỉnh sửa android/?

• Thêm permissions (camera, location, internet, etc.)
• Cấu hình app icon và splash screen
• Tích hợp native Android libraries
• Thay đổi package name

Thư mục ios/ – Code iOS native

Thư mục ios/ chứa code iOS native, được sử dụng khi build ứng dụng cho iOS.

Cấu trúc ios/

ios/
├── Runner/
│   ├── Info.plist
│   ├── Assets.xcassets/
│   └── AppDelegate.swift
├── Podfile
└── Flutter/

File quan trọng:

• Info.plist: Cấu hình ứng dụng iOS (permissions, bundle ID, etc.)
• Podfile: Quản lý CocoaPods dependencies
• AppDelegate.swift: Entry point của ứng dụng iOS

Khi nào cần chỉnh sửa ios/?

• Thêm permissions (camera, location, etc.)
• Cấu hình app icon và launch screen
• Tích hợp native iOS libraries
• Thay đổi bundle identifier

Thư mục test/ – Unit tests và Integration tests

Thư mục test/ chứa các file test cho ứng dụng.

Cấu trúc test/

test/
├── widget_test.dart
├── unit_test.dart
└── integration_test/
    └── app_test.dart

Các loại test:

1. Unit tests: Test các function và class riêng lẻ
2. Widget tests: Test các widget Flutter
3. Integration tests: Test toàn bộ flow của ứng dụng

Ví dụ unit test:

import 'package:flutter_test/flutter_test.dart';
import 'package:my_app/utils/calculator.dart';

void main() {
  test('Calculator should add two numbers', () {
    final calculator = Calculator();
    expect(calculator.add(2, 3), 5);
  });
}

File pubspec.yaml – Cấu hình dự án

pubspec.yaml là file cấu hình quan trọng nhất của dự án Flutter, tương tự như package.json trong Node.js.

Cấu trúc pubspec.yaml:

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

environment:
  sdk: '>=3.0.0 <4.0.0'

dependencies:
  flutter:
    sdk: flutter
  cupertino_icons: ^1.0.2
  http: ^1.1.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.0

flutter:
  uses-material-design: true

  assets:
    - images/
    - icons/

  fonts:
    - family: CustomFont
      fonts:
        - asset: fonts/CustomFont-Regular.ttf

Các phần quan trọng:

1. name: Tên package của ứng dụng
2. version: Phiên bản ứng dụng
3. dependencies: Các package cần thiết cho ứng dụng
4. dev_dependencies: Các package chỉ dùng khi development
5. flutter.assets: Đường dẫn đến images, fonts, etc.
6. flutter.fonts: Cấu hình custom fonts

Cách thêm package:

dependencies:
  http: ^1.1.0        # Package để gọi API
  provider: ^6.1.1   # State management
  shared_preferences: ^2.2.2  # Lưu trữ local

Sau đó chạy:

flutter pub get

Thư mục web/ – Code cho Web

Thư mục web/ chứa code và cấu hình cho phiên bản web của ứng dụng.

Cấu trúc web/

web/
├── index.html
├── manifest.json
└── icons/

File quan trọng:

• index.html: Entry point của ứng dụng web
• manifest.json: Cấu hình PWA (Progressive Web App)

Thư mục windows/, macos/, linux/ – Desktop platforms

Các thư mục này chứa code native cho các nền tảng desktop:

• windows/: Code cho Windows desktop
• macos/: Code cho macOS desktop
• linux/: Code cho Linux desktop

File .gitignore

File .gitignore xác định các file và thư mục không cần commit lên git:

# Build files
build/
.dart_tool/

# IDE files
.idea/
.vscode/
*.iml

# OS files
.DS_Store
Thumbs.db

Cấu trúc thư mục được khuyến nghị cho dự án lớn

Với dự án lớn, bạn nên tổ chức code theo kiến trúc rõ ràng:

lib/
├── main.dart
├── app.dart
├── config/
│   ├── routes.dart
│   └── theme.dart
├── core/
│   ├── constants/
│   ├── errors/
│   └── utils/
├── features/
│   ├── auth/
│   │   ├── data/
│   │   ├── domain/
│   │   └── presentation/
│   ├── home/
│   │   ├── data/
│   │   ├── domain/
│   │   └── presentation/
│   └── profile/
│       ├── data/
│       ├── domain/
│       └── presentation/
└── shared/
    ├── widgets/
    └── services/

Giải thích kiến trúc Clean Architecture:

• data/: Data sources, repositories implementation
• domain/: Business logic, entities, use cases
• presentation/: UI, widgets, screens, state management

Các thư mục và file khác

.dart_tool/

Thư mục chứa các file cache và tool của Dart SDK. Không cần commit lên git.

build/

Thư mục chứa các file build output. Được tạo tự động khi build ứng dụng.

.packages và pubspec.lock

• .packages: Danh sách các package đã cài (tự động tạo)
• pubspec.lock: Lock file cho dependencies (nên commit)

Best Practices

1. Tổ chức code theo feature

Thay vì tổ chức theo kiểu (screens, widgets, models), nên tổ chức theo feature:

lib/
├── features/
│   ├── authentication/
│   │   ├── screens/
│   │   ├── widgets/
│   │   └── models/
│   └── products/
│       ├── screens/
│       ├── widgets/
│       └── models/

2. Tách biệt business logic và UI

// ❌ Không nên: Business logic trong widget
class ProductList extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // Logic lấy data ở đây - KHÔNG TỐT
    final products = fetchProducts();
    return ListView(...);
  }
}

// ✅ Nên: Tách business logic ra service
class ProductService {
  Future<List<Product>> getProducts() {
    // Logic ở đây
  }
}

class ProductList extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // Chỉ render UI
  }
}

3. Sử dụng constants

Tạo file lib/utils/constants.dart để lưu các hằng số:

class AppConstants {
  static const String apiBaseUrl = 'https://api.example.com';
  static const int maxRetryAttempts = 3;
  static const Duration requestTimeout = Duration(seconds: 30);
}

4. Quản lý assets có tổ chức

assets/
├── images/
│   ├── logos/
│   ├── icons/
│   └── backgrounds/
├── fonts/
└── data/
    └── sample_data.json

Lệnh hữu ích

Xem cấu trúc dự án:

# Windows
tree /F

# Mac/Linux
tree

Tạo file mới:

# Tạo screen mới
touch lib/screens/new_screen.dart

# Tạo model mới
touch lib/models/new_model.dart

Clean build:

flutter clean
flutter pub get

Kết luận

Hiểu rõ cấu trúc thư mục Flutter giúp bạn:

• ✅ Tổ chức code một cách có hệ thống
• ✅ Dễ dàng tìm và sửa code
• ✅ Làm việc nhóm hiệu quả hơn
• ✅ Maintain code dễ dàng hơn

Tóm tắt:

• lib/: Code chính của ứng dụng
• android/, ios/: Code native cho từng platform
• test/: Unit tests và integration tests
• pubspec.yaml: Cấu hình dependencies và assets
• web/, windows/, macos/, linux/: Code cho các platform khác

Bắt đầu với cấu trúc đơn giản, sau đó mở rộng dần khi dự án phát triển. Quan trọng nhất là giữ code có tổ chức và dễ đọc!

---

Tác giả: Admin
Ngày đăng: 20/01/2025
Chuyên mục: Flutter