如何在Spring Data中编写Couchbase N1QL查询并解决子串匹配问题

我来帮你排查并解决这个问题，你的查询失效主要是因为N1QL语法错误、参数绑定方式不正确以及返回类型不匹配，下面一步步修正：

1. 修正@Query中的语法错误 #

你的原查询语句有两个关键问题：

• 通配符与参数的拼接方式错误：'%$1'% 的引号位置完全不对，Couchbase N1QL中需要用字符串连接操作符 || 来拼接通配符和参数
• within #{#n1ql.bucket} 的位置错误：它应该替换掉 FROM 后的硬编码桶名，而不是放在WHERE子句末尾

修正后的@Query语句如下：

@Query("SELECT * FROM #{#n1ql.bucket} WHERE #{#n1ql.filter} AND ANY v IN namelist SATISFIES v LIKE '%' || $1 || '%' END")
List<Car> findByNamelistContains(String name);

2. 修正返回类型 #

你的方法返回 List<String>，但实际查询的是整个文档（对应你的POJO类），所以应该返回POJO的集合（假设你的POJO类名为Car），这样Spring Data Couchbase才能正确映射查询结果。

3. 验证POJO的注解 #

确保你的POJO类上添加了@Document注解，否则Spring Data无法识别它是Couchbase的文档实体：

@Document
public class Car {
    @Id 
    private String car_id;
    
    @Field 
    @NotNull 
    private String name;
    
    @Field 
    private List<String> namelist;
    
    // 构造方法、getter/setter省略
}

为什么原查询失效？ #

• 原语句中的'%$1'%会被解析成无效的字符串字面量，Couchbase无法正确识别参数$1，导致查询无法匹配任何数据
• within #{#n1ql.bucket} 放在WHERE子句后属于语法错误，N1QL会直接拒绝执行这个查询

可选优化：使用参数化通配符（更安全） #

如果想避免手动拼接字符串，也可以在传入参数时直接带上通配符，然后在查询中直接使用参数：

// 调用方法时传入："%xyz%"
@Query("SELECT * FROM #{#n1ql.bucket} WHERE #{#n1ql.filter} AND ANY v IN namelist SATISFIES v LIKE $1 END")
List<Car> findByNamelistContains(String nameWithWildcards);

这样做的好处是避免注入风险（参数化始终是数据库查询的最佳实践）。

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