Spring Boot集成Couchbase遇Value is never used as Publisher警告

问题原因 #

ReactiveCollection的upsert()和remove()方法返回的是Mono<MutationResult>（Publisher的实现类），反应式流是惰性执行的——只有当Publisher被订阅时，对应的数据库操作才会真正触发。如果只调用方法但不处理返回的Publisher（比如不返回给上层、不手动订阅、不调用阻塞方法），IDE会弹出该警告，同时你的数据库操作根本不会执行。

解决方法 #

根据你的代码场景，选择以下任意一种方案：

1. 保持反应式链路（推荐） #

让仓库方法返回Mono，把Publisher传递到上层调用链中，由上层（比如WebFlux Controller、反应式Service）负责订阅：

@Repository
public class CouchbaseDocumentRepository {

    private final ReactiveCollection reactiveCollection;

    // 构造注入ReactiveCollection（依赖你的Couchbase配置）
    public CouchbaseDocumentRepository(Cluster cluster) {
        this.reactiveCollection = cluster.bucket("your-bucket-name").defaultCollection().reactive();
    }

    // 返回Mono，交由上层处理订阅逻辑
    public Mono<MutationResult> upsertDocument(YourCustomDocument doc) {
        return reactiveCollection.upsert(doc.getDocId(), doc);
    }

    public Mono<MutationResult> removeDocument(String docId) {
        return reactiveCollection.remove(docId);
    }
}

上层调用示例（WebFlux Controller）：

@RestController
@RequestMapping("/documents")
public class DocumentController {

    private final CouchbaseDocumentRepository repository;

    public DocumentController(CouchbaseDocumentRepository repository) {
        this.repository = repository;
    }

    @PostMapping
    public Mono<ResponseEntity<Void>> saveDocument(@RequestBody YourCustomDocument doc) {
        return repository.upsertDocument(doc)
                .map(result -> ResponseEntity.status(HttpStatus.CREATED).build());
        // Spring WebFlux会自动订阅该Mono，触发数据库操作
    }
}

2. 同步执行（仅适用于非反应式场景） #

如果必须在命令式代码中执行操作，可以调用block()方法强制订阅并等待结果，但不推荐在WebFlux等反应式上下文使用，会阻塞线程：

public void upsertDocumentSync(YourCustomDocument doc) {
    try {
        MutationResult result = reactiveCollection.upsert(doc.getDocId(), doc).block();
        // 可在此处理结果，比如日志打印、结果校验
    } catch (RuntimeException e) {
        // 处理数据库异常，如连接失败、文档格式错误等
    }
}

3. 确认配置类的正确性 #

确保你的Couchbase配置正确初始化了ReactiveCollection，示例配置：

@Configuration
public class CouchbaseConfig {

    @Value("${spring.couchbase.connection-string}")
    private String connectionString;

    @Value("${spring.couchbase.username}")
    private String username;

    @Value("${spring.couchbase.password}")
    private String password;

    @Bean
    public Cluster couchbaseCluster() {
        return Cluster.connect(connectionString, username, password);
    }

    @Bean
    public ReactiveCollection reactiveCollection(Cluster cluster) {
        return cluster.bucket("your-bucket-name").defaultCollection().reactive();
    }
}

关键注意事项 #

• 反应式编程的核心是避免阻塞，尽量让整个调用链保持反应式（返回Mono/Flux），由框架或上层代码处理订阅
• 如果你的项目是传统Spring MVC（非WebFlux），建议直接使用Couchbase的同步客户端Collection，避免混合反应式与命令式代码的问题
• 忽略该警告会导致数据库操作不执行，必须处理返回的Publisher

内容的提问来源于stack exchange，提问作者Emre Törker