Couchbase 中通过 N1QL 查询刚插入的数据偶发丢失，根本原因在于默认查询不保证读取到最新写入——需显式配置 REQUEST_PLUS 一致性级别，或改用 Spring Data Couchbase 原生 Repository 方法规避手动查询风险。
couchbase 中通过 n1ql 查询刚插入的数据偶发丢失，根本原因在于默认查询不保证读取到最新写入——需显式配置 `request_plus` 一致性级别，或改用 spring data couchbase 原生 repository 方法规避手动查询风险。
在 Spring Boot 应用中集成 Couchbase 时，开发者常误以为 collection.insert() 后立即执行 SELECT * FROM ... 就能查到新数据，但实际会遇到随机性查询缺失（如插入 2 条却只查出 1 条）。这并非并发或事务配置错误，而是 Couchbase 架构层面的设计特性所致。
? 根本原因：N1QL 查询与 KV 操作的“可见性”差异
Couchbase 的键值（KV）操作（如 insert()）是强一致性的——调用返回即代表文档已持久化并可被 get() 立即读取；但 N1QL 查询依赖全局二级索引（GSI），而索引更新存在毫秒级延迟（称为 index lag）。默认情况下，查询采用 NOT_BOUNDED 一致性模式，不等待索引同步，因此可能查不到刚刚写入、尚未被索引覆盖的文档。
调试时测试“总能通过”，正是因为断点人为引入了足够延迟，让索引完成刷新——这恰恰印证了异步索引的时序问题。
✅ 正确解法一：强制查询等待索引就绪（REQUEST_PLUS）
在手动 N1QL 查询中，必须显式设置 QueryScanConsistency.REQUEST_PLUS：
@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());
}⚠️ 注意：REQUEST_PLUS 会带来轻微性能开销（需协调索引状态），仅建议用于强一致性要求场景（如测试验证、关键业务读写链路）。
✅ 正确解法二：优先使用 Spring Data Couchbase 原生 Repository（推荐）
手动拼 SQL + 手动映射不仅易错，更绕过了 Spring Data 的一致性保障机制。应改用声明式 Repository：
@Repository
@Scope("customer-scope") // 指定 Scope（需匹配 Bucket 配置）
@Collection("customer-collection")
public interface CustomerRepository extends ReactiveCouchbaseRepository<Customer, String> {
// 自动继承 findAll()，且默认使用 REQUEST_PLUS 一致性
Flux<Customer> findAll(); // Reactor 版本（推荐）
// 或使用阻塞版：List<Customer> findAll();
}Spring Data Couchbase 在底层自动应用 REQUEST_PLUS 于所有查询方法（包括 findAll()），无需额外配置。同时支持注解驱动的 Scope/Collection 定位，彻底避免硬编码键空间与手动 JSON 映射。
? 常见误区澄清
- @Transactional 对 N1QL 查询无效：Couchbase 的 @Transaction 仅作用于 SDK 的事务 API（如 transactions.run()），而 couchbaseTemplate.query() 属于非事务性查询，加注解无意义。
- couchbaseTemplate 不等于 Spring Data 抽象层：一旦调用 getCluster() 或 getScope() 获取原生 SDK 对象，后续代码即脱离 Spring Data 管理，失去其自动一致性、类型转换、异常翻译等能力。
- 自定义 mapJsonToCustomer() 是冗余的：Spring Data 已内置 Jackson / Gson 映射器，直接定义实体类 @Document 即可自动序列化。
✅ 最佳实践总结
- 生产环境优先使用 ReactiveCouchbaseRepository：语义清晰、一致性内建、响应式友好；
- 若必须手写 N1QL，请始终附加 QueryScanConsistency.REQUEST_PLUS；
- 测试中避免依赖“延迟巧合”：禁用 Thread.sleep() 或调试断点来“修复”问题，应通过一致性配置真正解决；
- 验证索引状态：可通过 Couchbase Web Console > Query Workbench 执行 SELECT COUNT(*) FROM bucket.scope.collection 并观察执行计划中的 "scanConsistency":"request_plus" 是否生效。
遵循以上方案，即可彻底消除“插入后查询丢失”的随机失败，构建稳定可靠的 Couchbase CRUD 服务。
