Flutter Hive模型字段修改：无需清除旧数据的解决方法

1. 规范使用字段索引与默认值 #

• 给每个模型字段指定唯一的index值，新增字段时用从未用过的新索引，不要修改已有字段的index。比如原来的name是@HiveField(0)，新增age就用@HiveField(1)。
• 给新增字段设置defaultValue，旧数据读取时会自动填充默认值，避免空值报错。示例：

@HiveType(typeId: 1)
class User extends HiveObject {
  @HiveField(0)
  String name;

  // 新增字段，设置默认值
  @HiveField(1, defaultValue: 18)
  int age;

  User(this.name, this.age);
}

2. 字段变更（重命名/类型修改）时使用迁移 #

如果需要修改已有字段的名称或类型，不能直接改字段名，要通过Hive的迁移机制处理旧数据：

• 打开Box时指定migration参数，在迁移函数里完成旧数据到新模型的转换。示例：

final box = await Hive.openBox<User>('users',
  migration: {
    // 旧版本号: 对应的迁移处理函数
    1: (oldBox, newBox) async {
      // 遍历旧数据，转换后存入新Box
      for (var key in oldBox.keys) {
        var oldData = oldBox.get(key);
        // 根据实际场景转换，比如旧模型无age字段则填充默认值
        newBox.put(key, User(oldData.name, 18));
      }
    },
  },
);

• 可以配合模型的typeId做版本区分，比如修改模型后把typeId从1改成2，再在迁移逻辑里对应处理不同版本的数据。

3. 避免直接删除旧字段 #

如果不再需要某个字段，不要直接删除对应的@HiveField，可以标记为废弃（比如加@deprecated）并保留索引，这样读取旧数据时不会因为找不到字段报错。等确认所有用户都更新到新版本后，再考虑清理废弃字段。

4. 测试迁移逻辑 #

修改模型和迁移代码后，一定要用旧版本的真实数据测试，确保迁移能正常完成，不会出现数据丢失或报错的情况。

内容的提问来源于stack exchange，提问作者Abhay Rawat