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

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

This chapter is a quick reference of what major changes have been introduced in 4.x and gives a high-level overview of things to consider when migrating.

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

Please note that implicitly the minimum Couchbase Server version has been bumped up to 5.5 and later, and we recommend running at least 6.0.x.

Configuration

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

Since the main objective was to migrate from the Java SDK 2 to 3, configuration has changed to adapt to the new SDK and also in the long run to prepare it for scopes and collections (but it can still be used without collection support).

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

XML Configuration support has been dropped, so only java/annotation based configuration is supported.

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

Your configuration still has to extend the AbstractCouchbaseConfiguration, but since RBAC (role-based access control) is now mandatory, different properties need to be overridden in order to be configured: getConnectionString, getUserName, getPassword and getBucketName.If you want to use a non-default scope optionally you can override the getScopeName method.Note that if you want to use certificate based authentication or you need to customize the password authentication, the authenticator method can be overridden to perform this task.

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

The new SDK still has an environment that is used to configure it, so you can override the configureEnvironment method and supply custom configuration if needed.

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

For more information, see Installation & Configuration.

Spring Boot Version Compatibility

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

Spring Boot 2.3.x or higher depends on Spring Data Couchbase 4.x.Earlier versions of Couchbase are not available because SDK 2 and 3 cannot live on the same classpath.

Entities

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

How to deal with entities has not changed, although since the SDK now does not ship annotations anymore only Spring-Data related annotations are supported.

具体来说：

Specifically:

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 注释保持不变。

The org.springframework.data.couchbase.core.mapping.Document annotation stayed the same.

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

For more information, see Modeling Entities.

Automatic Index Management

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

Automatic Index Management has been redesigned to allow more flexible indexing. New annotations have been introduced and old ones like @ViewIndexed, @N1qlSecondaryIndexed and @N1qlPrimaryIndexed were removed.

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

For more information, see Automatic Index Management.

Template and ReactiveTemplate

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

Since the Couchbase SDK 3 removes support for RxJava and instead adds support for Reactor, both the couchbaseTemplate as well as the reactiveCouchbaseTemplate can be directly accessed from the AbstractCouchbaseConfiguration.

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

The template has been completely overhauled so that it now uses a fluent API to configure instead of many method overloads.This has the advantage that in the future we are able to extend the functionality without having to introduce more and more overloads that make it complicated to navigate.

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

The following table describes the method names in 3.x and compares them to their 4.x equivalents:

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 中不可用的方法：

In addition, the following methods have been added which were not available in 3.x:

Table 2. Template Additions in 4.x
Name	Description
removeByQuery	Allows to remove entities through a N1QL query
findByAnalytics	Performs a find through the analytics service
findFromReplicasById	Like findById, but takes replicas into account

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

We tried to unify and align the APIs more closely to the underlying SDK semantics so they are easier to correlate and navigate.

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

For more information, see 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 has been removed.Consider extending ReactiveSortingRepository or ReactiveCouchbaseRepository
org.springframework.data.couchbase.repository.CouchbasePagingAndSortingRepository has been removed.Consider extending PagingAndSortingRepository or CouchbaseRepository

已移除视图支持，现在 N1QL 查询是针对所有自定义存储库方法和默认情况下内置方法的一等公民。

Support for views has been removed and N1QL queries are now the first-class citizens for all custom repository methods as well as the built-in ones by default.

查询派生机制的行为本身并未随新版本发生变化。如果您遇到过去可行但现在不可用的查询，请告知我们。

The behavior itself has not changed over the previous version on how the query derivation is supposed to work. Should you encounter any queries that worked in the past and now do not work anymore please let us know.

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

It is possible to override the default scan consistency for N1QL queries through the new ScanConsistency annotation.

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

The method getCouchbaseOperations() has also been removed. You can still access all methods from the native Java SDK via the class CouchbaseTemplate or Cluster:

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。

See Couchbase repositories for more information.

Full Text Search (FTS)

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

The FTS API has been simplified and now can be accessed via the Cluster class:

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。

See the FTS Documentation for more information.