Spring Data Neo4j默认查询关系映射错误致Contacts字段为空求助

我正在开发基于Spring Boot + Neo4j的应用，UserEntity与UserContactEntity通过PERSON_HAS_CONTACT关系关联。调用带depth=2的默认查询findByUserIdIn获取UserEntity时，其contacts字段始终为空。

相关代码 #

UserEntity.kt #

import org.neo4j.ogm.annotation.*
import org.springframework.data.neo4j.annotation.Depth
import org.springframework.data.neo4j.annotation.Query
import org.springframework.data.neo4j.repository.Neo4jRepository
import org.springframework.data.repository.query.Param
...
@NodeEntity("User")
class UserEntity : PermissionableEntity, Serializable {
    @Id
    @Property("userId")
    var userId: StringID? = null

    @Relationship("PERSON_HAS_CONTACT")
    var contacts: MutableSet<UserContactEntity> = mutableSetOf()

    // 其他字段和方法...
}

UserContactEntity.kt #

import org.neo4j.ogm.annotation.Id
import org.neo4j.ogm.annotation.NodeEntity
import org.neo4j.ogm.annotation.Property
import org.springframework.data.neo4j.annotation.Query
import org.springframework.data.neo4j.repository.Neo4jRepository
import org.springframework.data.repository.query.Param
...
@NodeEntity("UserContact")
class UserContactEntity : Serializable {
    // 字段和方法...
}

UserRepository.kt #

interface UserRepository : Neo4jRepository<UserEntity, StringID> {

    fun findByUserIdIn(userIds: Collection<StringID>, @Depth depth: Int = 2): Iterable<UserEntity>
    
}

排查情况 #

1. 数据关联验证：通过Neo4j浏览器执行查询，确认关联数据存在且正确：

MATCH (u:User)-[r:PERSON_HAS_CONTACT]->(c:UserContact)
RETURN u.userId AS userId, c.id AS contactId, c.type AS contactType, c.detail AS contactDetail, c.verified AS contactVerified

2. 自动查询异常日志：日志显示自动生成的查询存在两个问题：
   • 用CONTACTS替代了定义的PERSON_HAS_CONTACT关系
   • 包含未定义的MEMBER_FIELDS关系

[.0-8080-exec-10] o.s.d.n.r.query.PartTreeNeo4jQuery       : Executing query for method findByUserIdIn
[.0-8080-exec-10] o.n.o.drivers.bolt.request.BoltRequest   : Request: MATCH (n:`User`) WHERE n.`userId` IN $`userId_0` WITH n RETURN n,[ [ (n)-[r_m1:`MEMBER_FIELDS`]-(f1:`FieldValue`) | [ r_m1, f1, [ [ (f1)-[r_d2:`DEFINITION`]-(f2:`FieldDefinition`) | [ r_d2, f2 ] ] ] ] ], [ (n)-[r_c1:`CONTACTS`]-(u1:`UserContact`) | [ r_c1, u1 ] ] ], ID(n) with params {userId_0=[b3c98b44f2e005250b23a4b02938e9f6, fd587ab3096750e10e5c9a0de61c12bb]}

3. 数据库实际关系：查询数据库确认不存在CONTACTS和MEMBER_FIELDS关系：

MATCH (u:User)-[r]->(n)
RETURN type(r) AS relationshipType, count(r) AS count, labels(n) AS targetLabels
ORDER BY count DESC

返回结果：

relationshipType         count  targetLabels
"USER_HAS_ROLES"            11  ["SystemRole"]
"USER_HAS_CREDENTIALS"      5   ["Credentials"]
"PERSON_HAS_CONTACT"        5   ["UserContact"]
"MARKER_HAS_CREDIBILITY"    1   ["ActiveCompetition"]

4. 临时解决方案：自定义查询可正常获取关联数据：

@Query("MATCH (u:User)-[:PERSON_HAS_CONTACT]->(c:UserContact)WHERE u.userId IN $userIds WITH u, collect(c) AS contacts RETURN u, [ [ (u)-[r:`PERSON_HAS_CONTACT`]->(c) | [ r, c ] ] ], ID(u)")
fun findByUserIdInWithContacts(@Param("userIds") userIds: Collection<StringID>): Iterable<UserEntity>

5. 其他排查动作：
   • 查阅Spring Data Neo4j官方文档
   • 清理本地Maven仓库及Gradle构建缓存，排除旧代码影响
   • 同类Organisation实体可正常使用默认查询加载关系，仅UserEntity出现问题

疑问 #

1. Spring Data Neo4j或Neo4j是否存在相关已知问题？
2. 是否有其他关系定义方式干扰了当前代码？
3. 应用其他位置的Bug是否可能导致此问题？

版本信息 #

• Neo4j 4.1.1 enterprise
• Spring Boot 2.3.8.RELEASE
• Spring Data Neo4j 5.3.6.RELEASE
• Java 11

1. 已知问题排查 #

Spring Data Neo4j 5.3.x（对应你使用的版本）在处理继承关系时，存在实体元数据扫描异常的情况。你的UserEntity继承了PermissionableEntity，如果父类或其父类的关联关系定义存在冲突（比如父类中也有命名为contacts的字段、未显式指定关系名，或通过注解配置了默认关系名），会导致子类的@Relationship注解被覆盖。

另外，Neo4j OGM在处理集合类型关联时，默认会将字段名（如contacts）转换为大写作为关系名，若父类存在未显式指定关系名的同名字段，会直接覆盖子类的自定义关系配置。

2. 潜在干扰因素 #

• 继承关系的元数据污染：检查PermissionableEntity及其父类，确认是否存在：
  • 命名为contacts的字段，未通过@Relationship显式指定关系名
  • 使用@RelationshipEntity定义了冲突的关系类型
  • 类上的全局配置（如@Neo4jMappingContext相关配置）影响了子类的关系映射
• 重复实体扫描：若应用中存在多个@Configuration类配置了Neo4j实体扫描路径，可能导致元数据重复加载，出现注解覆盖问题
• 字段命名与默认规则冲突：Spring Data Neo4j默认将字段名转为大写作为关系名，若父类存在同名字段且未指定关系名，会覆盖子类的@Relationship("PERSON_HAS_CONTACT")配置

3. 其他位置的Bug可能性 #

• 元数据缓存问题：即使清理了构建缓存，Spring Data Neo4j的元数据缓存可能未完全失效。可添加JVM启动参数-Dspring.data.neo4j.mapping-context.cache.enabled=false禁用元数据缓存，验证是否解决问题
• 序列化异常：检查UserContactEntity的Serializable实现，若存在未正确序列化的字段，可能导致Neo4j OGM无法正确映射关联对象
• 事务上下文缺失：如果查询未在事务内执行，Neo4j OGM可能无法正确加载关联数据。尝试在调用findByUserIdIn的方法上添加@Transactional注解测试

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