跳到主要内容

模板与直接操作

ChatGPT-4o-mini 中英对照 Template & direct operations

该模板提供了对底层数据库的更低级别访问，并且作为仓库的基础。每当仓库对您的需求来说过于高层时，模板很可能会很好地为您服务。请注意，您始终可以通过 AbstractCouchbaseConfiguration 上暴露的 beans 直接进入 SDK。

支持的操作​

可以通过 couchbaseTemplate 和 reactiveCouchbaseTemplate bean 从你的上下文中访问模板。一旦你获得了对它的引用，你可以对其执行各种操作。除了通过存储库，在模板中你需要始终指定你想要转换的目标实体类型。

这些模板使用流畅风格的 API，允许根据需要链式调用可选操作符。例如，以下是如何存储一个用户并通过其 ID 再次查找它：

示例 1. Fluent 模板访问

// Create an Entity
User user = new User(UUID.randomUUID().toString(), "firstname", "lastname");

// Upsert it
couchbaseTemplate.upsertById(User.class).one(user);

// Retrieve it again
User found = couchbaseTemplate.findById(User.class).one(user.getId());
java

如果你想为 upsert 操作使用自定义的耐久性要求（默认情况下将使用 @Document 注解中的耐久性选项），你可以将其链式调用进去：

示例 2. 带持久性的 Upsert

User modified = couchbaseTemplate
  .upsertById(User.class)
  .withDurability(DurabilityLevel.MAJORITY)
  .one(user);
java

以类似的方式，您可以执行 N1QL 操作：

示例 3. 在模板上执行 N1QL 查询

final List<User> foundUsers = couchbaseTemplate
  .findByQuery(User.class)
  .consistentWith(QueryScanConsistency.REQUEST_PLUS)
  .all();
java

子文档操作​

Couchbase 支持 子文档操作。本节文档介绍了如何在 Spring Data Couchbase 中使用它。

子文档操作可能比完整文档操作（如插入或替换）更快且更具网络效率，因为它们仅传输文档中访问的部分内容。

子文档操作也是原子性的，即如果一个子文档的变更失败，则所有变更都会失败，从而允许在内建并发控制的情况下安全地修改文档。

目前，Spring Data Couchbase 仅支持子文档变更（删除、更新插入、替换和插入）。

变更操作修改文档中的一个或多个路径。这些操作中最简单的是 upsert，类似于 fulldoc 级别的 upsert，它将修改现有路径的值，或者如果该路径不存在，则创建它：

以下示例将更新用户地址中的城市字段，而不传输任何其他用户文档数据。

示例 4. 在模板上进行 MutateIn upsert

User user = new User();
// id field on the base document id required
user.setId(ID);
user.setAddress(address);
couchbaseTemplate.mutateInById(User.class)
    .withUpsertPaths("address.city")
    .one(user);
java

执行多个子文档操作​

多个子文档操作可以在同一文档上同时执行，允许您一次修改多个子文档。当在单个 mutateIn 命令的上下文中提交多个操作时，服务器将使用文档的相同版本执行所有操作。

要执行多个变更操作，可以使用方法链。

示例 5. MutateIn 多重操作

couchbaseTemplate.mutateInById(User.class)
    .withInsertPaths("roles", "subuser.firstname")
    .withRemovePaths("address.city")
    .withUpsertPaths("firstname")
    .withReplacePaths("address.street")
    .one(user);
java

并发修改​

在文档的不同部分进行并发子文档操作时不会发生冲突，因此默认情况下执行变更时不会提供 CAS 值。如果需要 CAS 值，可以像这样提供：

示例 6. 带 CAS 的 MutateIn

User user = new User();
// id field on the base document id required
user.setId(ID);
// @Version field should have a value for CAS to be supplied
user.setVersion(cas);
user.setAddress(address);
couchbaseTemplate.mutateInById(User.class)
    .withUpsertPaths("address.city")
    .withCasProvided()
    .one(user);
java

异常翻译​

Spring 框架为各种数据库和映射技术提供了异常转换。这通常是针对 JDBC 和 JPA。Spring Data Couchbase 通过提供 org.springframework.dao.support.PersistenceExceptionTranslator 接口的实现，将此功能扩展到 Couchbase。

映射到 Spring 的 一致数据访问异常层次结构 的动机是让您编写可移植和描述性的异常处理代码，而无需针对特定的 Couchbase 异常进行编码和处理。所有 Spring 的数据访问异常都继承自 DataAccessException 类，因此您可以确保在单个 try-catch 块中捕获所有与数据库相关的异常。

ReactiveCouchbase 尽早传播异常。在处理反应式序列的过程中发生的异常会作为错误信号发出。