spring-data-neo4j v6传非@Node DTO参数报ConverterNotFoundException如何处理

核心结论 #

Spring Data Neo4j 6.x 版本默认不支持直接将非@Node注解的普通DTO作为查询方法参数、在Cypher语句中通过.访问属性。这是因为6.x版本重构了参数转换逻辑，仅内置了基础类型、关联@Node实体、集合/数组等类型到org.neo4j.driver.Value的转换器，没有默认的普通POJO/DTO到Value的转换器，因此会抛出你遇到的ConverterNotFoundException异常。

可行解决方案 #

方案1：自定义参数转换器（最贴近原有用法） #

该方案可以保留你原有直接传DTO、在Cypher中访问字段的写法，仅需要额外加转换器并注册即可。

1. 实现DTO到org.neo4j.driver.Value的转换器：

import org.neo4j.driver.Values
import org.springframework.core.convert.converter.Converter
import org.springframework.data.convert.WritingConverter

@WritingConverter
class MyDtoToValueConverter : Converter<MyDTO, org.neo4j.driver.Value> {
    override fun convert(source: MyDTO): org.neo4j.driver.Value {
        return Values.value(mapOf(
            "field1" to source.field1,
            "field2" to source.field2
        ))
    }
}

2. 将转换器注册到Spring Data Neo4j配置中：

import org.springframework.context.annotation.Configuration
import org.springframework.data.neo4j.config.AbstractNeo4jConfig
import org.springframework.data.neo4j.core.convert.Neo4jConversions

@Configuration
class Neo4jConfig : AbstractNeo4jConfig() {
    // 其他配置如驱动、连接池配置保持不变

    override fun neo4jConversions(): Neo4jConversions {
        return Neo4jConversions(listOf(MyDtoToValueConverter()))
    }
}

配置完成后，你现有使用$0.field1的写法即可正常运行。

方案2：拆分DTO为单个参数（无需修改配置，适合字段少的场景） #

如果DTO字段数量少，可以直接把方法参数替换为DTO的对应字段，Cypher语句直接引用参数即可：

@Repository
interface MyRepository : PagingAndSortingRepository<MyEntity, String> {

    @Query("MATCH (e:MyEntity {attr1: $field1}) " +
           "CREATE (e)-[l:LINK]->(n:OtherEntity {attr2: $field2))")
    fun doSomethingWithDto(field1: String, field2: String)
}
// 调用时从DTO取出字段传入即可

方案3：将DTO转为Map传入 #

Spring Data Neo4j 6.x内置了Map类型到Value的转换器，你可以将DTO转成Map后作为参数传入：

@Repository
interface MyRepository : PagingAndSortingRepository<MyEntity, String> {

    @Query("MATCH (e:MyEntity {attr1: $0.field1}) " +
           "CREATE (e)-[l:LINK]->(n:OtherEntity {attr2: $0.field2))")
    fun doSomethingWithDto(dtoMap: Map<String, Any?>)
}
// 调用时转换DTO为Map即可，可借助Jackson等工具类实现通用转换
val dtoMap = jacksonObjectMapper().convertValue(dto, Map::class.java) as Map<String, Any?>
myRepository.doSomethingWithDto(dtoMap)

原有尝试方案无效原因说明 #

• 给DTO加@Node注解无效：SDN的@Node实体参数转换逻辑仅适用于对应Repository管理的实体类型，你的MyRepository绑定的是MyEntity，不是MyDTO，因此不会触发对应转换逻辑。
• 仅修改{0}为$0无效：该修改仅适配了Neo4j 4.x+的Cypher语法要求，但核心的DTO到Value的转换问题没有解决，因此仍然报错。

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