Migrating from Spring Data Couchbase 3.x to 4.x

本章对 4.x 中引入的主要更改进行了快速参考，并对迁移时需要考虑的事项进行了概览介绍。请注意，隐式地将最低的 Couchbase Server 版本提升到 5.5 及更高版本，我们建议至少运行 6.0.x 版。

Configuration

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

XML 配置支持已不再受支持，因此仅支持基于 java/注释的配置。

你的配置仍必须扩展 AbstractCouchbaseConfiguration，但因为 RBAC（基于角色的访问控制）现在是强制性的，因此需要覆盖不同的属性才能进行配置：getConnectionString、getUserName、getPassword 和 getBucketName。如果你想使用非默认作用域，可以选择覆盖 getScopeName 方法。请注意，如果你想使用基于证书的身份验证，或者你需要自定义密码身份验证，则可以覆盖 authenticator 方法来执行此任务。

新 SDK 仍然有一个用于配置它的环境，因此如果你需要，可以覆盖 configureEnvironment 方法并提供自定义配置。

如需更多信息，请参阅 Installation & Configuration。

Spring Boot Version Compatibility

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

Entities

如何处理实体没有改变，尽管由于 SDK 现在不再支持注释，因此只支持与 Spring Data 相关的注释。

具体来说：

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

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

如需更多信息，请参阅 Modeling Entities。

Automatic Index Management

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

有关更多信息，请参阅 ``。

Template and ReactiveTemplate

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

模板已经过彻底检修，因此现在它使用流畅的 API 进行配置，而不是许多方法重载。这具有这样的优点：在未来，我们能够扩展功能，而不必引入更多重载，这使得导航变得复杂。

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

Table 1. Template Method Comparison
SDC 3.x	SDC 4.x
save	upsertById
insert	insertById
update	replaceById
findById	findById
findByView	(removed)
findBySpatialView	(removed)
findByN1QL	findByQuery
findByN1QLProjection	findByQuery
queryN1QL	(call SDK directly)
exists	existsById
remove	removeById
execute	(call SDK directly)

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

Table 2. Template Additions in 4.x
Name	Description
removeByQuery	允许通过 N1QL 查询删除实体
findByAnalytics	通过分析服务执行查找
findFromReplicasById	与 findById 相似，但考虑到了副本

我们尝试统一和调整 API，让其更贴合基础 SDK 语义，以便于关联和导航。

如需更多信息，请参阅 Template & direct operations。

Repositories & Queries

org.springframework.data.couchbase.core.query.Query became 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 repositories。

Full Text Search (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();
        }
    }
}

如需更多信息，请参阅 the FTS Documentation。