從 Spring Data Couchbase 3.x 遷移到 4.x

本章節快速參考 4.x 中引入的主要變更，並提供遷移時需要考量事項的高階概觀。

請注意，最低 Couchbase Server 版本已隱含地提升至 5.5 及更高版本，我們建議至少執行 6.0.x。

設定

由於主要目標是從 Java SDK 2 遷移到 3，因此組態已變更以適應新的 SDK，並在長期內為 scopes 和 collections 做好準備（但它仍然可以在沒有 collection 支援的情況下使用）。

XML 組態支援已被移除，因此僅支援基於 Java/註解的組態。

您的組態仍然必須擴充 AbstractCouchbaseConfiguration，但由於 RBAC（基於角色的存取控制）現在是強制性的，因此需要覆寫不同的屬性才能進行組態：getConnectionString、getUserName、getPassword 和 getBucketName。如果您想選擇性地使用非預設 scope，您可以覆寫 getScopeName 方法。請注意，如果您想使用基於憑證的身份驗證，或者您需要自訂密碼驗證，則可以覆寫 authenticator 方法來執行此任務。

新的 SDK 仍然有一個用於配置它的環境，因此您可以覆寫 configureEnvironment 方法並在需要時提供自訂組態。

如需更多資訊，請參閱安裝與設定。

Spring Boot 版本相容性

Spring Boot 2.3.x 或更高版本取決於 Spring Data Couchbase 4.x。較早版本的 Couchbase 無法使用，因為 SDK 2 和 3 無法在同一個類別路徑中共存。

實體

如何處理實體沒有改變，儘管由於 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。

如需更多資訊，請參閱自動索引管理。

樣板和 ReactiveTemplate

由於 Couchbase SDK 3 移除了對 RxJava 的支援，並改為添加了對 Reactor 的支援，因此可以從 AbstractCouchbaseConfiguration 直接存取 couchbaseTemplate 以及 reactiveCouchbaseTemplate。

樣板已完全修改，因此它現在使用流暢的 API 進行配置，而不是許多方法重載。這具有優勢，因為在未來我們能夠擴展功能，而無需引入越來越多的重載，使其難以導航。

下表描述了 3.x 中的方法名稱，並將其與 4.x 的對應名稱進行比較

表 1. 樣板方法比較
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 中新增的樣板
名稱	描述
removeByQuery	允許透過 N1QL 查詢移除實體
findByAnalytics	透過分析服務執行查找
findFromReplicasById	類似於 findById，但考慮到副本

我們嘗試統一並更緊密地對齊 API 與底層 SDK 語義，以便它們更容易關聯和導航。

如需更多資訊，請參閱樣板與直接操作。

儲存庫與查詢

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

已移除對 View 的支援，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 儲存庫。

全文搜尋 (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 文件。