使用Neo4j Spring Data添加@Version后出现乐观锁异常如何解决？

我近期开始使用Neo4j与Spring-Data，实现了如下基础节点：

@Node
data class Entity(
   @Id var identifier: UUID
)

日志中出现如下警告：

2024-07-30T17:10:18.036+02:00  WARN 7520 --- [           main] o.s.d.n.c.m.DefaultNeo4jIsNewStrategy    : Instances of class Entity with an assigned id will always be treated as new without version property

尝试为类添加版本属性，代码如下：

@Node
data class Entity(
   @Id var identifier: UUID,
   @Version var version: Long? = null
)

但此时代码崩溃，抛出异常：

org.springframework.dao.OptimisticLockingFailureException: An entity with the required version does not exist.

请问遗漏了什么？

原因分析 #

1. 当使用**手动分配的ID（如UUID）**搭配@Version时，Spring Data Neo4j的乐观锁机制会要求实体必须携带有效的版本信息。
2. 若数据库中存在未添加version属性的旧数据，查询或更新时框架找不到对应版本值，就会抛出该异常。
3. 原警告的核心是：无version时，手动分配ID的实体每次都会被当作新实体执行CREATE操作；添加version是为了让框架区分实体的新旧状态，但旧数据缺失version字段是触发崩溃的直接原因。

解决步骤 #

1. 补全已有数据的version字段 #

针对数据库中已存在的Entity节点，执行Cypher语句批量添加默认version值：

MATCH (e:Entity) WHERE NOT EXISTS(e.version) SET e.version = 0

2. 调整实体类的version定义 #

将version设为非空并赋予默认值，避免手动初始化导致的版本不匹配：

@Node
data class Entity(
   @Id var identifier: UUID,
   @Version var version: Long = 0 // 固定默认值0，框架会自动递增
)

3. 规范Repository操作逻辑 #

• 新增实体：直接调用save()，框架会自动处理version的初始化与存储。
• 更新实体：必须先通过Repository查询出已存在的实体（此时会加载数据库中的version值），修改属性后再调用save()，框架会自动对比版本并完成更新。禁止手动创建带已有ID的Entity实例直接执行save操作，否则会因版本不匹配触发异常。

内容的提问来源于stack exchange，提问作者Yonatan Karp-Rudin