Войти в ID

2.1. Flutter: структура проекта

Авторы
Софья Тимохина

Dart — язык программирования, разработанный компанией Google, а Flutter — кросс-платформенный UI-фреймворк, написанный на языке Dart.

Flutter позволяет разрабатывать приложения, которые могут работать на шести платформах: Android, iOS, Linux, MacOS, Web и Windows. Благодаря этому разработчики экономят время и ресурсы: не нужно создавать и поддерживать отдельные версии приложений для каждой платформы.

В этом параграфе мы познакомимся со структурой Flutter-приложения, узнаем о каждой папке и файле, чтобы в будущем было проще ориентироваться в проекте. А начнём с установки фреймворка.

Установка Flutter

Начать писать на Flutter легко — достаточно установить необходимые инструменты по шагам:

  1. Зайти на docs.flutter.dev.

  2. Установить окружение и инструменты по инструкции.

  3. Выбрать удобную среду разработки.

  4. Создать проект с помощью команды flutter create my_app — и вот базовое приложение готово.

Ниже в статье часто будет упоминаться инструмент командной строки pub, используемый для управления зависимостями и пакетами в Dart- и Flutter-проектах.

Он входит в состав Dart SDK и предоставляет удобные средства для разработки приложений. Запуск любого проекта начинается с команды flutter pub get, которая устанавливает необходимые зависимости, в том числе и Flutter.

Теперь давайте подробнее рассмотрим базовую структуру Flutter-проекта.

Структура проекта

Проекты во Flutter делятся на два типа: приложения и библиотеки.

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

О библиотеках, их установке и создании собственной библиотеки мы подробнее поговорим в следующем параграфе.

И у приложений, и у библиотек схожая структура, они содержат следующие папки и файлы:

flutter2

Рассмотрим их все по очереди.

Платформенные папки

Папки android, ios, linux, macos, web и windows содержат код и настройки, специфичные для каждой платформы. В них находятся файлы и каталоги, необходимые для сборки, упаковки и запуска приложения на соответствующей платформе.

У каждой из этих папок есть свой собственный набор инструментов и зависимостей, которые нужно установить и настроить, чтобы успешно собрать и запустить приложение на нужной платформе. При разработке Flutter-приложений важно учитывать эти различия и тестировать приложение на всех платформах, для которых оно предназначено.

Если планируется, что проект будет поддерживать только определённые платформы, то их можно перечислить при создании проекта в параметре --platforms, передав через запятую список необходимых платформ.

Например, если планируется, что проект будет поддерживать только Android и iOS, то команда будет выглядеть следующим образом: flutter create --platforms=ios,android ..

lib

Папка lib в проекте Flutter — это основная папка, в которой располагается весь исходный код приложения. В ней находятся все Dart-файлы проекта, определяющие логику и интерфейс приложения. В этой папке лежит файл main.dart.

main.dart

Файл main.dart в проекте Flutter — точка входа в приложение, где находится главный метод main(). Этот файл содержит основной код приложения и выступает отправной точкой для его запуска.

В файле main.dart не рекомендуется размещать много логики или множество UI-компонентов, так как это может привести к перегруженности и неудобству в разработке и поддержке кода. Часто в этом файле создаётся лишь функция main, а более сложная логика выносится в отдельные файлы и классы.

pubspec.yaml

Файл pubspec.yaml относится к важным компонентам проекта Flutter или Dart. Он определяет конфигурацию проекта и используется, чтобы определить зависимости, версии библиотек, настройки сборки и другие свойства.

Ниже представлен пример для проекта под названием my_app:

1name: my_app
2description: A new Flutter project.
3
4publish_to: 'none'
5version: 1.0.0
6
7homepage: https://my_project_site.com
8repository: https://github.com/my_project_url
9issue_tracker: https://github.com/<my_project_url>/issues
10documentation: https://my_project_site.com/documentation
11
12environment:
13  sdk: '>=2.18.0 <3.0.0'
14
15flutter:
16  uses-material-design: true

Есть обязательные параметры файла pubspec.yaml:

  • name — имя проекта. Чаще всего оно совпадает с папкой, в которой лежит проект.
  • environment — параметр, отвечающий за окружение проекта — версию Dart и Flutter. В нашем pubspec.yaml используется параметр sdk для указания версии Dart.

Есть также обязательные для библиотек параметры:

  • version — актуальная версия библиотеки;
  • description — описание проекта. Для каждого нового проекта оно будет как в примере выше — “A new Flutter project”.

И несколько необязательных параметров:

  • homepage — ссылка на главную страницу проекта, чаще оставляют ссылку на репозиторий;
  • repository — ссылка на репозиторий проекта с исходным кодом;
  • issue_tracker — ссылка на трекер проблем и предложений от тех, кто пользуется проектом. Например, иногда указывают ссылку на секцию “Issue” в GitHub;
  • documentation — ссылка на документацию проекта;
  • executables — скрипты проекта в виде исполняемых файлов, которые могут быть запущены из командной строки:
1executables:
2    ## При активации с помощью команды pub global activate и ввода my_command_1 запустится bin/main.dart
3    my_command_1: main
4    ## При активации с помощью команды pub global activate и ввода my_command_2 запустится bin/my_command_2.dart
5    my_command_2

​

  • platforms — платформы, которые поддерживает проект:
1## Этот проект поддерживает все платформы
2platforms:
3  android:
4  ios:
5  linux:
6  macos:
7  web:
8  windows:

1## А этот — только Android и iOS
2platforms:
3  android:
4  ios:
  • publish_to — ссылка на сервер публикации пакетов, где находится библиотека. Если данный параметр пустой, то публикуемые пакеты отправляются на pub.dev, о котором мы поговорим в следующем параграфе. Если не хотите публиковать проект, можно указывать none. Также этот параметр можно использовать для указания пользовательского сервера публикации пакетов:
1publish_to: 'none'
  • funding — список ссылок, по которым можно перейти и проспонсировать автора разработки:
1funding:
22 - https:*//www.buymeacoffee.com/example_user*
33 - https:*//www.patreon.com/some-account*
  • false_secrets — секция для указания файлов, для которых мы не проверяем наличие секретов. При публикации пакета pub проверяет, нет ли в коде различных секретов: API ключей или криптографических данных. Если такие вдруг обнаружились, то пакет не публикуется. Но проверка может сработать ложно — принять за секрет файл, который им не является. Поэтому если проверка срабатывает на файл, но вы уверены, что он не содержит секретов, то его можно добавить в поле false_secrets, и проверка будет его игнорировать:
1false_secrets:
2    ## Не смотрим для файла hardcoded_api_key.dart
3    - /lib/src/hardcoded_api_key.dart
4    ## Не смотрим для всех файлов с расширением .pem в папке localhost_certificates
5    - /test/localhost_certificates*/*.pem*
  • screenshots — скриншоты, связанные с библиотекой: примеры виджетов или других визуальных элементов проекта:
1screenshots:
2  - description: 'Тут мы описываем, что показано на изображении.'
3    path: path/to/image/**in**/package/500x500.webp **## А тут оставляем ссылку**
  • и зависимости: dependencies, dev_dependencies и dependency_overrides. О них мы поговорим в следующем параграфе.

Файл pubspec.yaml, использующий все доступные поля, будет выглядеть следующим образом:

1name: my_app
2description: A new Flutter project.
3
4publish_to: 'none'
5version: 1.0.0
6
7homepage: https://my_project_site.com
8repository: https://github.com/my_project_url
9issue_tracker: https://github.com/<my_project_url>/issues
10documentation: https://my_project_site.com/documentation
11
12environment:
13  sdk: '>=2.18.0 <3.0.0'
14
15dependencies:
16  flutter:
17    sdk: flutter
18  cupertino_icons: ^1.0.2
19
20dev_dependencies:
21  flutter_test:
22    sdk: flutter
23  flutter_lints: ^2.0.0
24
25executables:
26    ## При активации с помощью команды pub global activate и ввода my_command_1 запустится bin/main.dart
27    my_command_1: main
28    ## При активации с помощью команды pub global activate и ввода my_command_2 запустится bin/my_command_2.dart
29    my_command_2
30
31flutter:
32  uses-material-design: true
33## Этот проект поддерживает все платформы
34platforms:
35  android:
36  ios:
37  linux:
38  macos:
39  web:
40  windows:

analysis_options.yaml

Этот файл позволяет настраивать конфигурацию линтера. Библиотеки для линтера предоставляют стандартный набор правил, который может быть применён в проекте, но пользователь может изменять и дополнять этот набор в соответствии с требованиями проекта.

В примере ниже используется пакет lints. Это официальная библиотека для Dart-проектов, содержащая все рекомендуемые правила. Помимо этого, в примере добавлены правила, которые вносят ограничения дополнительно к тем, что есть у самой библиотеки.

1include: package:lints/recommended.yaml
2
3analyzer:
4  exclude: [build/**]
5  language:
6    strict-inference: true
7    strict-raw-types: true
8
9linter:
10  rules:
11    - cancel_subscriptions

Поле include позволяет задавать правила из другого файла. В примере выше правила из файла recommended.yaml в пакете lints переиспользуются в analysis_options.yaml.

Поле analyzer — для настройки статического анализа: включения более строгих проверок типов, исключения файлов, игнорирования определённых правил, изменения строгости правил или включения экспериментов. Так, флаг strict-inference: true будет ругаться на строку кода final myMap = {};. Поле linter используется для кастомизации линтера, для удаления правил и добавления новых.

Подробнее о доступных правилах можно прочесть тут, а о расширении правил — вот тут.

test

В этой папке будут находиться юнит- и виджет-тесты, если вы их напишите. Подробнее о тестах мы поговорим в главе «Стабильность».

.gitignore

Это файл, который позволяет указать, какие файлы или папки проекта нужно игнорировать в системе контроля версий git.

1folder_name/               # Игнорируем всю папку folder_name
2folder_name/subfolder_name # Игнорируем всю папку subfolder_name, лежащую в папке folder_name
3**/folder_name/             # Игнорируем все папки в проекте с названием folder_name
4**/*.png                    # Игнорируем все файлы проекта с расширением png
5folder_name/file_name.dart  # Игнорируем файл file_name.dart в папке folder_name

Для Dart- и Flutter-проектов, помимо всего остального, рекомендуется добавлять папки .dart_tool и build в файл .gitignore, а для библиотек добавлять в тот же файл дополнительно к папкам, перечисленным ранее, файл pubspec.lock.

README

README — это файл, который содержит информацию о проекте, его назначении, функциональности и использовании. Это первый файл, который разработчик или пользователь читает, когда знакомится с проектом, обычно он расположен в корневой директории проекта.

Файл README часто используется для следующей инфрормации:

  • описание проекта — это обычно первый абзац файла README;
  • установка и запуск — инструкции по установке и запуску проекта, которые должны помочь пользователям начать работу с проектом;
  • использование — детальное описание функциональности проекта и того, как использовать различные компоненты или функции;
  • примеры — примеры использования проекта, которые могут помочь пользователям лучше понять, как он работает и что можно сделать с его помощью;
  • зависимости — список зависимостей и версий пакетов, которые необходимы для работы проекта;
  • лицензия — информация о правах и ограничениях использования проекта, включая его лицензию.

Хорошо написанный файл README помогает пользователям быстро вникнуть в проект и начать работу с ним.

Он также может служить важным источником документации по проекту как для разработчиков, так и для конечных пользователей. Важно помнить, что файл README открыт для всех, поэтому в нём не следует размещать конфиденциальную информацию.

LICENSE

Для публичных репозиториев принято добавлять файл LICENSE, чтобы лицензировать код. Это позволяет другим пользователям добавлять, изменять и распространять код. Некоторые лицензии не накладывают никаких ограничений на разработчиков, которые хотят переиспользовать написанный код, а некоторые обязывают указывать имя репозитория или автора или даже платить за использование пакета.

Существует большое количество лицензий, и иногда найти подходящую достаточно сложно. Эту проблему поможет решить проект choosealicense, разработанный GitHub. Он помогает разобраться в том, какие лицензии существуют, какие есть между ними различия и какая подходит именно для вашего проекта.

.dart_tool

Папка .dart_tool создаётся автоматически при выполнении операций, связанных с инструментами и пакетами в проекте. Внутри этой папки содержатся временные файлы, кеши, артефакты и другие данные, которые генерируются при компиляции, анализе и выполнении кода.

Вот несколько распространённых файлов и папок, которые могут находиться внутри папки .dart_tool:

  • build — папка, где сохраняются результаты сборки проекта. В ней могут быть подпапки, связанные с конфигурацией среды выполнения и инструментами сборки;
  • .dart_tool/package_config.json — файл, содержащий информацию о зависимостях проекта, включая пути к пакетам, используемым в проекте;
  • .dart_tool/package_config_subset — данный файл содержит подмножество информации о зависимостях, необходимых для быстрого запуска или сборки проекта;
  • .dart_tool/pub — эта папка содержит временные файлы, связанные с менеджером пакетов pub для установки и обновления зависимостей проекта.

.metadata

.metadata — приватный файл, который среда разработки использует, чтобы отслеживать параметры Flutter-проекта. В таком файле может находиться информация о версии фреймворка, который используется в проекте, вспомогательные файлы для миграции проекта на другую версию фреймворка и так далее.

👉 Этот файл автоматически создаётся средой разработки и не должен редактироваться вручную.

dart doc

И напоследок — полезная команда dart doc. Она позволяет генерировать документацию по комментариям в коде. Вот пример таких комментариев:

1///
2/// Короткий комментарий для класса Model
3///
4class Model {}
5
6/*
7   * Это длинный комментарий для функции functionGetModel
8     Он может указывать на [Model], будет автоматически оставлена ссылка в документации на этот класс
9     Он также может указывать на [function], будет автоматически оставлена ссылка в документации на эту функцию
10   
11*/
12Model functionGetModel() {
13    ...
14}

Для генерации документации нужно использовать команду dart doc ..

Вот и всё! Мы рассмотрели важные папки и файлы проекта: папки платформ, конфигурационные файлы, файл настройки линтера и дугие.

Эти части проекта будут встречаться нам ещё неоднократно в процессе разработки. А в следующем параграфе мы поговорим о работе с зависимостями — библиотеках, которые можно использовать для упрощения и ускорения процесса создания приложений

Полезные ссылки

Чтобы добавить в заметки выделенный текст, нажмите Ctrl + E
Предыдущий параграф1.1. Введение
Следующий параграф2.2. Flutter: зависимости проекта