Template & direct operations

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

The template provides lower level access to the underlying database and also serves as the foundation for repositories. Any time a repository is too high-level for you needs chances are good that the templates will serve you well. Note that you can always drop into the SDK directly through the beans exposed on the AbstractCouchbaseConfiguration.

Supported operations

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

The template can be accessed through the couchbaseTemplate and reactiveCouchbaseTemplate beans out of your context. Once you’ve got a reference to it, you can run all kinds of operations against it. Other than through a repository, in a template you need to always specify the target entity type which you want to get converted.

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

The templates use a fluent-style API which allows you to chain in optional operators as needed. As an example, here is how you store a user and then find it again by its 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 注释的持久性选项）持久性要求，可以将其链接起来：

If you wanted to use a custom (by default durability options from the @Document annotation will be used) durability requirement for the upsert operation you can chain it in:

Example 2. Upsert with durability

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

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

In a similar fashion, you can perform a N1QL operation:

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 配合使用。

Couchbase supports Sub-Document Operations. This section documents how to use it with Spring Data Couchbase.

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

Sub-Document operations may be quicker and more network-efficient than full-document operations such as upsert or replace because they only transmit the accessed sections of the document over the network.

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

Sub-Document operations are also atomic, in that if one Sub-Document mutation fails then all will, allowing safe modifications to documents with built-in concurrency control.

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

Currently Spring Data Couchbase supports only sub document mutations (remove, upsert, replace and insert).

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

Mutation operations modify one or more paths in the document. The simplest of these operations is upsert, which, similar to the fulldoc-level upsert, will either modify the value of an existing path or create it if it does not exist:

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

Following example will upsert the city field on the address of the user, without trasfering any additional user document data.

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 命令的上下文中提交多个操作时，服务器将使用同一版本的文档执行所有操作。

Multiple Sub-Document operations can be executed at once on the same document, allowing you to modify several Sub-Documents at once. When multiple operations are submitted within the context of a single mutateIn command, the server will execute all the operations with the same version of the document.

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

To execute several mutation operations the method chaining can be used.

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，可以像这样提供：

Concurrent Sub-Document operations on different parts of a document will not conflict so by default the CAS value will be not be supplied when executing the mutations. If CAS is required then it can be provided like this:

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。

The Spring Framework provides exception translation for a wide variety of database and mapping technologies. This has traditionally been for JDBC and JPA. Spring Data Couchbase extends this feature to Couchbase by providing an implementation of the org.springframework.dao.support.PersistenceExceptionTranslator interface.

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

The motivation behind mapping to Spring’s consistent data access exception hierarchy is to let you write portable and descriptive exception handling code without resorting to coding against and handling specific Couchbase exceptions. All of Spring’s data access exceptions are inherited from the DataAccessException class, so you can be sure that you can catch all database-related exceptions within a single try-catch block.

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

ReactiveCouchbase propagates exceptions as early as possible. Exceptions that occur during the processing of the reactive sequence are emitted as error signals.