在Neo4j保存实体时触发NoSuchRecordException：本地正常远程报错

核心原因 #

Spring Data Neo4j（SDN）的save方法底层会先执行查询操作（根据实体的@Id字段匹配节点），判断是执行创建还是更新。报错提示"期望单条记录但返回多条"，说明查询阶段返回了多个匹配节点，或者SDN版本与Neo4j 4.2.5不兼容导致查询逻辑异常。

排查步骤与解决方案 #

1. 检查远程数据库的重复数据 #

远程Neo4j 4.2.5中可能存在多个Profile节点共享同一个hash值，导致查询时返回多条记录：

• 登录远程Neo4j控制台，执行Cypher查询：

  MATCH (p:Profile {hash: '你的实体hash值'}) RETURN count(p), p
  

• 如果返回数量>1，清理重复数据：保留一条有效节点，删除其余重复项。

2. 验证Spring Data Neo4j与Neo4j版本兼容性 #

SDN版本和Neo4j服务器版本必须严格匹配：

• Neo4j 4.2.5对应的SDN版本是6.x（搭配Spring Boot 2.7.x）；如果本地用的是适配Neo4j 5.x的SDN 7.x（Spring Boot 3.x），部署到4.2.5会出现逻辑冲突。
• 调整项目依赖：
  • Maven示例（降级到Spring Boot 2.7.x）：

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.15</version>
        <relativePath/>
    </parent>
    
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-neo4j</artifactId>
    </dependency>
    

3. 检查实体主键与父类定义 #

• 确保hash字段在业务逻辑中是全局唯一的，不会出现重复生成的情况。
• 检查父类Profile是否包含其他@Id、@Indexed注解字段，导致SDN生成的查询条件包含额外字段，意外匹配到多条节点。如果父类有无关索引，可移除或调整索引策略。

4. 调试SDN生成的Cypher语句 #

开启SDN的Cypher日志，查看save时实际执行的查询语句：

• 在application.yml中添加日志配置：

  logging:
    level:
      org.springframework.data.neo4j: DEBUG
      org.neo4j.driver: DEBUG
  

• 对比本地与远程执行的Cypher语句，确认是否因为版本差异导致查询逻辑不同，进而返回多条记录。

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