跳到主要内容

从 Spring Data Couchbase 3.x 升级到 4.x

ChatGPT-4o-mini 中英对照 Migrating from Spring Data Couchbase 3.x to 4.x

本章是 4.x 中引入的主要变化的快速参考，并提供了迁移时需要考虑的事项的高层次概述。

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

配置​

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

important

已不再支持 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 不能共存于同一个类路径中。

实体​

To handle entities that have not changed, you can follow these steps, especially considering that the SDK no longer ships with annotations and only supports Spring Data related annotations:

  1. Remove Deprecated Annotations: Ensure that any annotations that are no longer supported by the SDK are removed from your entity classes.

  2. Use Spring Data Annotations: Replace any removed annotations with the appropriate Spring Data annotations. For example, use @Entity, @Table, @Id, etc., as needed.

  3. Check for Entity Changes: Implement logic to check if the entity has changed before performing any operations. This can be done by comparing the current state of the entity with its previous state.

  4. Update Repository Methods: Ensure that your repository methods are updated to work with the new annotations and that they correctly handle the persistence of unchanged entities.

  5. Testing: Thoroughly test your application to ensure that the changes do not affect the functionality and that unchanged entities are handled correctly.

If you need specific code examples or further assistance, please let me know!

具体来说：

  • 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 注解保持不变.

有关更多信息，请参见 Modeling Entities。

自动索引管理​

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

有关更多信息，请参见 自动索引管理。

模板和 ReactiveTemplate​

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

模板已被完全重构，现在使用流畅的 API 来进行配置，而不是许多方法重载。这样做的好处是，未来我们可以扩展功能，而不需要引入越来越多的重载方法，从而避免使导航变得复杂。

以下表格描述了 3.x 中的方法名称，并将其与 4.x 中的对应名称进行比较：

表 1. 模板方法比较

SDC 3.xSDC 4.x
saveupsertById
insertinsertById
updatereplaceById
findByIdfindById
findByView(已移除)
findBySpatialView(已移除)
findByN1QLfindByQuery
findByN1QLProjectionfindByQuery
queryN1QL(直接调用 SDK)
existsexistsById
removeremoveById
execute(直接调用 SDK)

此外，以下方法已被添加，这些方法在 3.x 中不可用：

表 2. 4.x 中的模板添加

名称描述
removeByQuery允许通过 N1QL 查询删除实体
findByAnalytics通过分析服务执行查找
findFromReplicasById类似于 findById，但考虑到副本

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

欲了解更多信息，请参阅 Template & direct operations。

Repositories & Queries​

  • 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

important

视图支持已被移除，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;
}
java

请参阅 Couchbase repositories 以获取更多信息。

全文搜索 (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();
        }
    }
}
java

请参阅 FTS 文档 以获取更多信息。