对于最新的稳定版本,请使用 Spring Data Couchbase 5.3.1! |
对于最新的稳定版本,请使用 Spring Data Couchbase 5.3.1! |
Spring Data 存储库抽象的目标是显著减少为各种持久性存储实现数据访问层所需的样板代码量。
默认情况下,如果操作是单文档操作且 ID 已知,则操作由 Key/Value 提供支持。 对于所有其他操作,默认情况下会生成 N1QL 查询,因此必须为高性能数据访问创建适当的索引。
请注意,您可以调整查询所需的一致性(请参阅使用一致性进行查询),并具有由不同存储桶支持的不同存储库(请参阅 [couchbase.repository.multibucket])
配置
虽然始终存在对存储库的支持,但您需要在一般情况下或为特定命名空间启用它们。
如果扩展 ,只需使用注释即可。
它提供了许多可能的选项来缩小或自定义搜索路径,最常见的选项之一是 .AbstractCouchbaseConfiguration
@EnableCouchbaseRepositories
basePackages
另请注意,如果您在 spring boot 中运行,autoconfig 支持已经为您设置了注解,因此您只需要在要覆盖默认值时使用它。
@Configuration
@EnableCouchbaseRepositories(basePackages = {"com.couchbase.example.repos"})
public class Config extends AbstractCouchbaseConfiguration {
//...
}
[couchbase.repository.multibucket] 中描述了高级用法。
QueryDSL 配置
Spring Data Couchbase 支持 QueryDSL 来构建类型安全查询。要启用代码生成,您需要在项目上设置为注释处理器。spring-data-couchbase
<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>
annotationProcessor 'com.querydsl:querydsl-apt:${querydslVersion}'
annotationProcessor 'org.springframework.data:spring-data-couchbase:${springDataCouchbaseVersion}'
用法
在最简单的情况下,您的存储库将扩展 ,其中 T 是要公开的实体。
让我们看一下 UserInfo 的存储库:CrudRepository<T, String>
import org.springframework.data.repository.CrudRepository;
public interface UserRepository extends CrudRepository<UserInfo, String> {
}
请注意,这只是一个接口,而不是一个实际的类。 在后台,当您的上下文被初始化时,将创建存储库描述的实际实现,您可以通过常规 Bean 访问它们。 这意味着您将节省大量样板代码,同时仍将完整的 CRUD 语义暴露给您的服务层和应用程序。
现在,让我们想象一下,我们是一个使用它的类。
我们有什么可用的方法?@Autowire
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 功能。
虽然公开的方法为您提供了各种各样的访问模式,但通常需要定义自定义模式。 您可以通过向接口添加方法声明来做到这一点,这些声明将在后台自动解析为请求,我们将在下一节中看到。
方法 | 描述 |
---|---|
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。
下面是一个示例:
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 一起使用(否则您的查询可能会受到来自其他存储库的实体的影响)。selectEntity filter |
基于字符串的查询支持参数化查询。
您可以使用位置占位符,如“$1”,在这种情况下,每个方法参数将按顺序映射到 、 、 ...或者,您可以使用“$someString”语法使用命名占位符。
方法参数将使用参数名称与其相应的占位符匹配,可以通过用 (例如) 注释每个参数(或除外)来覆盖该占位符。
您不能在查询中混合使用这两种方法,如果这样做,则会得到一个。$1
$2
$3
Pageable
Sort
@Param
@Param("someString")
IllegalArgumentException
请注意,您可以混合使用 N1QL 占位符和 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 的预测。COUNT
AVG
MAX
long
boolean
String
另一个例子:
相当于#{#n1ql.selectEntity} WHERE #{#n1ql.filter} AND test = $1
SELECT #{#n1ql.fields} FROM #{#n1ql.collection} WHERE #{#n1ql.filter} AND test = $1
第二种方法使用Spring-Data的查询派生机制,从方法名称和参数构建N1QL查询。
这将生成如下所示的查询:。
您可以结合这些标准,甚至可以使用名称进行计数,或者使用名称进行限制,例如...SELECT … FROM … WHERE firstName = "valueOfFnameAtRuntime"
countByFirstname
findFirst3ByLastname
实际上,生成的 N1QL 查询还将包含一个额外的 N1QL 条件,以便仅选择与存储库的实体类匹配的文档。 |
支持大多数 Spring-Data 关键字: .@Query (N1QL) 方法名称中支持的关键字
关键词 | 样本 | N1QL WHERE 子句片段 |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
您可以通过此方法同时使用计数查询和 [repositories.limit-query-result] 功能。
使用 N1QL,存储库的另一个可能的接口是(扩展 )。
它添加了两种方法:PagingAndSortingRepository
CrudRepository
方法 | 描述 |
---|---|
Iterable<T> findAll(排序排序); |
允许在对其中一个属性进行排序时检索所有相关实体。 |
Page<T> findAll(可分页可分页); |
允许在页面中检索实体。返回的内容可以轻松获取下一页以及项目列表。对于第一次调用,请用作 Pageable。 |
您还可以将 和 作为方法返回类型与 N1QL 支持的存储库一起使用。Page Slice |
如果将 pageable 和 sort 参数用于内联查询,则内联查询本身不应有任何 order by、limit 或 offset 子句,否则服务器会拒绝格式不正确的查询。 |
自动索引管理
默认情况下,用户应为其查询创建和管理最佳索引。特别是在开发的早期阶段,自动创建索引以快速启动可以派上用场。
对于 N1QL,提供了以下注释,这些注释需要附加到实体(在类或字段上):
-
@QueryIndexed
:放置在字段上以指示此字段应是索引的一部分 -
@CompositeQueryIndex
:放置在类上,以指示应在多个字段(复合)上创建索引。 -
@CompositeQueryIndexes
:如果应创建多个注释,则此注释将列出它们。CompositeQueryIndex
例如,以下是在实体上定义复合索引的方式:
@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;
}
}
默认情况下,索引创建处于禁用状态。如果要启用它,则需要在配置上覆盖它:
@Override
protected boolean autoIndexCreation() {
return true;
}
一致查询
默认情况下,使用 N1QL 的存储库查询使用扫描一致性。这意味着结果会快速返回,但索引中的数据可能还不包含以前写入的操作的数据(称为最终一致性)。如果需要查询的“准备自己的写入”语义,则需要使用注释。下面是一个示例:NOT_BOUNDED
@ScanConsistency
@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 将返回域对象,包括其所有属性。
有两个选项可用于检索属性。
一种选择是为如下对象定义存储库:address
Address
interface AddressRepository extends CrudRepository<Address, Long> {}
在这种情况下,using 仍将返回整个对象。
Using 将只返回 .PersonRepository
Person
AddressRepository
Address
但是,如果您根本不想暴露细节怎么办?
您可以通过定义一个或多个投影来为存储库服务的使用者提供替代方案。address
interface NoAddresses { (1)
String getFirstName(); (2)
String getLastName(); (3)
}
此投影包含以下详细信息:
1 | 一个普通的 Java 接口,使其具有声明性。 |
2 | 导出 .firstName |
3 | 导出 .lastName |
投影只有 getter for 和 意味着它不会提供任何地址信息。
在这种情况下,查询方法定义返回,而不是 。NoAddresses
firstName
lastName
NoAdresses
Person
interface PersonRepository extends CrudRepository<Person, Long> {
NoAddresses findByFirstName(String firstName);
}
投影声明基础类型与与公开属性相关的方法签名之间的协定。
因此,需要根据基础类型的属性名称来命名 getter 方法。
如果基础属性被命名为 ,则必须命名 getter 方法,否则 Spring Data 无法查找源属性。firstName
getFirstName
我们建议您始终将 SpEL 和 WHERE 子句与 SpEL 一起使用(否则您的查询可能会受到来自其他存储库的实体的影响)。selectEntity filter |
实际上,生成的 N1QL 查询还将包含一个额外的 N1QL 条件,以便仅选择与存储库的实体类匹配的文档。 |
关键词 | 样本 | N1QL WHERE 子句片段 |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
方法 | 描述 |
---|---|
Iterable<T> findAll(排序排序); |
允许在对其中一个属性进行排序时检索所有相关实体。 |
Page<T> findAll(可分页可分页); |
允许在页面中检索实体。返回的内容可以轻松获取下一页以及项目列表。对于第一次调用,请用作 Pageable。 |
您还可以将 和 作为方法返回类型与 N1QL 支持的存储库一起使用。Page Slice |
如果将 pageable 和 sort 参数用于内联查询,则内联查询本身不应有任何 order by、limit 或 offset 子句,否则服务器会拒绝格式不正确的查询。 |
1 | 一个普通的 Java 接口,使其具有声明性。 |
2 | 导出 .firstName |
3 | 导出 .lastName |