Spring Data Neo4j接口投影抛出NoRootNodeMappingException如何解决

错误原因 #

• Spring Data Neo4j 6+ 版本的默认接口投影属于实体派生投影，要求查询结果中必须包含完整的根节点（即预先定义的域模型节点实体）作为映射载体，你当前仅返回了name、count两个零散属性，框架无法找到可匹配的根节点实体，因此抛出NoRootNodeMappingException异常。
• 现有Cypher语句存在语法不规范问题：MATCH (User {mobile:$mobile})没有为节点指定标签前缀冒号，实际语义是将节点别名设为User，而非匹配标签为User的节点，可能导致查询结果不符合预期。

解决方法 #

方法一（推荐，兼容性最高）：改用值类DTO投影 #

放弃接口投影，改用普通Java类作为返回载体，框架会自动按返回字段名和构造参数名匹配映射，无需根节点实体：

// 定义普通DTO类，提供全参数构造方法和对应getter
public class StepList {
    private final String name;
    private final int count;

    public StepList(String name, int count) {
        this.name = name;
        this.count = count;
    }

    public String getName() {
        return name;
    }

    public int getCount() {
        return count;
    }
}

Repository层的查询方法无需修改其他逻辑，保持现有Query语句即可正常运行。

方法二：保留接口投影，添加查询属性适配 #

如果需要继续使用接口投影，可在@Query注解上添加readOnly = true属性，告知框架该查询为只读聚合查询，不需要根节点映射，同时修正Cypher语句的标签语法：

@Query(value = "MATCH (:User {mobile:$mobile})-[:CONTACT]-(n:User)-[:STEPTAKER]-(s:Step) RETURN n.name AS name, s.count AS count", readOnly = true)
public List<StepList> findAllStepByMobile(String mobile);

interface StepList{
    String getName();
    int getCount();
}

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