Spring Data Neo4j中如何将领域对象作为自定义Cypher查询参数

我正在开发Spring Data Neo4j Web应用，定义了如下领域对象：

@Node("Person")
public class Person {
    
    @Id
    @GeneratedValue
    private String id;
}

同时存在(:Image) - [:DEPICTS] -> (:Person)关系。我需要统计描绘特定Person的Image数量，尝试了多种自定义Cypher查询方式均返回0：

public interface ImageRepositoryNeo4j extends Neo4jRepository<Image, String> {
@Query("""
        MATCH (i:Image) -[:DEPICTS] -> (p:Person)
        WHERE p = $person
        RETURN count(i)
        """)
    // 无效，返回0
    public Integer countByPeopleContains(@Param("person") Person person);
}

其他失败尝试包括传入Person集合、通过ID匹配等，均返回0。仅通过fullName匹配的方式有效，但fullName不具备唯一性，不符合业务逻辑：

@Query("""
        MATCH (i:Image) -[:DEPICTS] -> (p:Person {fullName: $person})
        RETURN count(i)
        """)
    // TODO：fullName不唯一，需替换
    public Integer countByPeopleContains(@Param("person") String personFullName);

怀疑与@GeneratedValue生成的ID有关，如何在Spring Data Neo4j Repository的自定义Cypher查询中正确使用领域对象作为参数？

核心原因 #

Spring Data Neo4j（SDN）中直接用领域对象实例匹配节点时，默认会尝试用内部跟踪的节点标识符（并非你定义的@Id字段）匹配，而@GeneratedValue生成的id是业务层面属性，和Neo4j内部节点ID不是同一回事，这就导致匹配失败。

正确实现方式 #

方式1：通过领域对象的@Id属性匹配

直接在Cypher中引用传入对象的id属性，这是最直接的方案：

public interface ImageRepositoryNeo4j extends Neo4jRepository<Image, String> {
    @Query("""
            MATCH (i:Image)-[:DEPICTS]->(p:Person)
            WHERE p.id = $person.id
            RETURN count(i)
            """)
    Integer countByDepictedPerson(@Param("person") Person person);
}

方式2：使用SDN节点绑定语法

SDN支持用$person直接匹配节点，但需确保传入的Person是从SDN仓库加载的托管实例（不是自行new的对象），同时显式指定用内部ID匹配：

public interface ImageRepositoryNeo4j extends Neo4jRepository<Image, String> {
    @Query("""
            MATCH (i:Image)-[:DEPICTS]->(p:Person)
            WHERE id(p) = id($person)
            RETURN count(i)
            """)
    Integer countByDepictedPerson(@Param("person") Person person);
}

这里的id(p)是Neo4j内置函数，用于获取节点内部ID，SDN会自动将托管的Person实例映射到对应内部ID。

方式3：直接传入ID参数

如果场景允许，也可以直接传入Person的id属性值，避免对象传递的问题：

public interface ImageRepositoryNeo4j extends Neo4jRepository<Image, String> {
    @Query("""
            MATCH (i:Image)-[:DEPICTS]->(p:Person {id: $personId})
            RETURN count(i)
            """)
    Integer countByDepictedPersonId(@Param("personId") String personId);
}

注意事项 #

• 若使用自行new的Person对象（非托管实例），SDN无法识别其对应Neo4j节点，此时必须通过id属性值匹配，不能用id($person)语法。
• 确保Person类的@Id字段被SDN正确映射，@GeneratedValue默认生成UUID格式字符串ID，会存储在Neo4j节点的id属性中。

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