使用Neo4j OGM集群时出现‘Error mapping GraphModel’错误求助

集群架构 #

采用1台LEADER、2台FOLLOWERS的Neo4j服务器集群架构，节点结构如下：

保存薪资支付记录方法 #

@Override
@UseBookmark
@Transactional(rollbackFor = Exception.class, propagation = Propagation.REQUIRED)
public void addEmploymentPayout(EmploymentPayoutDTO payoutDto, String employmentId) {
    try {
        // Map
        var payout = dozerMapper.map(payoutDto, EmploymentPayout.class);

        // Save
        var employment = profileService.findEmploymentByUuid(employmentId);

        var container = employmentPayoutContainerRepository.getContainerIfExist(employmentId)
                                                           .orElse(new EmploymentPayoutContainer());
        container.setEmployment(employment);

        var payouts = Optional.ofNullable(container.getEmploymentPayouts())
                              .orElse(new ArrayList<>());
        payouts.add(payout);
        container.setEmploymentPayouts(payouts);
        employmentPayoutContainerRepository.save(container);

        // employmentPayout.setEmploymentPayoutContainer(container);
        // employmentPayoutRepository.save(payout);
        // employmentPayoutRepository.save(employmentPayout, 2);
    } catch (Exception e) {
        LOG.error(ExceptionUtils.getStackTrace(e));
    }
}

查询方法getAllPureEmploymentsByProfileId #

@Query("MATCH (p:Profile) WHERE p.uuid=$profileId "
    + "MATCH (p)-[:HAS_PROFILE_EMPLOYMENT_CONTAINER]->(pec:ProfileEmploymentContainer) "
    + "MATCH path = (pec)-[:USES_PROFILE_EMPLOYMENT]-(pe:ProfileEmployment) RETURN pec, path")
ProfileEmploymentContainer getAllPureEmploymentsByProfileId( @Param("profileId") String profileId);

问题详情 #

调用addEmploymentPayout新增EmploymentPayout记录后，立即执行getAllPureEmploymentsByProfileId加载路径数据时，出现图模型映射错误，但重启服务器后错误消失。已尝试添加@UseBookmark和事务注解，问题仍未解决；单机Neo4j服务器环境下无此问题。

错误栈 #

org.springframework.dao.InvalidDataAccessApiUsageException: Error mapping GraphModel; nested exception is org.neo4j.ogm.exception.core.MappingException: Error mapping GraphModel
    at org.springframework.data.neo4j.transaction.SessionFactoryUtils.convertOgmAccessException(SessionFactoryUtils.java:125)
    ...（省略中间栈信息）
Caused by: java.lang.NullPointerException
    at org.neo4j.ogm.session.Utils.coerceTypes(Utils.java:79)
    ...（省略末尾栈信息）

问题原因分析 #

1. 集群数据同步延迟：Neo4j集群中Leader写入数据后，需要同步到Followers，若查询请求被路由到尚未完成同步的Follower节点，会读取到不完整的图数据（比如新增的EmploymentPayout关联关系未同步），导致OGM映射时出现空指针。单机环境下无同步延迟，所以不会触发该问题。
2. OGM会话缓存与集群一致性冲突：Spring Data Neo4j的OGM会话可能缓存了旧的节点/关系数据，即使集群数据已同步，会话仍使用缓存数据进行映射，导致数据不一致。重启服务器会清空会话缓存，所以错误消失。
3. @UseBookmark使用不彻底：虽然写入方法添加了@UseBookmark，但查询方法未标注该注解，无法保证查询使用与写入相同的书签（即读取已提交的最新数据），导致查询可能访问到未同步的节点。
4. 事务边界问题：写入方法的事务提交后，集群同步需要时间，若查询立即执行，此时Follower节点的数据还未更新，读取到的ProfileEmploymentContainer可能缺少新增的EmploymentPayout关联，OGM映射时处理空关联数据触发空指针。

解决方案建议 #

• 给查询方法getAllPureEmploymentsByProfileId也添加@UseBookmark注解，强制查询使用写入事务的书签，保证读取Leader节点的最新数据。
• 配置Neo4j驱动的读策略为READ_COMMITTED，或强制路由到Leader节点进行查询（适用于写入后立即查询的场景）。
• 检查OGM实体映射配置，确保关联关系的映射逻辑处理了空值情况，避免空指针。

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