模板与直接操作
模板提供对底层数据库的低层访问,同时也是仓库的基础。每当仓库对您的需求来说过于高层时,模板很可能就能很好地满足您的需求。请注意,您始终可以通过 AbstractCouchbaseConfiguration 上暴露的 Bean 直接使用 SDK。
支持的操作
您可以从上下文中通过 couchbaseTemplate 和 reactiveCouchbaseTemplate Bean 访问模板。一旦获得它的引用,就可以对其执行各种操作。与通过仓库不同,在模板中您始终需要指定想要转换到的目标实体类型。
模板采用流式风格 API,允许您根据需要链式叠加可选操作符。作为示例,下面演示如何保存一个 user 然后再通过其 ID 查找它:
示例 1. 流式模板访问
// 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 注解中的持久性选项),可以将其链式叠加进去:
示例 2. 带持久性的 upsert
User modified = couchbaseTemplate
.upsertById(User.class)
.withDurability(DurabilityLevel.MAJORITY)
.one(user);
类似地,您也可以执行 N1QL 操作:
示例 3. 模板上的 N1QL 查询
final List<User> foundUsers = couchbaseTemplate
.findByQuery(User.class)
.consistentWith(QueryScanConsistency.REQUEST_PLUS)
.all();
子文档操作
Couchbase 支持子文档操作。本节介绍如何在 Spring Data Couchbase 中使用它。
与 upsert 或 replace 等整文档操作相比,子文档操作可能更快、更省网络开销,因为它们只通过网络传输文档中被访问的部分。
子文档操作也是原子性的:如果某个子文档变更失败,则全部失败,从而以内置的并发控制安全地修改文档。
目前 Spring Data Couchbase 仅支持子文档变更(remove、upsert、replace 和 insert)。
变更操作会修改文档中的一条或多条路径。这些操作中最简单的是 upsert,它与整文档级别的 upsert 类似,会修改已有路径的值,或者在路径不存在时创建它:
以下示例会对 user 的 address 上的 city 字段执行 upsert,而不传输任何额外的 user 文档数据。
示例 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);
执行多个子文档操作
可以在同一文档上一次性执行多个子文档操作,从而同时修改多个子文档。当多个操作在单个 mutateIn 命令的上下文中提交时,服务器会基于同一文档版本执行所有操作。
要执行多个变更操作,可以使用方法链式调用。
示例 5. MutateIn 多个操作
couchbaseTemplate.mutateInById(User.class)
.withInsertPaths("roles", "subuser.firstname")
.withRemovePaths("address.city")
.withUpsertPaths("firstname")
.withReplacePaths("address.street")
.one(user);
并发修改
对文档不同部分执行的并发子文档操作不会冲突,因此在执行这些变更时默认不提供 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);
异常转换
Spring Framework 为多种数据库和映射技术提供异常转换。传统上这主要用于 JDBC 和 JPA。Spring Data Couchbase 通过提供 org.springframework.dao.support.PersistenceExceptionTranslator 接口的实现,将该特性扩展到 Couchbase。
映射到 Spring 一致的数据访问异常体系的初衷,是让您编写出可移植且具描述性的异常处理代码,而无需针对特定 Couchbase 异常进行编码和处理。Spring 的所有数据访问异常都继承自 DataAccessException 类,因此您可以确信能在单个 try-catch 块中捕获所有与数据库相关的异常。
ReactiveCouchbase 会尽早传播异常。在响应式序列处理过程中发生的异常会作为错误信号发出。