Couchbase 查询默认不保证实时可见性，插入后立即执行 N1QL 查询可能因索引延迟而漏查数据；需显式配置 REQUEST_PLUS 一致性级别或改用 Spring Data 原生 Repository 方法规避该问题。
couchbase 查询默认不保证实时可见性，插入后立即执行 n1ql 查询可能因索引延迟而漏查数据；需显式配置 `request_plus` 一致性级别或改用 spring data 原生 repository 方法规避该问题。
在 Spring Boot 中集成 Couchbase 时，开发者常误以为 collection.insert() 后立即执行 SELECT * FROM ... 就能查到刚插入的数据——但实际并非如此。根本原因在于：KV 操作（如 insert/get）是强一致性的，而 N1QL 查询依赖后台全文索引（GSI），存在毫秒级延迟。当测试中并发执行写入与查询时，若未指定查询一致性级别，Couchbase 查询引擎可能返回“旧快照”，导致 findAll() 随机缺失部分文档（尤其在非调试环境下）。
✅ 正确做法一：为 N1QL 查询启用 REQUEST_PLUS 一致性
若坚持使用 couchbaseTemplate 手动执行查询，必须显式设置扫描一致性：
import com.couchbase.client.java.query.QueryOptions;
import com.couchbase.client.java.query.QueryScanConsistency;
// 替换原 findAll() 实现：
@Override
public List<Customer> findAll() {
QueryOptions options = QueryOptions.queryOptions()
.scanConsistency(QueryScanConsistency.REQUEST_PLUS); // 关键配置！
List<JsonObject> jsonObjects = couchbaseTemplate.getCouchbaseClientFactory().getScope()
.query(String.format("SELECT * FROM %s", keySpace), options)
.rowsAsObject();
return jsonObjects.stream()
.map(this::mapJsonToCustomer)
.collect(Collectors.toList());
}⚠️ 注意：QueryScanConsistency.REQUEST_PLUS 会阻塞查询，直至所有已提交的变更完成索引构建，确保结果包含本次事务写入的数据。这是解决“随机丢失数据”问题最直接有效的方案。
✅ 正确做法二：优先使用 Spring Data Couchbase 原生 Repository（推荐）
手动拼 SQL + JSON 映射不仅冗余，还绕过了 Spring Data 的自动序列化、事务上下文及一致性管理。应改用声明式 Repository：
@Repository
public interface CustomerRepository extends ReactiveCouchbaseRepository<Customer, String> {
// 自动提供 findAll(), findById() 等方法
@Override
@ScanConsistency(query = QueryScanConsistency.REQUEST_PLUS) // Spring Data 专用注解
Flux<Customer> findAll();
}或同步版本（若未使用 WebFlux）：
@Repository
public interface CustomerRepository extends CouchbaseRepository<Customer, String> {
@ScanConsistency(query = QueryScanConsistency.REQUEST_PLUS)
List<Customer> findAll();
}此时 customerRepository.findAll() 内部已自动应用 REQUEST_PLUS，无需手写 N1QL 或处理 JSON 转换——Spring Data 会通过 @Document 注解自动完成对象-JSON 映射。
❌ 常见误区澄清
- @Transactional 对 N1QL 查询无效：Couchbase 的 @Transaction 仅作用于 KV 操作（如 insert/update），不控制查询一致性；N1QL 查询需独立配置 ScanConsistency。
- couchbaseTemplate.getCouchbaseClientFactory().getCluster() 绕过了 Spring Data 层：后续调用 SDK 原生 API（如 .query()）将失去 Spring Data 的一致性封装、异常翻译和类型安全。
- 调试模式“偶然成功”不是 bug 修复：调试时单步执行引入了隐式延迟，恰好让索引追上写入，掩盖了根本问题。
✅ 最佳实践总结
| 场景 | 推荐方案 |
|---|---|
| 快速验证/简单 CRUD | 使用 CouchbaseRepository + @ScanConsistency 注解 |
| 复杂查询需自定义 N1QL | 通过 CouchbaseTemplate 调用 .query() 并显式传入 QueryOptions |
| 高并发写入+实时查询 | 结合 REQUEST_PLUS 与适当索引设计（如覆盖索引），避免全表扫描 |
遵循上述方案，即可彻底解决“插入后查询随机丢失数据”的问题，同时提升代码可维护性与 Spring 生态兼容性。
