如何在Spring Data Neo4j中正确转义全文索引查询参数？

先修正countQuery语法错误 #

你的countQuery存在语法问题，正确写法应该是：

countQuery = "CALL db.index.fulltext.queryNodes('mimir_NorseDeity_label_fulltext', $label) YIELD node RETURN COUNT(node)"

原写法里的YIELD node AS COUNT(n)不符合Cypher语法，会导致分页计数逻辑失效。

无需冗余代码的参数转义方案 #

方案1：自定义参数转换器 #

Spring Data支持自定义参数转换器，能自动对Repository方法的参数做转换，无需修改接口方法签名：

1. 编写Lucene特殊字符转义工具类：

public class LuceneQueryEscaper {
    private static final Pattern SPECIAL_CHARS = Pattern.compile("([\\+\\-\\!\\(\\)\\:\\^\\]\\{\\}\\~\\*\\?])");

    public static String escape(String input) {
        if (input == null) {
            return "";
        }
        return SPECIAL_CHARS.matcher(input).replaceAll("\\\\$1");
    }
}

2. 实现Spring Data的Converter<String, String>并注册转义逻辑：

@Component
public class LuceneQueryConverter implements Converter<String, String> {
    @Override
    public String convert(String source) {
        return LuceneQueryEscaper.escape(source);
    }
}

3. 在Repository方法参数上标注@Convert指定转换器：

@Query(
    value = "CALL db.index.fulltext.queryNodes('mimir_NorseDeity_label_fulltext', $label) YIELD node AS n RETURN n SKIP $skip LIMIT $limit",
    countQuery = "CALL db.index.fulltext.queryNodes('mimir_NorseDeity_label_fulltext', $label) YIELD node RETURN COUNT(node)"
)
Page<NorseDeity> fulltextFindByLabel(@Param("label") @Convert(converter = LuceneQueryConverter.class) String label, Pageable page);

调用该方法时，Spring Data会自动对label参数执行转义，Repository接口不会产生冗余代码。

方案2：使用SpEL表达式直接调用转义方法 #

如果不想编写转换器类，也可以在@Query中用SpEL表达式直接调用工具类的转义方法，保持Repository接口简洁：

1. 确保已准备好上述LuceneQueryEscaper工具类（静态方法直接可用）。

2. 修改@Query注解，用SpEL处理参数：

@Query(
    value = "CALL db.index.fulltext.queryNodes('mimir_NorseDeity_label_fulltext', #{T(com.yourpackage.LuceneQueryEscaper).escape(#label)}) YIELD node AS n RETURN n SKIP $skip LIMIT $limit",
    countQuery = "CALL db.index.fulltext.queryNodes('mimir_NorseDeity_label_fulltext', #{T(com.yourpackage.LuceneQueryEscaper).escape(#label)}) YIELD node RETURN COUNT(node)"
)
Page<NorseDeity> fulltextFindByLabel(@Param("label") String label, Pageable page);

这里T()是SpEL的类型运算符，用来调用静态方法，直接在查询语句中完成转义，无需修改Repository方法的参数定义。

方案对比 #

• 转换器方案适合多个Repository方法需要转义的场景，一次定义即可多处复用。
• SpEL方案更轻量，适合单个方法的转义需求，无需额外创建转换器类。

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