对于最新的稳定版本，请使用 Spring Data Couchbase 5.4.0！spring-doc.cn

Couchbase 存储库

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

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

请注意，您可以调整查询所需的一致性（请参阅一致查询），并拥有由不同存储桶支持的不同存储库（请参阅 [couchbase.repository.multibucket])spring-doc.cn

配置

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

另请注意，如果您在 Spring Boot 中运行，则 autoconfig 支持已经为您设置了 Comments，因此只有在要覆盖默认值时才需要使用它。spring-doc.cn

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

[couchbase.repository.multibucket] 中介绍了高级用法。spring-doc.cn

QueryDSL 配置

Spring Data Couchbase 支持 QueryDSL 来构建类型安全的查询。要启用代码生成，需要设置为 Annotation 处理器。 此外，运行时需要 querydsl-apt 才能在存储库上启用 QueryDSL。CouchbaseAnnotationProcessorspring-doc.cn

示例 2.Maven 配置示例
    . existing depdendencies including those required for spring-data-couchbase
    .
    .
    <dependency>
        <groupId>com.querydsl</groupId>
        <artifactId>querydsl-apt</artifactId>
        <version>${querydslVersion}</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
                <executions>
                    <execution>
                        <id>annotation-processing</id>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>compile</goal>
                        </goals>
                        <configuration>
                            <proc>only</proc>
                            <annotationProcessors>
                                <annotationProcessor>org.springframework.data.couchbase.repository.support.CouchbaseAnnotationProcessor</annotationProcessor>
                            </annotationProcessors>
                            <generatedTestSourcesDirectory>target/generated-sources</generatedTestSourcesDirectory>
                            <compilerArgs>
                                <arg>-Aquerydsl.logInfo=true</arg>
                            </compilerArgs>
                        </configuration>
                    </execution>
                </executions>
        </plugin>
    </plugins>
</build>
例 3.Gradle 配置示例
dependencies {
    annotationProcessor 'com.querydsl:querydsl-apt:${querydslVersion}'
    annotationProcessor 'org.springframework.data:spring-data-couchbase'
    testAnnotationProcessor 'com.querydsl:querydsl-apt:${querydslVersion}'
    testAnnotationProcessor 'org.springframework.data:spring-data-couchbase'
}
tasks.withType(JavaCompile).configureEach {
    options.compilerArgs += [
            "-processor",
            "org.springframework.data.couchbase.repository.support.CouchbaseAnnotationProcessor"]
}

用法

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

示例 4.一个 UserInfo 仓库
import org.springframework.data.repository.CrudRepository;

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

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

现在，让我们想象我们 to 一个使用它的类。 我们有哪些方法可用？@AutowireUserRepositoryspring-doc.cn

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

UserInfo save（UserInfo 实体）spring-doc.cn

保存给定的实体。spring-doc.cn

Iterable<UserInfo> save（Iterable<UserInfo> 实体）spring-doc.cn

保存实体列表。spring-doc.cn

UserInfo findOne（字符串 ID）spring-doc.cn

按实体的唯一 ID 查找实体。spring-doc.cn

boolean exists（字符串 ID）spring-doc.cn

通过唯一 ID 检查给定实体是否存在。spring-doc.cn

Iterable<UserInfo> findAll（）spring-doc.cn

在存储桶中查找此类型的所有实体。spring-doc.cn

Iterable<UserInfo> findAll（Iterable<String> ids）spring-doc.cn

按此类型和给定的 id 列表查找所有实体。spring-doc.cn

长 count（）spring-doc.cn

计算存储桶中的实体数。spring-doc.cn

无效删除 （字符串 ID）spring-doc.cn

按 ID 删除实体。spring-doc.cn

void delete（UserInfo 实体）spring-doc.cn

删除实体。spring-doc.cn

void delete（Iterable<UserInfo> 实体）spring-doc.cn

删除所有给定的实体。spring-doc.cn

无效 deleteAll（）spring-doc.cn

按类型删除存储桶中的所有实体。spring-doc.cn

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

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

存储库和查询

基于 N1QL 的查询

先决条件是在将存储实体的存储桶上创建 PRIMARY INDEX。spring-doc.cn

下面是一个示例：spring-doc.cn

例 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 支持的查询方式。spring-doc.cn

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

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

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

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

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

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

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

  • #n1ql.delete将替换为 statement 。delete fromspring-doc.cn

  • #n1ql.returning将替换为 return 重建实体所需的子句。spring-doc.cn

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

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

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

例 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 = 3spring-doc.cn

您还可以在 N1QL 查询中执行单个投影（前提是它只选择一个字段并且只返回一个结果，通常是像 ， ， ... 这样的聚合）。 此类投影将具有简单的返回类型，如 、 或 。 这不适用于到 DTO 的投影。COUNTAVGMAXlongbooleanStringspring-doc.cn

再比如：

等价于#{#n1ql.selectEntity} WHERE #{#n1ql.filter} AND test = $1
SELECT #{#n1ql.fields} FROM #{#n1ql.collection} WHERE #{#n1ql.filter} AND test = $1spring-doc.cn

SpEL 与 Spring Security 的实际应用

当您想根据其他 Spring 组件（如 Spring Security）注入的数据进行查询时，SPEL 可能很有用。 以下是扩展 SPEL 上下文以访问此类外部数据所需执行的操作。spring-doc.cn

首先，您需要实现一个 （使用如下 support 类）：EvaluationContextExtensionspring-doc.cn

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：spring-doc.cn

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

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

@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

删除查询示例：spring-doc.cn

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

第二种方法使用 Spring-Data 的查询派生机制从方法名称和参数构建 N1QL 查询。 这将生成如下所示的查询：. 您可以组合这些条件，甚至可以使用类似 name like 的名称进行计数，或者使用 name like ...SELECT …​ FROM …​ WHERE firstName = "valueOfFnameAtRuntime"countByFirstnamefindFirst3ByLastnamespring-doc.cn

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

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

关键词 样本 N1QL WHERE 子句片段

Andspring-doc.cn

findByLastnameAndFirstnamespring-doc.cn

lastName = a AND firstName = bspring-doc.cn

Orspring-doc.cn

findByLastnameOrFirstnamespring-doc.cn

lastName = a OR firstName = bspring-doc.cn

Is,Equalsspring-doc.cn

findByField,findByFieldEqualsspring-doc.cn

field = aspring-doc.cn

IsNot,Notspring-doc.cn

findByFieldIsNotspring-doc.cn

field != aspring-doc.cn

Betweenspring-doc.cn

findByFieldBetweenspring-doc.cn

field BETWEEN a AND bspring-doc.cn

IsLessThan,LessThan,IsBefore,Beforespring-doc.cn

findByFieldIsLessThan,findByFieldBeforespring-doc.cn

field < aspring-doc.cn

IsLessThanEqual,LessThanEqualspring-doc.cn

findByFieldIsLessThanEqualspring-doc.cn

field ⇐ aspring-doc.cn

IsGreaterThan,GreaterThan,IsAfter,Afterspring-doc.cn

findByFieldIsGreaterThan,findByFieldAfterspring-doc.cn

field > aspring-doc.cn

IsGreaterThanEqual,GreaterThanEqualspring-doc.cn

findByFieldGreaterThanEqualspring-doc.cn

field >= aspring-doc.cn

IsNullspring-doc.cn

findByFieldIsNullspring-doc.cn

field IS NULLspring-doc.cn

IsNotNull,NotNullspring-doc.cn

findByFieldIsNotNullspring-doc.cn

field IS NOT NULLspring-doc.cn

IsLike,Likespring-doc.cn

findByFieldLikespring-doc.cn

field LIKE "a"- a 应该是包含 % 和 _ 的 String（匹配 n 和 1 个字符）spring-doc.cn

IsNotLike,NotLikespring-doc.cn

findByFieldNotLikespring-doc.cn

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

IsStartingWith,StartingWith,StartsWithspring-doc.cn

findByFieldStartingWithspring-doc.cn

field LIKE "a%"- a 应该是 String 前缀spring-doc.cn

IsEndingWith,EndingWith,EndsWithspring-doc.cn

findByFieldEndingWithspring-doc.cn

field LIKE "%a"- a 应该是 String 后缀spring-doc.cn

IsContaining,Containing,Containsspring-doc.cn

findByFieldContainsspring-doc.cn

field LIKE "%a%"- a 应该是一个 Stringspring-doc.cn

IsNotContaining,NotContaining,NotContainsspring-doc.cn

findByFieldNotContainingspring-doc.cn

field NOT LIKE "%a%"- a 应该是一个 Stringspring-doc.cn

IsIn,Inspring-doc.cn

findByFieldInspring-doc.cn

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

IsNotIn,NotInspring-doc.cn

findByFieldNotInspring-doc.cn

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

IsTrue,Truespring-doc.cn

findByFieldIsTruespring-doc.cn

field = TRUEspring-doc.cn

IsFalse,Falsespring-doc.cn

findByFieldFalsespring-doc.cn

field = FALSEspring-doc.cn

MatchesRegex,Matches,Regexspring-doc.cn

findByFieldMatchesspring-doc.cn

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

Existsspring-doc.cn

findByFieldExistsspring-doc.cn

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

OrderByspring-doc.cn

findByFieldOrderByLastnameDescspring-doc.cn

field = a ORDER BY lastname DESCspring-doc.cn

IgnoreCasespring-doc.cn

findByFieldIgnoreCasespring-doc.cn

LOWER(field) = LOWER("a")- a 必须是 Stringspring-doc.cn

通过这种方法，您可以同时使用计数查询和 [repositories.limit-query-result] 功能。spring-doc.cn

使用 N1QL 时，存储库的另一个可能接口是 （它扩展了 ）。 它添加了两个方法：PagingAndSortingRepositoryCrudRepositoryspring-doc.cn

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

Iterable<T> findAll（排序排序）;spring-doc.cn

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

Page<T> findAll（可分页可分页）;spring-doc.cn

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

自动索引管理

默认情况下，用户应为其查询创建和管理最佳索引。尤其是在开发的早期阶段，自动创建索引以快速开始会派上用场。spring-doc.cn

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

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

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

  • @CompositeQueryIndexes：如果应创建多个，则此注释将获取它们的列表。CompositeQueryIndexspring-doc.cn

例如，这是在实体上定义组合索引的方式：spring-doc.cn

例 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;
	}

}

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

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

一致性查询

默认情况下，使用 N1QL 的存储库查询使用扫描一致性。这意味着结果会很快返回，但索引中的数据可能还不包含以前编写的操作的数据（称为最终一致性）。如果您需要查询的 “ready your own write” 语义，则需要使用 annotation。下面是一个示例：NOT_BOUNDED@ScanConsistencyspring-doc.cn

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

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

}

DTO 投影

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

请看下面的域模型：spring-doc.cn

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

  …
}

这有几个属性：Personspring-doc.cn

现在假设我们创建相应的存储库，如下所示：spring-doc.cn

interface PersonRepository extends CrudRepository<Person, Long> {

  Person findPersonByFirstName(String firstName);
}

Spring Data 将返回 domain 对象，包括其所有属性。 有两个选项仅用于检索属性。 一种选择是为对象定义存储库，如下所示：addressAddressspring-doc.cn

interface AddressRepository extends CrudRepository<Address, Long> {}

在这种情况下，using 仍将返回整个对象。 using 将仅返回 .PersonRepositoryPersonAddressRepositoryAddressspring-doc.cn

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

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

  String getFirstName(); (2)

  String getLastName();  (3)
}

此投影具有以下详细信息：spring-doc.cn

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

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

interface PersonRepository extends CrudRepository<Person, Long> {

  NoAddresses findByFirstName(String firstName);
}

投影声明基础类型和与公开属性相关的方法签名之间的协定。 因此，需要根据底层类型的属性 name 来命名 getter 方法。 如果基础属性被命名，则必须命名 getter 方法，否则Spring Data无法查找 source 属性。firstNamegetFirstNamespring-doc.cn