Template & direct operations

该模板提供对基础数据库的更低级别访问，并作为存储库的基础。如果存储库对你而言级别太高，那么有很大几率模板将很好地为你服务。请注意，始终可以通过在 AbstractCouchbaseConfiguration 上公开的 bean 直接进入 SDK。

Supported operations

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

这些模板使用一种流畅风格的 API，它允许根据需要将可选项操作员链接起来。作为一个示例，以下是存储用户然后根据其 ID 再次查找它的方法：

Example 1. Fluent template access

// 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());

如果想对 upsert 操作使用自定义（默认情况下将使用来自 @Document 注释的持久性选项）持久性要求，可以将其链接起来：

Example 2. Upsert with durability

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

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

Example 3. N1QL query on the template

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

Sub-Document Operations

Couchbase 支持 ``。本部分记录了如何将它与 Spring Data Couchbase 配合使用。

与 upsert 或替换之类的完整文档操作相比，子文档操作可能更快、更节省网络，因为它们仅通过网络传输文档的访问部分。

子文档操作也是原子的，如果一个子文档突变失败，则所有操作都将失败，从而允许对具有内置并发控制的文档进行安全修改。

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

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

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

Example 4. MutateIn upsert on the template

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);

Executing Multiple Sub-Document Operations

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

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

Example 5. MutateIn Multiple Operations

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

Concurrent Modifications

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

Example 6. MutateIn With CAS

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);

Exception Translation

Spring Framework 为各种数据库和映射技术提供异常转换。按照传统，它适用于 JDBC 和 JPA。Spring Data Couchbase 通过提供 org.springframework.dao.support.PersistenceExceptionTranslator 接口的实现将此功能扩展到 Couchbase。

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

ReactiveCouchbase 尽早传播异常。在处理反应序列期间发生的异常将作为错误信号发出。