实体主键从long改为UUID后Javers抛出UUID反序列化异常如何解决？

问题触发场景 #

开发中将实体主键类型从long调整为uuid后，执行对象修改操作时Javers直接抛出运行异常，堆栈信息如下：

java.lang.IllegalArgumentException: Invalid UUID string: 7
    at java.base/java.util.UUID.fromString(UUID.java:215)
    at org.javers.core.json.typeadapter.util.UUIDTypeAdapter.deserialize(UUIDTypeAdapter.java:19)
    at org.javers.core.json.typeadapter.util.UUIDTypeAdapter.deserialize(UUIDTypeAdapter.java:10)
    at org.javers.core.json.BasicStringTypeAdapter.fromJson(BasicStringTypeAdapter.java:45)
    at ........
    at org.javers.spring.jpa.JaversTransactionalJpaDecorator.commit(JaversTransactionalJpaDecorator.java:50)

经定位，异常触发原因是Javers尝试将历史快照中存储的旧long类型主键值反序列化为UUID类型时，旧数字值不符合UUID字符串格式要求导致解析失败，目前无官方针对该类主键类型变更场景的推荐处理方案，可落地的解决思路分为三类：

可选解决思路 #

• 历史快照全量迁移
  先定位Javers持久化快照的所有关联表（核心表一般为jv_snapshot、jv_commit、jv_global_id），提前约定旧long主键到新UUID的固定映射规则（推荐使用UUID v5，基于固定命名空间+旧long值生成，保证同一旧主键始终映射到同一UUID），批量更新所有历史快照中存储的旧主键值为映射后的合法UUID，校验数据无误后再上线主键类型为UUID的业务代码，从根源避免类型不匹配问题。
• 自定义类型适配器兼容旧格式
  替换Javers默认的UUIDTypeAdapter，自定义反序列化逻辑：解析时先判断入参字符串格式，如果是纯数字的旧long类型主键，按照预先约定的映射规则转换为对应UUID再返回；如果是标准UUID格式则直接走原生解析逻辑。该方案不需要提前改动历史数据，上线成本更低，注意必须保证适配器内的映射规则和后续数据迁移规则完全一致，避免新旧数据主键映射错乱。
• 实体类型隔离
  如果不需要关联查询主键类型变更前的历史审计记录，可以给调整后的实体加@TypeName注解，指定和旧实体完全不同的类型标识，Javers会将其识别为全新的实体类型，不会读取旧类型的历史快照做反序列化，从读取层面隔离新旧数据，不会触发解析异常。该方案缺点是新旧实体的变更历史完全割裂，无法查询单条业务数据的全量变更链路。

风险提示：选择历史数据迁移方案前，必须全量备份Javers相关业务表，先在测试环境验证全量数据转换的正确性，避免操作失误导致历史审计数据丢失。

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