Анатомия Flutter-проекта

и честное предупреждение об этой главе

Что это

Flutter — способ написать приложение один раз и собрать его под Android, iOS, веб и десктоп. Язык — Dart.

Прежде чем начать, одно предупреждение, которое касается всей главы.

Это неприятно, но честнее, чем делать вид. Заодно это ровно та ситуация, о которой вся книга: уверенный текст не равен проверенному тексту (статья 1.6). Относись к этой главе так же, как к ответу ИИ по редкой библиотеке, — читай, но сверяй.

Как выглядит в коде

weather_app/
├── lib/                    ← твой код, только он
│   ├── main.dart           точка входа
│   ├── screens/            экраны
│   ├── widgets/            переиспользуемые куски интерфейса
│   ├── models/             описание данных
│   └── services/           сеть, база, работа с API
├── test/                   тесты
├── android/                платформенные файлы Android
├── ios/                    платформенные файлы iOS
├── web/                    файлы для сборки под веб
├── pubspec.yaml            зависимости и ресурсы
├── pubspec.lock            точные версии — коммитить
└── .dart_tool/             служебное, не трогать

Структура знакомая: читать надо lib/, всё остальное — обвязка. Ровно то же правило, что src/ в React-проекте (статья 10.1).

Папки android/ и ios/ — настоящие нативные проекты. Туда заглядывают редко: когда нужны разрешения, иконки, подпись приложения. Это тема главы 12.

pubspec.yaml

Аналог package.json, но ещё и список ресурсов:

name: weather_app
environment:
  sdk: ^3.5.0

dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^4.0.0

flutter:
  uses-material-design: true
  assets:
    - assets/icons/

Два отличия от других экосистем, о которых стоит знать:

Ресурсы объявляются явно. Картинку положить в папку мало — её надо прописать в assets. Забыл — приложение не найдёт файл во время работы, и ошибка будет не при сборке, а при открытии экрана. ИИ забывает про это регулярно.

Отступы значимы. YAML, как и Python, чувствителен к пробелам, и неверный отступ ломает файл целиком.

Команды

flutter pub get          # поставить зависимости
flutter run              # запустить на устройстве или эмуляторе
flutter analyze          # статический анализ — аналог tsc и mypy
flutter test             # тесты
flutter build apk        # сборка (глава 12)

flutter analyze — самая важная из них для работы с ИИ. Это тот же рубеж, что mypy --strict в Python (статья 6.3) и tsc --noEmit в TypeScript (9.3): проверка до запуска. В Dart типы обязательны, поэтому анализатор ловит много.

Как сказать ИИ

Покажи структуру lib/ этого проекта: что в каждой папке,
по строке. android/, ios/ и .dart_tool не показывай.

Я добавил картинку в assets/icons/. Что нужно прописать
в pubspec.yaml, чтобы она работала? Покажи точный отступ.

Версия Flutter у меня 3.38, Dart 3.10. Пиши код только
под них и скажи, если что-то из предложенного появилось
в более поздних версиях.

Последний запрос особенно уместен именно здесь: Flutter меняет API между мажорными версиями чаще, чем большинство фреймворков, а обучающих данных для старых версий больше (статья 3.1, причина 3).

На что смотреть

Код для старых версий. Самый частый признак — устаревшие имена виджетов и параметров. Если flutter analyze ругается на незнакомые аргументы — скорее всего, дело в версии.

Ресурс не объявлен в pubspec.yaml. Ошибка появится при открытии экрана, а не при сборке.

Нет pubspec.lock в репозитории. Версии разъедутся (статья 5.6).

Всё в main.dart. Файл на тысячу строк вместо экранов и виджетов.

Правки в android/ и ios/ без объяснения. Эти папки частично генерируются; изменения там легко потерять при обновлении инструментов.

Шпаргалка