对于最新的稳定版本，请使用 Spring Data Couchbase 5.3.1！

对于最新的稳定版本，请使用 Spring Data Couchbase 5.3.1！

Spring Data 存储库抽象的目标是显著减少为各种持久性存储实现数据访问层所需的样板代码量。

默认情况下，如果操作是单文档操作且 ID 已知，则操作由 Key/Value 提供支持。 对于所有其他操作，默认情况下会生成 N1QL 查询，因此必须为高性能数据访问创建适当的索引。

请注意，您可以调整查询所需的一致性（请参阅使用一致性进行查询），并具有由不同存储桶支持的不同存储库（请参阅 [couchbase.repository.multibucket])

配置

虽然始终存在对存储库的支持，但您需要在一般情况下或为特定命名空间启用它们。 如果扩展 ，只需使用注释即可。 它提供了许多可能的选项来缩小或自定义搜索路径，最常见的选项之一是 .AbstractCouchbaseConfiguration@EnableCouchbaseRepositoriesbasePackages

另请注意，如果您在 spring boot 中运行，autoconfig 支持已经为您设置了注解，因此您只需要在要覆盖默认值时使用它。

例 1.基于注释的存储库设置
@Configuration
@EnableCouchbaseRepositories(basePackages = {"com.couchbase.example.repos"})
public class Config extends AbstractCouchbaseConfiguration {
    //...
}

[couchbase.repository.multibucket] 中描述了高级用法。

QueryDSL 配置

Spring Data Couchbase 支持 QueryDSL 来构建类型安全查询。要启用代码生成，您需要在项目上设置为注释处理器。spring-data-couchbase

例 2.Maven 配置示例
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>[compiler-plugin-version]</version>
            <configuration>
                <annotationProcessorPaths>
                    <!-- path to the annotation processor -->
                    <path>
                        <groupId>com.querydsl</groupId>
                        <artifactId>querydsl-apt</artifactId>
                        <version>[version]</version>
                    </path>
                    <path>
                        <groupId>org.springframework.data</groupId>
                        <artifactId>spring-data-couchbase</artifactId>
                        <version>[version]</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>
例 3.Gradle 配置示例
annotationProcessor 'com.querydsl:querydsl-apt:${querydslVersion}'
annotationProcessor 'org.springframework.data:spring-data-couchbase:${springDataCouchbaseVersion}'

用法

在最简单的情况下，您的存储库将扩展 ，其中 T 是要公开的实体。 让我们看一下 UserInfo 的存储库：CrudRepository<T, String>

例 4.UserInfo 存储库
import org.springframework.data.repository.CrudRepository;

public interface UserRepository extends CrudRepository<UserInfo, String> {
}

请注意，这只是一个接口，而不是一个实际的类。 在后台，当您的上下文被初始化时，将创建存储库描述的实际实现，您可以通过常规 Bean 访问它们。 这意味着您将节省大量样板代码，同时仍将完整的 CRUD 语义暴露给您的服务层和应用程序。

现在，让我们想象一下，我们是一个使用它的类。 我们有什么可用的方法？@AutowireUserRepository

表 1.UserRepository 上公开的方法
方法 描述

UserInfo 保存（UserInfo 实体）

保存给定的实体。

Iterable<UserInfo> save（Iterable<UserInfo> 实体）

保存实体列表。

用户信息 findOne（字符串 id）

按实体的唯一 ID 查找实体。

boolean exists（字符串 id）

检查给定实体是否存在其唯一 ID。

Iterable<UserInfo> findAll（）

在存储桶中按此类型查找所有实体。

Iterable<UserInfo> findAll（Iterable<String> ids）

按此类型和给定的 ID 列表查找所有实体。

长计数（）

计算存储桶中的实体数。

void delete（字符串 id）

按实体的 ID 删除实体。

void delete（UserInfo 实体）

删除实体。

void delete（Iterable<UserInfo> 实体）

删除所有给定的实体。

无效 deleteAll（）

按类型删除存储桶中的所有实体。

现在真是太棒了！ 只需定义一个接口，我们就可以在托管实体之上获得完整的 CRUD 功能。

虽然公开的方法为您提供了各种各样的访问模式，但通常需要定义自定义模式。 您可以通过向接口添加方法声明来做到这一点，这些声明将在后台自动解析为请求，我们将在下一节中看到。

表 1.UserRepository 上公开的方法
方法 描述

UserInfo 保存（UserInfo 实体）

保存给定的实体。

Iterable<UserInfo> save（Iterable<UserInfo> 实体）

保存实体列表。

用户信息 findOne（字符串 id）

按实体的唯一 ID 查找实体。

boolean exists（字符串 id）

检查给定实体是否存在其唯一 ID。

Iterable<UserInfo> findAll（）

在存储桶中按此类型查找所有实体。

Iterable<UserInfo> findAll（Iterable<String> ids）

按此类型和给定的 ID 列表查找所有实体。

长计数（）

计算存储桶中的实体数。

void delete（字符串 id）

按实体的 ID 删除实体。

void delete（UserInfo 实体）

删除实体。

void delete（Iterable<UserInfo> 实体）

删除所有给定的实体。

无效 deleteAll（）

按类型删除存储桶中的所有实体。

存储库和查询

基于 N1QL 的查询

先决条件是在存储实体的存储桶上创建 PRIMARY INDEX。

下面是一个示例：

例 5.具有 N1QL 查询的扩展 UserInfo 存储库
public interface UserRepository extends CrudRepository<UserInfo, String> {

    @Query("#{#n1ql.selectEntity} WHERE role = 'admin' AND #{#n1ql.filter}")
    List<UserInfo> findAllAdmins();

    List<UserInfo> findByFirstname(String fname);
}

在这里，我们看到两种 N1QL 支持的查询方式。

第一种方法使用注释以内联方式提供 N1QL 语句。 SpEL（Spring 表达式语言）由 和 之间的周围 SpEL 表达式块支持。 SpEL 提供了一些特定于 N1QL 的值：Query#{}

  • #n1ql.selectEntity允许轻松确保语句将选择构建完整实体所需的所有字段（包括文档 ID 和 CAS 值）。

  • #n1ql.filter在 WHERE 子句中添加一个条件，将实体类型与 Spring Data 用于存储类型信息的字段相匹配。

  • #n1ql.bucket将替换为存储实体的存储桶的名称，并在反引号中转义。

  • #n1ql.scope将替换为存储实体的范围的名称，并在反引号中转义。

  • #n1ql.collection将替换为存储实体的集合的名称，并在反引号中转义。

  • #n1ql.fields将被替换为重建实体所需的字段列表（例如，对于 SELECT 子句）。

  • #n1ql.delete将被语句替换。delete from

  • #n1ql.returning将替换为重建实体所需的返回子句。

我们建议您始终将 SpEL 和 WHERE 子句与 SpEL 一起使用（否则您的查询可能会受到来自其他存储库的实体的影响）。selectEntityfilter

基于字符串的查询支持参数化查询。 您可以使用位置占位符，如“$1”，在这种情况下，每个方法参数将按顺序映射到 、 、 ...或者，您可以使用“$someString”语法使用命名占位符。 方法参数将使用参数名称与其相应的占位符匹配，可以通过用 （例如） 注释每个参数（或除外）来覆盖该占位符。 您不能在查询中混合使用这两种方法，如果这样做，则会得到一个。$1$2$3PageableSort@Param@Param("someString")IllegalArgumentException

请注意，您可以混合使用 N1QL 占位符和 SpEL。N1QL 占位符仍将考虑所有方法参数，因此请务必使用正确的索引，如下例所示：

例 6.混合了 SpEL 和 N1QL 占位符的内联查询
@Query("#{#n1ql.selectEntity} WHERE #{#n1ql.filter} AND #{[0]} = $2")
public List<User> findUsersByDynamicCriteria(String criteriaField, Object criteriaValue)

这允许您生成与 eg. 或者，使用单个方法声明。AND name = "someName"AND age = 3

您还可以在 N1QL 查询中执行单个投影（前提是它只选择一个字段并只返回一个结果，通常是像 、 、 等聚合）。 这种投影将具有简单的返回类型，如 或 。 这不适用于对 DTO 的预测。COUNTAVGMAXlongbooleanString

另一个例子：

相当于#{#n1ql.selectEntity} WHERE #{#n1ql.filter} AND test = $1
SELECT #{#n1ql.fields} FROM #{#n1ql.collection} WHERE #{#n1ql.filter} AND test = $1

SpEL 与 Spring Security 的实际应用

当您想根据其他 Spring 组件（如 Spring Security）注入的数据进行查询时，SpEL 非常有用。 以下是扩展 SpEL 上下文以访问此类外部数据所需的操作。

首先，您需要实现一个（使用支持类，如下所示）：EvaluationContextExtension

class SecurityEvaluationContextExtension extends EvaluationContextExtensionSupport {

  @Override
  public String getExtensionId() {
    return "security";
  }

  @Override
  public SecurityExpressionRoot getRootObject() {
    Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
    return new SecurityExpressionRoot(authentication) {};
  }
}

然后，要使Spring Data Couchbase能够访问关联的SpEL值，您需要做的就是在配置中声明相应的bean：

@Bean
EvaluationContextExtension securityExtension() {
    return new SecurityEvaluationContextExtension();
}

这对于根据连接用户的角色制作查询可能很有用，例如：

@Query("#{#n1ql.selectEntity} WHERE #{#n1ql.filter} AND " +
"role = '?#{hasRole('ROLE_ADMIN') ? 'public_admin' : 'admin'}'")
List<UserInfo> findAllAdmins(); //only ROLE_ADMIN users will see hidden admins

删除查询示例：

@Query("#{#n1ql.delete} WHERE #{#n1ql.filter} AND " +
"username = $1 #{#n1ql.returning}")
UserInfo removeUser(String username);

第二种方法使用Spring-Data的查询派生机制，从方法名称和参数构建N1QL查询。 这将生成如下所示的查询：。 您可以结合这些标准，甚至可以使用名称进行计数，或者使用名称进行限制，例如...SELECT …​ FROM …​ WHERE firstName = "valueOfFnameAtRuntime"countByFirstnamefindFirst3ByLastname

实际上，生成的 N1QL 查询还将包含一个额外的 N1QL 条件，以便仅选择与存储库的实体类匹配的文档。

支持大多数 Spring-Data 关键字： .@Query （N1QL） 方法名称中支持的关键字

关键词 样本 N1QL WHERE 子句片段

And

findByLastnameAndFirstname

lastName = a AND firstName = b

Or

findByLastnameOrFirstname

lastName = a OR firstName = b

Is,Equals

findByField,findByFieldEquals

field = a

IsNot,Not

findByFieldIsNot

field != a

Between

findByFieldBetween

field BETWEEN a AND b

IsLessThan,LessThan,IsBefore,Before

findByFieldIsLessThan,findByFieldBefore

field < a

IsLessThanEqual,LessThanEqual

findByFieldIsLessThanEqual

field ⇐ a

IsGreaterThan,GreaterThan,IsAfter,After

findByFieldIsGreaterThan,findByFieldAfter

field > a

IsGreaterThanEqual,GreaterThanEqual

findByFieldGreaterThanEqual

field >= a

IsNull

findByFieldIsNull

field IS NULL

IsNotNull,NotNull

findByFieldIsNotNull

field IS NOT NULL

IsLike,Like

findByFieldLike

field LIKE "a"- a 应该是包含 % 和 _ 的字符串（匹配 n 个字符和 1 个字符）

IsNotLike,NotLike

findByFieldNotLike

field NOT LIKE "a"- a 应该是包含 % 和 _ 的字符串（匹配 n 个字符和 1 个字符）

IsStartingWith,StartingWith,StartsWith

findByFieldStartingWith

field LIKE "a%"- a 应该是 String 前缀

IsEndingWith,EndingWith,EndsWith

findByFieldEndingWith

field LIKE "%a"- a 应该是 String 后缀

IsContaining,Containing,Contains

findByFieldContains

field LIKE "%a%"- a 应该是一个字符串

IsNotContaining,NotContaining,NotContains

findByFieldNotContaining

field NOT LIKE "%a%"- a 应该是一个字符串

IsIn,In

findByFieldIn

field IN array- 请注意，下一个参数值（如果是集合/数组，则为其子项）应与存储在JsonArray)

IsNotIn,NotIn

findByFieldNotIn

field NOT IN array- 请注意，下一个参数值（如果是集合/数组，则为其子项）应与存储在JsonArray)

IsTrue,True

findByFieldIsTrue

field = TRUE

IsFalse,False

findByFieldFalse

field = FALSE

MatchesRegex,Matches,Regex

findByFieldMatches

REGEXP_LIKE(field, "a")- 请注意，这里忽略了 ignoreCase，a 是 String 形式的正则表达式

Exists

findByFieldExists

field IS NOT MISSING- 用于验证 JSON 是否包含此属性

OrderBy

findByFieldOrderByLastnameDesc

field = a ORDER BY lastname DESC

IgnoreCase

findByFieldIgnoreCase

LOWER(field) = LOWER("a")- a 必须是 String

您可以通过此方法同时使用计数查询和 [repositories.limit-query-result] 功能。

使用 N1QL，存储库的另一个可能的接口是（扩展 ）。 它添加了两种方法：PagingAndSortingRepositoryCrudRepository

表 2.PagingAndSortingRepository 上公开的方法
方法 描述

Iterable<T> findAll（排序排序）;

允许在对其中一个属性进行排序时检索所有相关实体。

Page<T> findAll（可分页可分页）;

允许在页面中检索实体。返回的内容可以轻松获取下一页以及项目列表。对于第一次调用，请用作 Pageable。PagePageablenew PageRequest(0, pageSize)
您还可以将 和 作为方法返回类型与 N1QL 支持的存储库一起使用。PageSlice
如果将 pageable 和 sort 参数用于内联查询，则内联查询本身不应有任何 order by、limit 或 offset 子句，否则服务器会拒绝格式不正确的查询。

自动索引管理

默认情况下，用户应为其查询创建和管理最佳索引。特别是在开发的早期阶段，自动创建索引以快速启动可以派上用场。

对于 N1QL，提供了以下注释，这些注释需要附加到实体（在类或字段上）：

  • @QueryIndexed：放置在字段上以指示此字段应是索引的一部分

  • @CompositeQueryIndex：放置在类上，以指示应在多个字段（复合）上创建索引。

  • @CompositeQueryIndexes：如果应创建多个注释，则此注释将列出它们。CompositeQueryIndex

例如，以下是在实体上定义复合索引的方式：

例 7.两个字段的复合索引，并按排序
@Document
@CompositeQueryIndex(fields = {"id", "name desc"})
public class Airline {
   @Id
   String id;

	@QueryIndexed
	String name;

	@PersistenceConstructor
	public Airline(String id, String name) {
		this.id = id;
	}

	public String getId() {
		return id;
	}

	public String getName() {
		return name;
	}

}

默认情况下，索引创建处于禁用状态。如果要启用它，则需要在配置上覆盖它：

例 8.启用自动索引创建
@Override
protected boolean autoIndexCreation() {
 return true;
}

一致查询

默认情况下，使用 N1QL 的存储库查询使用扫描一致性。这意味着结果会快速返回，但索引中的数据可能还不包含以前写入的操作的数据（称为最终一致性）。如果需要查询的“准备自己的写入”语义，则需要使用注释。下面是一个示例：NOT_BOUNDED@ScanConsistency

例 9.使用不同的扫描一致性
@Repository
public interface AirportRepository extends PagingAndSortingRepository<Airport, String> {

	@Override
	@ScanConsistency(query = QueryScanConsistency.REQUEST_PLUS)
	Iterable<Airport> findAll();

}

DTO预测

Spring Data Repositories 通常在使用查询方法时返回域模型。 但是，有时，由于各种原因，您可能需要更改该模型的视图。 在本节中，您将学习如何定义投影以提供简化和缩减的资源视图。

请看以下域模型：

@Entity
public class Person {

  @Id @GeneratedValue
  private Long id;
  private String firstName, lastName;

  @OneToOne
  private Address address;
  …
}

@Entity
public class Address {

  @Id @GeneratedValue
  private Long id;
  private String street, state, country;

  …
}

这有几个属性：Person

  • id是主键

  • firstName并且是数据属性lastName

  • address是指向另一个域对象的链接

现在假设我们创建一个相应的存储库，如下所示：

interface PersonRepository extends CrudRepository<Person, Long> {

  Person findPersonByFirstName(String firstName);
}

Spring Data 将返回域对象，包括其所有属性。 有两个选项可用于检索属性。 一种选择是为如下对象定义存储库：addressAddress

interface AddressRepository extends CrudRepository<Address, Long> {}

在这种情况下，using 仍将返回整个对象。 Using 将只返回 .PersonRepositoryPersonAddressRepositoryAddress

但是，如果您根本不想暴露细节怎么办？ 您可以通过定义一个或多个投影来为存储库服务的使用者提供替代方案。address

例 10.简单投影
interface NoAddresses {  (1)

  String getFirstName(); (2)

  String getLastName();  (3)
}

此投影包含以下详细信息：

1 一个普通的 Java 接口，使其具有声明性。
2 导出 .firstName
3 导出 .lastName

投影只有 getter for 和 意味着它不会提供任何地址信息。 在这种情况下，查询方法定义返回，而不是 。NoAddressesfirstNamelastNameNoAdressesPerson

interface PersonRepository extends CrudRepository<Person, Long> {

  NoAddresses findByFirstName(String firstName);
}

投影声明基础类型与与公开属性相关的方法签名之间的协定。 因此，需要根据基础类型的属性名称来命名 getter 方法。 如果基础属性被命名为 ，则必须命名 getter 方法，否则 Spring Data 无法查找源属性。firstNamegetFirstName

我们建议您始终将 SpEL 和 WHERE 子句与 SpEL 一起使用（否则您的查询可能会受到来自其他存储库的实体的影响）。selectEntityfilter
实际上，生成的 N1QL 查询还将包含一个额外的 N1QL 条件，以便仅选择与存储库的实体类匹配的文档。
关键词 样本 N1QL WHERE 子句片段

And

findByLastnameAndFirstname

lastName = a AND firstName = b

Or

findByLastnameOrFirstname

lastName = a OR firstName = b

Is,Equals

findByField,findByFieldEquals

field = a

IsNot,Not

findByFieldIsNot

field != a

Between

findByFieldBetween

field BETWEEN a AND b

IsLessThan,LessThan,IsBefore,Before

findByFieldIsLessThan,findByFieldBefore

field < a

IsLessThanEqual,LessThanEqual

findByFieldIsLessThanEqual

field ⇐ a

IsGreaterThan,GreaterThan,IsAfter,After

findByFieldIsGreaterThan,findByFieldAfter

field > a

IsGreaterThanEqual,GreaterThanEqual

findByFieldGreaterThanEqual

field >= a

IsNull

findByFieldIsNull

field IS NULL

IsNotNull,NotNull

findByFieldIsNotNull

field IS NOT NULL

IsLike,Like

findByFieldLike

field LIKE "a"- a 应该是包含 % 和 _ 的字符串（匹配 n 个字符和 1 个字符）

IsNotLike,NotLike

findByFieldNotLike

field NOT LIKE "a"- a 应该是包含 % 和 _ 的字符串（匹配 n 个字符和 1 个字符）

IsStartingWith,StartingWith,StartsWith

findByFieldStartingWith

field LIKE "a%"- a 应该是 String 前缀

IsEndingWith,EndingWith,EndsWith

findByFieldEndingWith

field LIKE "%a"- a 应该是 String 后缀

IsContaining,Containing,Contains

findByFieldContains

field LIKE "%a%"- a 应该是一个字符串

IsNotContaining,NotContaining,NotContains

findByFieldNotContaining

field NOT LIKE "%a%"- a 应该是一个字符串

IsIn,In

findByFieldIn

field IN array- 请注意，下一个参数值（如果是集合/数组，则为其子项）应与存储在JsonArray)

IsNotIn,NotIn

findByFieldNotIn

field NOT IN array- 请注意，下一个参数值（如果是集合/数组，则为其子项）应与存储在JsonArray)

IsTrue,True

findByFieldIsTrue

field = TRUE

IsFalse,False

findByFieldFalse

field = FALSE

MatchesRegex,Matches,Regex

findByFieldMatches

REGEXP_LIKE(field, "a")- 请注意，这里忽略了 ignoreCase，a 是 String 形式的正则表达式

Exists

findByFieldExists

field IS NOT MISSING- 用于验证 JSON 是否包含此属性

OrderBy

findByFieldOrderByLastnameDesc

field = a ORDER BY lastname DESC

IgnoreCase

findByFieldIgnoreCase

LOWER(field) = LOWER("a")- a 必须是 String
表 2.PagingAndSortingRepository 上公开的方法
方法 描述

Iterable<T> findAll（排序排序）;

允许在对其中一个属性进行排序时检索所有相关实体。

Page<T> findAll（可分页可分页）;

允许在页面中检索实体。返回的内容可以轻松获取下一页以及项目列表。对于第一次调用，请用作 Pageable。PagePageablenew PageRequest(0, pageSize)
您还可以将 和 作为方法返回类型与 N1QL 支持的存储库一起使用。PageSlice
如果将 pageable 和 sort 参数用于内联查询，则内联查询本身不应有任何 order by、limit 或 offset 子句，否则服务器会拒绝格式不正确的查询。
1 一个普通的 Java 接口，使其具有声明性。
2 导出 .firstName
3 导出 .lastName