從 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 文件。