从 Spring Data Couchbase 3.x 迁移到 4.x

本章快速介绍了 4.x 中引入的主要更改，并概述了迁移时需要考虑的事项。

请注意，最低 Couchbase Server 版本已隐式提升至 5.5 及更高版本，我们建议运行至少 6.0.x 版本。

配置

由于主要目标是从 Java SDK 2 迁移到 3，配置已更改以适应新的 SDK，并且从长远来看，也为作用域和集合做准备（但仍可在没有集合支持的情况下使用）。

XML 配置支持已被移除，因此仅支持基于 Java/注解的配置。

您的配置仍需继承 AbstractCouchbaseConfiguration，但由于 RBAC（基于角色的访问控制）现在是强制性的，需要重写不同的属性才能进行配置：getConnectionString、getUserName、getPassword 和 getBucketName。如果您想使用非默认作用域，可以选择重写 getScopeName 方法。请注意，如果您想使用基于证书的身份验证或需要自定义密码身份验证，可以重写 authenticator 方法来完成此任务。

新的 SDK 仍然有一个用于配置的环境，因此您可以重写 configureEnvironment 方法并在需要时提供自定义配置。

欲了解更多信息，请参阅安装与配置。

Spring Boot 版本兼容性

Spring Boot 2.3.x 或更高版本依赖于 Spring Data Couchbase 4.x。早期版本的 Couchbase 不可用，因为 SDK 2 和 3 不能在同一个类路径上共存。

实体

处理实体的方式没有改变，尽管由于 SDK 现在不再提供注解，因此仅支持 Spring Data 相关的注解。

具体来说

com.couchbase.client.java.repository.annotation.Id 变为 import org.springframework.data.annotation.Id
com.couchbase.client.java.repository.annotation.Field 变为 import org.springframework.data.couchbase.core.mapping.Field

org.springframework.data.couchbase.core.mapping.Document 注解保持不变。

欲了解更多信息，请参阅建模实体。

自动索引管理

自动索引管理已经重新设计，以允许更灵活的索引。引入了新的注解，并移除了旧的注解，如 @ViewIndexed、@N1qlSecondaryIndexed 和 @N1qlPrimaryIndexed。

欲了解更多信息，请参阅自动索引管理。

Template 和 ReactiveTemplate

由于 Couchbase SDK 3 移除了对 RxJava 的支持，取而代之的是增加了对 Reactor 的支持，因此 couchbaseTemplate 和 reactiveCouchbaseTemplate 都可以直接从 AbstractCouchbaseConfiguration 访问。

该模板已完全 overhauled，现在它使用流畅的 API 进行配置，而不是使用许多方法重载。这样做的好处是，将来我们能够扩展功能，而无需引入越来越多使导航复杂化的重载。

下表描述了 3.x 中的方法名称，并将其与 4.x 中的等效方法进行了比较

表 1. 模板方法比较
SDC 3.x	SDC 4.x
save	upsertById
insert	insertById
更新	replaceById
findById	findById
findByView	（已移除）
findBySpatialView	（已移除）
findByN1QL	findByQuery
findByN1QLProjection	findByQuery
queryN1QL	（直接调用 SDK）
exists	existsById
remove	removeById
execute	（直接调用 SDK）

此外，还添加了以下 3.x 中未提供的方法

表 2. 4.x 中模板新增功能
名称	描述
removeByQuery	允许通过 N1QL 查询删除实体
findByAnalytics	通过分析服务执行查找
findFromReplicasById	与 findById 类似，但考虑了副本

我们试图统一并使 API 更紧密地与底层 SDK 语义对齐，以便更容易关联和导航。

欲了解更多信息，请参阅模板与直接操作。

仓库与查询

org.springframework.data.couchbase.core.query.Query 变更为 org.springframework.data.couchbase.repository.Query
org.springframework.data.couchbase.repository.ReactiveCouchbaseSortingRepository 已被移除。请考虑继承 ReactiveSortingRepository 或 ReactiveCouchbaseRepository
org.springframework.data.couchbase.repository.CouchbasePagingAndSortingRepository 已被移除。请考虑继承 PagingAndSortingRepository 或 CouchbaseRepository

对视图的支持已移除，N1QL 查询现在是所有自定义仓库方法以及默认内置方法的一等公民。

查询派生本身的行为与上一版本相比没有改变。如果您遇到过去有效但现在不再有效的查询，请告知我们。

可以通过新的 ScanConsistency 注解覆盖 N1QL 查询的默认扫描一致性。

方法 getCouchbaseOperations() 也已被移除。您仍然可以通过 CouchbaseTemplate 类或 Cluster 访问所有原生 Java SDK 方法

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.couchbase.core.CouchbaseTemplate;
import org.springframework.stereotype.Service;
import com.couchbase.client.java.Cluster;

@Service
public class MyService {

    @Autowired
    private CouchbaseTemplate couchbaseTemplate;

    @Autowired
    private Cluster cluster;
}

更多信息请参阅Couchbase 仓库。

全文搜索 (FTS)

FTS API 已简化，现在可以通过 Cluster 类访问

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import com.couchbase.client.java.Cluster;
import com.couchbase.client.java.search.result.SearchResult;
import com.couchbase.client.java.search.result.SearchRow;
import com.couchbase.client.core.error.CouchbaseException;

@Service
public class MyService {

    @Autowired
    private Cluster cluster;

    public void myMethod() {
        try {
          final SearchResult result = cluster
            .searchQuery("index", SearchQuery.queryString("query"));

          for (SearchRow row : result.rows()) {
            System.out.println("Found row: " + row);
          }

          System.out.println("Reported total rows: "
            + result.metaData().metrics().totalRows());
        } catch (CouchbaseException ex) {
          ex.printStackTrace();
        }
    }
}

欲了解更多信息，请参阅FTS 文档。