Flutter Hive新增字段致应用崩溃，如何保障向后兼容？

核心思路 #

Hive的TypeAdapter通过版本号区分不同的数据结构版本，当模型新增字段时，只需升级Adapter版本，并在读取逻辑中针对旧版本数据做兼容处理——给新增字段设置合理的默认值，就能避免应用崩溃。

具体实现步骤 #

1. 升级TypeAdapter的版本号 #

修改你的UserModelAdapter，将version参数从原来的默认值（通常是0）递增为1（每次数据结构变更都要加1）：

class UserModelAdapter extends TypeAdapter<UserModel> {
  @override
  final int typeId = 0; // 这个值是模型的唯一标识，上线后绝对不能修改
  @override
  final int version = 1; // 升级版本号，标记数据结构变更
  // ... 其他方法
}

2. 在read方法中兼容旧版本数据 #

在read方法里先读取版本号，根据版本判断是否需要读取新增字段；如果是旧版本数据（版本号小于1），直接给favourite字段设置默认值（比如空列表）：

@override
UserModel read(BinaryReader reader) {
  final dataVersion = reader.readByte(); // 先读取数据的版本号
  final id = reader.readString();
  final name = reader.readString();

  List<String> favourite = [];
  // 只有版本>=1时，才读取新增的favourite字段
  if (dataVersion >= 1) {
    favourite = reader.readList().cast<String>();
  }

  return UserModel(
    id: id,
    name: name,
    favourite: favourite, // 旧数据也能拿到合法的默认值
  );
}

3. 保持write方法的正确性 #

write方法按照新版本结构写入所有字段即可，新版本的写入逻辑不影响旧版本数据的读取：

@override
void write(BinaryWriter writer, UserModel obj) {
  writer.writeByte(version); // 先写入当前版本号
  writer.writeString(obj.id);
  writer.writeString(obj.name);
  writer.writeList(obj.favourite);
}

4. 自动生成Adapter的兼容方式（若使用hive_generator） #

如果你用hive_generator自动生成Adapter，无需手动修改read/write方法，只需给新增字段添加defaultValue参数：

@HiveType(typeId: 0)
class UserModel extends HiveObject {
  @HiveField(0)
  String id;

  @HiveField(1)
  String name;

  @HiveField(2, defaultValue: []) // 给新增字段设置默认值
  List<String> favourite;

  UserModel({required this.id, required this.name, this.favourite = const []});
}

重新生成Adapter后，工具会自动处理版本升级和默认值填充逻辑。

关键注意事项 #

• 绝对不能修改typeId：这个值是Hive识别不同模型的唯一标识，上线后修改会导致所有旧数据无法读取。
• 版本号只能递增：每次模型变更都要把version加1，不能回退版本。
• 默认值要符合业务逻辑：比如列表用空列表、布尔值用false、数值用0，确保旧数据能正常映射到新模型。

内容的提问来源于stack exchange，提问作者Febin Johnson