如何用Spring Starter JPA优雅更新字段类型变更后的历史数据？

问题场景 #

原有Data实体类将Double输入转换为String存储：

public class Data implements Serializable {
    private static final long serialVersionUID = 1L;
    private final String data;

    public Data(Double in) {
        this.data = String.valueOf(in);
    }
}

重构后改为直接存储Double类型，并更新序列化版本号：

public class Data implements Serializable {
    private static final long serialVersionUID = 2L;
    private final Double data;

    public Data(Double in) {
        this.data = in;
    }
}

需要平滑迁移历史数据，避免直接替换导致的序列化异常或数据丢失。

优雅迁移方案 #

步骤1：临时兼容阶段（双字段共存） #

先修改实体类，保留原String字段，新增Double字段，同时添加自动转换逻辑：

public class Data implements Serializable {
    private static final long serialVersionUID = 1L; // 暂保留旧版本号
    private String data; // 旧存储字段
    private Double dataDouble; // 新存储字段

    // 保留旧构造方法，兼容历史数据反序列化
    public Data(Double in) {
        this.data = String.valueOf(in);
        this.dataDouble = in;
    }

    // JPA加载数据时自动完成类型转换
    @PostLoad
    private void convertLegacyData() {
        if (dataDouble == null && data != null) {
            try {
                this.dataDouble = Double.valueOf(data);
            } catch (NumberFormatException e) {
                // 处理格式异常数据，比如设为默认值或标记为脏数据
                this.dataDouble = null;
            }
        }
    }

    // 提供getter/setter，确保JPA能正常操作字段
    public String getData() { return data; }
    public void setData(String data) { this.data = data; }
    public Double getDataDouble() { return dataDouble; }
    public void setDataDouble(Double dataDouble) { this.dataDouble = dataDouble; }
}

部署该版本后，应用启动时会自动加载所有历史数据，通过@PostLoad完成String到Double的转换并持久化到数据库。

步骤2：批量主动迁移（可选，针对大数据量） #

如果数据量较大，懒加载转换效率低，可以编写启动时执行的批量迁移逻辑：

@Component
public class DataMigrationRunner implements ApplicationRunner {
    private static final Logger log = LoggerFactory.getLogger(DataMigrationRunner.class);
    private final DataRepository dataRepository;

    public DataMigrationRunner(DataRepository dataRepository) {
        this.dataRepository = dataRepository;
    }

    @Override
    public void run(ApplicationArguments args) throws Exception {
        int pageSize = 1000;
        int page = 0;
        Page<Data> dataPage;
        do {
            dataPage = dataRepository.findAll(PageRequest.of(page, pageSize));
            for (Data data : dataPage) {
                if (data.getDataDouble() == null && data.getData() != null) {
                    try {
                        data.setDataDouble(Double.valueOf(data.getData()));
                        dataRepository.save(data);
                    } catch (NumberFormatException e) {
                        log.error("转换数据失败，ID: {}, 原数据: {}", data.getId(), data.getData(), e);
                    }
                }
            }
            page++;
        } while (dataPage.hasNext());
    }
}

注意：执行前务必全量备份数据库，避免转换错误导致数据丢失。

步骤3：切换到最终实体类 #

确认所有历史数据转换完成后，修改实体类为最终版本，并同步调整数据库表结构：

public class Data implements Serializable {
    private static final long serialVersionUID = 2L;
    private final Double data;

    public Data(Double in) {
        this.data = in;
    }

    public Double getData() { return data; }
}

同时执行数据库表结构修改（以MySQL为例）：

-- 重命名新字段为原字段名
ALTER TABLE data CHANGE COLUMN dataDouble data DOUBLE NULL;
-- 删除旧的String类型字段
ALTER TABLE data DROP COLUMN data;

关键注意事项 #

• 序列化版本号：兼容阶段保留旧版本号，避免反序列化异常；最终版本再更新为2L。
• 脏数据处理：转换过程中必须捕获格式异常，记录日志后手动处理异常数据。
• 分批操作：大数据量场景下必须分页处理，防止内存溢出。
• 备份优先：迁移前一定要全量备份数据库，确保可回滚。

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