Spring Data Neo4j Client无数据库匹配时抛异常的解决咨询

使用Neo4jClient进行查询时，源节点与目标节点标签相同，查询在有匹配结果时运行正常，但当无匹配返回空结果时，会抛出NULL is not iterable异常。

原始查询代码 #

@Repository
public class Neo4jClientRepository {
    @Autowired
    private Neo4jMappingContext neo4jMappingContext;

    @Autowired
    private Neo4jClient neo4jClient;

    public Collection<NodePair> findNodesByUniqueIds(List<String> srcUniqueIds, String nodeName) {
        BiFunction<TypeSystem, MapAccessor, Node> mappingFunction = neo4jMappingContext.getRequiredMappingFunctionFor(Node.class);

        return neo4jClient.query(
                        """
                                MATCH (src:Node)
                                WHERE src.uniqueId IN $uniqueIds
                                OPTIONAL MATCH (src:Node)-[*1..2]-(target:Node)
                                WHERE toUpper(target.name) = toUpper($name)
                                RETURN {src: src, target: target} AS nodePair
                                """
                )
                .bind(srcUniqueIds).to("uniqueIds")
                .bind(nodeName).to("name")
                .fetchAs(NodePair.class)
                .mappedBy((typeSystem, record) -> {
                        MapValue nodePair = (MapValue) record.get("nodePair");
                        var src = mappingFunction.apply(typeSystem, nodePair.get("src"));
                        var target = mappingFunction.apply(typeSystem, nodePair.get("target"));
                    return new NodePair(src, target);
                })
                .all();
    }
}

抛出异常 #

org.springframework.dao.InvalidDataAccessApiUsageException: NULL is not iterable; Error code 'N/A'
    at org.springframework.data.neo4j.core.Neo4jPersistenceExceptionTranslator.translateImpl(Neo4jPersistenceExceptionTranslator.java:107)
    at org.springframework.data.neo4j.core.Neo4jPersistenceExceptionTranslator.translateExceptionIfPossible(Neo4jPersistenceExceptionTranslator.java:81)
    at org.springframework.data.neo4j.core.DefaultNeo4jClient.potentiallyConvertRuntimeException(DefaultNeo4jClient.java:230)
    at org.springframework.data.neo4j.core.DefaultNeo4jClient$DefaultRecordFetchSpec.all(DefaultNeo4jClient.java:488)

疑问 #

如何在结果映射到实体类前进行空值检查，或如何避免此类情况？

1. 在Cypher查询层面过滤或处理空值 #

问题核心是OPTIONAL MATCH无匹配时会返回target: null，后续映射时触发空迭代异常。可以通过Cypher语句提前处理：

过滤空target结果 #

如果业务上只需要有有效目标节点的结果，添加WHERE target IS NOT NULL过滤：

MATCH (src:Node)
WHERE src.uniqueId IN $uniqueIds
OPTIONAL MATCH (src:Node)-[*1..2]-(target:Node)
WHERE toUpper(target.name) = toUpper($name)
WITH src, target WHERE target IS NOT NULL
RETURN {src: src, target: target} AS nodePair

为target设置默认值 #

如果需要保留源节点（即使无匹配目标），用COALESCE给target设置空节点结构，避免映射时处理null：

MATCH (src:Node)
WHERE src.uniqueId IN $uniqueIds
OPTIONAL MATCH (src:Node)-[*1..2]-(target:Node)
WHERE toUpper(target.name) = toUpper($name)
RETURN {src: src, target: COALESCE(target, {uniqueId: null, name: null})} AS nodePair

2. 在映射逻辑中添加空值检查 #

在mappedBy转换函数里，先判断target是否为null，再执行映射：

.mappedBy((typeSystem, record) -> {
        MapValue nodePair = (MapValue) record.get("nodePair");
        var src = mappingFunction.apply(typeSystem, nodePair.get("src"));
        // 检查target是否为null，避免映射空值触发异常
        Node target = null;
        if (!nodePair.get("target").isNull()) {
            target = mappingFunction.apply(typeSystem, nodePair.get("target"));
        }
        return new NodePair(src, target);
    })

3. 改用Stream处理空结果集 #

如果all()方法在空结果集时触发异常，改用stream()收集结果，空流会被正确转换为空集合：

return neo4jClient.query(
                        // 原Cypher语句
                )
                .bind(srcUniqueIds).to("uniqueIds")
                .bind(nodeName).to("name")
                .fetchAs(NodePair.class)
                .mappedBy(/* 原映射逻辑 */)
                .stream()
                .collect(Collectors.toList());

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