跨平台开发 / 系统课时

插入和批量写入数据

插入和批量写入数据

SQLite 表创建完成后,下一步是把 Dart 对象转换为数据库能够保存的键值记录。本节用一个任务模型演示单条插入和事务式批量写入,并通过查询结果确认主键生成、布尔值转换和多条数据提交都符合预期。

学习目标

  • 将 Dart 数据模型转换为 SQLite 可写入的 Map<String, Object?>
  • 使用 insert 完成单条记录写入并取得主键
  • 使用 Batch 在一个事务中高效写入多条记录

把模型转换为数据库记录

应用模型和数据库记录不应该完全混在一起。模型可以保留 Dart 类型,而 toMap 专门处理 SQLite 所需的字段格式。

dart
class Task {
  const Task({
    this.id,
    required this.title,
    required this.isDone,
    required this.createdAt,
  });

  final int? id;
  final String title;
  final bool isDone;
  final DateTime createdAt;

  Map<String, Object?> toMap() {
    return {
      if (id != null) 'id': id,
      'title': title,
      'is_done': isDone ? 1 : 0,
      'created_at': createdAt.millisecondsSinceEpoch,
    };
  }
}

这里没有把空的 id 写入记录,因为新数据应让 SQLite 自动生成主键。bool 被转换成 0 或 1,DateTime 则转换为毫秒时间戳,读取时再恢复成 Dart 类型。

插入一条记录

假设项目已经使用上一节的 AppDatabase 初始化了 tasks 表,可以直接调用 Database.insert。该方法成功后会返回新记录的行 ID。

dart
Future<void> insertOneTask() async {
  final db = await AppDatabase.instance.database;

  final task = Task(
    title: '缓存接口数据',
    isDone: false,
    createdAt: DateTime.fromMillisecondsSinceEpoch(1700000000000),
  );

  final id = await db.insert('tasks', task.toMap());
  print('inserted id: $id');

  final rows = await db.query(
    'tasks',
    where: 'id = ?',
    whereArgs: [id],
  );
  print(rows);
}

预期输出

text
inserted id: 1
[{id: 1, title: 缓存接口数据, is_done: 0, created_at: 1700000000000}]

如果数据库中已经存在其他记录,自增主键不一定是 1,因此实际 ID 可能不同。查询条件使用 ? 和 whereArgs 传参,而不是把数据直接拼进 SQL 字符串,可以避免引号转义错误并降低 SQL 注入风险。

使用 Batch 批量写入

连续调用很多次 insert 虽然能工作,但大量独立数据库操作会增加 Dart 与原生数据库之间的调用开销。sqflite 提供 Batch,可以先收集多条操作,再统一提交。

dart
Future<void> insertTasksInBatch() async {
  final db = await AppDatabase.instance.database;

  final tasks = [
    Task(
      title: '保存用户资料',
      isDone: false,
      createdAt: DateTime.fromMillisecondsSinceEpoch(1700000001000),
    ),
    Task(
      title: '保存文章列表',
      isDone: true,
      createdAt: DateTime.fromMillisecondsSinceEpoch(1700000002000),
    ),
    Task(
      title: '保存同步时间',
      isDone: false,
      createdAt: DateTime.fromMillisecondsSinceEpoch(1700000003000),
    ),
  ];

  await db.transaction((txn) async {
    final batch = txn.batch();

    for (final task in tasks) {
      batch.insert('tasks', task.toMap());
    }

    await batch.commit(noResult: true);
  });

  final rows = await db.query(
    'tasks',
    orderBy: 'created_at ASC',
  );
  print(rows);
}

预期输出

text
[{id: <ID>, title: 保存用户资料, is_done: 0, created_at: 1700000001000}, {id: <ID>, title: 保存文章列表, is_done: 1, created_at: 1700000002000}, {id: <ID>, title: 保存同步时间, is_done: 0, created_at: 1700000003000}]

<ID> 表示数据库运行时生成的主键,实际值取决于表中已有记录。示例把批处理放进 transaction,这样批次中的操作属于同一个事务:正常完成时统一提交,回调抛出异常时事务会回滚,从而避免只写入一部分业务数据。

什么时候使用单条插入或批处理

用户新建一条笔记、保存一条设置记录时,直接调用 insert 更简单,还能立即拿到新主键。同步接口列表、导入缓存或一次保存几十到几百条记录时,则更适合使用 Batch。

当批量写入的数据需要“全部成功或全部失败”时,应明确放入事务中;如果每条记录本来就允许独立成功或失败,则不应为了追求批量形式强行绑定为一个事务。模型转换、事务边界和写入策略分开设计后,本地数据库层会更容易测试,也更容易继续扩展查询、更新和删除操作。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

插入和批量写入数据

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通