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

本章快速介绍了 4.x 版本引入的主要变化，并提供了迁移时需要考虑事项的高级概述。

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

配置

由于主要目标是从 Java SDK 2 迁移到 3，配置已更改以适应新的 SDK，并且从长远来看也为范围 (scopes) 和集合 (collections) 做准备（但即使不使用集合支持，它仍然可以使用）。

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 不能在同一个 classpath 中共存。

实体

处理实体的方式没有改变，尽管由于 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` 访问。

该 template 已经完全重写，现在使用流畅的 API 进行配置，而不是许多方法重载。这样做的好处是将来我们能够扩展功能而无需引入越来越多使其难以导航的重载。

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

表 1. Template 方法比较
SDC 3.x	SDC 4.x
save	upsertById
insert	insertById
update	replaceById
findById	findById
findByView	(已移除)
findBySpatialView	(已移除)
findByN1QL	findByQuery
findByN1QLProjection	findByQuery
queryN1QL	(直接调用 SDK)
exists	existsById
remove	removeById
execute	(直接调用 SDK)

此外，还添加了以下在 3.x 中不可用的方法

表 2. 4.x 中添加的 Template 方法
名称	描述
removeByQuery	允许通过 N1QL 查询删除实体
findByAnalytics	通过分析服务执行查找
findFromReplicasById	类似于 findById，但考虑副本

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

更多信息请参阅Template 与直接操作。

Repository 与查询

`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`。

对 views 的支持已被移除，N1QL 查询现在是所有自定义 Repository 方法以及内置方法的一等公民。

查询派生的行为本身与之前版本相比没有变化。如果您遇到过去可行而现在不再可行的查询，请告知我们。

可以通过新的 `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 Repository。

全文搜索 (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 文档。