Floor — что это, ORM поверх SQLite во Flutter

Что такое Floor?

Floor — это ORM-библиотека для Flutter и Dart, построенная на основе SQLite. Она использует аннотации для описания сущностей (Entity), Data Access Object (DAO) и базы данных (Database). Генерация кода выполняется через build_runner и floor_generator — компилятор создаёт реализации DAO и управляющий класс базы данных. В отличие от raw sqflite, Floor полностью устраняет необходимость ручного преобразования ResultSet в Dart-объекты, автоматически маппя столбцы на поля Entity через отражение типов.

Floor следует шаблону Repository + DAO, знакомому разработчикам Android по Room. Каждая таблица представлена Dart-классом с аннотацией @Entity, SQL-запросы группируются в интерфейсах с аннотацией @dao, а база данных собирается в абстрактном классе с @Database. Такой подход строго разделяет модель данных и логику запросов.

По данным Flutter Pulse (2023), Floor выбирают в 28% Flutter-проектов, где требуется локальная БД. Основные причины выбора — знакомство с SQL (не нужно учить новый язык запросов) и проверка запросов на этапе компиляции. Кроме того, Floor генерирует читаемый код, который легко отлаживать в отличие от более абстрактных ORM с кастомным DSL, что снижает порог входа для новых разработчиков в команде.

Архитектура Floor

Floor состоит из трёх слоёв: Entity (модель таблицы), DAO (интерфейс запросов) и Database (точка входа). Генератор создаёт реализации _$_Entity для маппинга полей и _$_Dao для выполнения SQL. При изменении Entity или DAO достаточно перезапустить build_runner — код обновится автоматически. Для миграции между версиями схемы Floor использует последовательные номера версий, что гарантирует целостность данных при обновлении приложения на устройствах пользователей.

Как работает Floor во Flutter?

Floor использует SQLite через пакет sqflite для платформенных сборок и sqlite3 для десктопа и web. При запуске приложения Floor создаёт или открывает SQLite-файл, применяет миграции и подготавливает DAO-методы для выполнения запросов. Все операции выполняются в асинхронном режиме через Future и Stream.

Генерация кода в Floor работает по следующему принципу: парсер считывает аннотации из исходников, создаёт AST (Abstract Syntax Tree) моделей и запросов, после чего генерирует Dart-файлы с префиксом _$. Сгенерированный код включает мапперы ResultSet → Entity и обратно.

Потокобезопасность

Floor работает с SQLite в одном изоляте. Все запросы выполняются асинхронно, но конкурентные записи блокируются на уровне SQLite. Для транзакций используется @transaction аннотация, которая гарантирует атомарность группы запросов и откат при ошибке.

Floor vs Drift: сравнение ORM для Flutter

И Floor, и Drift — ORM поверх SQLite, но они различаются по философии. Floor ближе к Room из Android, Drift — более реактивный с встроенным Stream API и компиляцией запросов через SQL-файлы. Выбор между ними зависит от опыта команды и требуемой реактивности.

Когда выбирать Floor

Floor — выбор команд, уже знакомых с SQL и Android Room. Если разработчики привыкли писать SQL-запросы вручную и хотят минимальную обёртку над SQLite — Floor даёт типизацию без изучения нового DSL. Он также проще в отладке, так как сгенерированный код читаем и предсказуем.

Когда лучше Drift

Drift даёт более мощную реактивность и поддерживает больше платформ. Если приложение активно использует Stream для обновления UI, требует сложных запросов с JOIN и подзапросами или собирается под web — Drift предпочтительнее. Однако его порог входа выше из-за необходимости изучения собственного DSL.

Примеры кода с Floor

Floor строится вокруг аннотаций. Ниже приведён полный пример Entity, DAO и Database для приложения-списка задач. После запуска build_runner сгенерированные классы готовы к использованию.

Определение Entity и DAO

Класс TaskEntity с аннотацией @Entity маппится на таблицу task. Поле с @primaryKey становится первичным ключом. Интерфейс TaskDao содержит методы для операций с таблицей — каждый метод аннотирован @Query, @Insert, @Update или @Delete.

@entity
class TaskEntity {
    @PrimaryKey(autoGenerate: true)
    final int id;
    final String title;
    final bool isCompleted;
    final int priority;

    TaskEntity({this.id, required this.title,
        this.isCompleted = false, this.priority = 0});
}

@dao
abstract class TaskDao {
    @Query('SELECT * FROM TaskEntity ORDER BY priority DESC')
    Future<List<TaskEntity>> getAllTasks();

    @Insert
    Future<int> insertTask(TaskEntity task);

    @Update
    Future<void> updateTask(TaskEntity task);

    @Query('SELECT * FROM TaskEntity WHERE isCompleted = :status')
    Stream<List<TaskEntity>> watchTasks(bool status);
}

Инициализация базы данных

Абстрактный класс с аннотацией @Database связывает Entity и DAO. Метод databaseBuilder создаёт экземпляр базы. После вызова build база готова: Floor открывает SQLite-файл, применяет миграции и возвращает DAO для работы.

@Database(version: 1, entities: [TaskEntity])
abstract class AppDatabase extends FloorDatabase {
    TaskDao get taskDao;
}

// Использование
final database = await $FloorAppDatabase.databaseBuilder('app.db').build();
final taskDao = database.taskDao;
final tasks = await taskDao.getAllTasks();

Реактивные запросы через Stream

Floor поддерживает возврат Stream из DAO-методов. При любых изменениях в таблице Stream испускает новый список. Это интегрируется с StreamBuilder во Flutter — UI автоматически обновляется при добавлении, изменении или удалении записей.

@Query('SELECT * FROM TaskEntity ORDER BY priority DESC')
Stream<List<TaskEntity>> watchAllTasks();

// Во Flutter-виджете
StreamBuilder<List<TaskEntity>>(
    stream: taskDao.watchAllTasks(),
    builder: (context, snapshot) {
        final tasks = snapshot.data ?? [];
        return ListView.builder(
            itemCount: tasks.length,
            itemBuilder: (_, i) => TaskTile(tasks[i]),
        );
    },
)

Миграции и версионирование в Floor

Floor поддерживает версионирование базы данных через параметр version в аннотации @Database. При изменении Entity (добавлении или удалении полей) нужно увеличить версию и добавить миграцию. Миграция — это Dart-функция, которая получает транзакцию и выполняет SQL-запросы ALTER TABLE.

Пример миграции

Допустим, в версии 2 мы добавили поле dueDate в TaskEntity. Миграция выполняется SQL-запросом ALTER TABLE. Если миграция не указана, Floor вызывает MigrationStrategy, где можно задать fallback (например, пересоздание таблицы с потерей данных).

Тестирование запросов Floor

Floor не предоставляет встроенного мок-фреймворка, но базу данных можно легко заменить в тестах. Создайте inMemoryDatabaseBuilder — он создаёт SQLite-базу в памяти, идентичную по схеме продакшну. После каждого теста очищайте данные через deleteDatabase для изоляции тестовых сценариев.

Транзакции и пакетные операции в Floor

Floor поддерживает транзакции через аннотацию @transaction на DAO-методе. Внутри транзакции выполняются несколько запросов последовательно с гарантией отката при ошибке. Пакетная вставка через @Insert с параметром List оптимизирует вставку множества записей за один вызов — это в несколько раз быстрее, чем вставка по одной записи в цикле. Для массовых операций используйте batch-вставку по 100–200 записей: это оптимальный баланс между скоростью выполнения и потреблением оперативной памяти на мобильных устройствах с ограниченными ресурсами.

final migration1to2 = Migration(1, 2, (database) async {
    await database.execute(
        'ALTER TABLE TaskEntity ADD COLUMN dueDate TEXT'
    );
});

final database = await $FloorAppDatabase.databaseBuilder('app.db')
    .addMigrations([migration1to2])
    .build();