安装与配置
本章介绍使用该库时所需的常见安装与配置步骤。
安装
所有用于生产环境的版本都发布在 Maven Central 和 Spring 发布仓库中。因此,可以像引入任何其他 maven 依赖一样引入该库:
兼容性
获得正确依赖最简单的方式是用 spring initializr 创建项目。父级 Spring Boot Starter 制品已包含所需依赖,无需再显式指定。
Spring Boot 版本兼容性
-
Spring Boot 3.4.* 使用 Spring Data Couchbase 5.4.*。
-
Spring Boot 3.3.* 使用 Spring Data Couchbase 5.3.*。
-
Spring Boot 3.2.* 使用 Spring Data Couchbase 5.2.*。
Couchbase Java SDK 兼容性
-
Spring Data Couchbase 5.4.* 依赖 Couchbase Java SDK 3.7.*
-
Spring Data Couchbase 5.3.* 依赖 Couchbase Java SDK 3.6.*
-
Spring Data Couchbase 5.2.* 依赖 Couchbase Java SDK 3.3.*
配置
示例 1. 通过 maven 引入依赖
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-couchbase</artifactId>
<version>6.1.1</version>
</dependency>
这会引入多个依赖,包括底层的 Couchbase Java SDK、常见的 Spring 依赖,以及作为 JSON 映射基础设施的 Jackson。
快照配置
示例 2. 使用快照版本
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-couchbase</artifactId>
<version>${version}-SNAPSHOT</version>
</dependency>
<repository>
<id>spring-snapshot</id>
<name>Spring Snapshot Repository</name>
<url>https://repo.spring.io/snapshot</url>
</repository>
覆盖 Couchbase SDK 版本
有些用户可能希望使用与某个 Spring Data Couchbase 发布版所引用版本不同的 Couchbase Java SDK 版本,以获得缺陷修复和漏洞修复。由于 Couchbase Java SDK 的小版本发布是向后兼容的,本版本 Spring Data Couchbase 兼容并支持比发布依赖中所指定版本更新的任何 3.x 版 Couchbase Java SDK。要更改 Spring Data Couchbase 使用的 Couchbase Java SDK 版本,只需在应用的 pom.xml 中按如下方式覆盖该依赖:
示例 3. 直接使用 spring-data-couchbase 依赖时
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-couchbase</artifactId>
<version>${version}</version>
<exclusions> <!-- exclude Couchbase Java SDK -->
<exclusion>
<groupId>com.couchbase.client</groupId>
<artifactId>java-client</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency> <!-- add dependency for specific Couchbase Java SDK version -->
<groupId>com.couchbase.client</groupId>
<artifactId>java-client</artifactId>
<version>3.4.7</version>
</dependency>
示例 4. 使用 spring-data-starter-couchbase 依赖时(来自 Spring Initializr)
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>x.y.z</version>
<relativePath/>
</parent>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-couchbase</artifactId>
<exclusions> <!-- exclude Couchbase Java SDK -->
<exclusion>
<groupId>com.couchbase.client</groupId>
<artifactId>java-client</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency> <!-- add dependency for specific Couchbase Java SDK version -->
<groupId>com.couchbase.client</groupId>
<artifactId>java-client</artifactId>
<version>3.4.7</version>
</dependency>
将所有所需依赖加入 classpath 后,即可开始配置。仅支持 Java 配置(XML 配置已在 4.0 中移除)。
基于注解的配置("JavaConfig")
要开始使用,您只需继承 AbstractCouchbaseConfiguration 并实现其中的抽象方法。
示例 5. 扩展 AbstractCouchbaseConfiguration
@Configuration
public class Config extends AbstractCouchbaseConfiguration {
@Override
public String getConnectionString() {
return "couchbase://127.0.0.1";
}
@Override
public String getUserName() {
return "Administrator";
}
@Override
public String getPassword() {
return "password";
}
@Override
public String getBucketName() {
return "travel-sample";
}
}
如上面代码所示,连接字符串由一组主机和一个可选的方案(couchbase://)组成。您只需提供一组用于引导的 Couchbase 节点(以 , 分隔)。请注意,虽然在开发环境中一个主机就足够了,但建议在此处添加 3 到 5 个引导节点。Couchbase 会自动从集群中发现所有节点,但有可能在您启动应用时,您提供的唯一一个节点正好出现问题。
userName 和 password 是通过 RBAC(基于角色的访问控制)在您的 Couchbase Server 集群中配置的。bucketName 表示您想在此配置中使用的桶。
此外,还可以通过覆盖 configureEnvironment 方法来调整 SDK 环境,该方法接收一个 ClusterEnvironment.Builder 并返回一个配置好的 ClusterEnvironment。
还有许多内容可以通过此配置自定义并覆盖为自定义 Bean(例如仓库、校验和自定义转换器)。
如果您使用 SyncGateway 和 CouchbaseMobile,可能会遇到以 _ 为前缀的字段问题。由于 Spring Data Couchbase 默认将类型信息存储为 _class 属性,这可能会引发问题。覆盖 typeKey()(例如返回 MappingCouchbaseConverter.TYPEKEY_SYNCGATEWAY_COMPATIBLE)即可更改该属性的名称。
启动应用后,您应该能在日志中看到 Couchbase 的 INFO 级别日志,表明底层 Couchbase Java SDK 正在连接数据库。如果报告了任何错误,请确认所提供的凭据和主机信息是否正确。
配置多个桶
要利用多桶仓库,请在您的 Config 类中实现以下方法。config*OperationsMapping 方法用于配置实体对象到桶的映射。请小心方法名——使用一个与 Bean 同名的方法名,会导致使用该 Bean 的值而不是方法的返回结果。
本示例将 Person 映射到 protected、User 映射到 mybucket,其余全部进入 getBucketName()。请注意,这仅映射通过仓库发起的调用。
@Override
public void configureReactiveRepositoryOperationsMapping(ReactiveRepositoryOperationsMapping baseMapping) {
try {
ReactiveCouchbaseTemplate personTemplate = myReactiveCouchbaseTemplate(myCouchbaseClientFactory("protected"),new MappingCouchbaseConverter());
baseMapping.mapEntity(Person.class, personTemplate); // Person goes in "protected" bucket
ReactiveCouchbaseTemplate userTemplate = myReactiveCouchbaseTemplate(myCouchbaseClientFactory("mybucket"),new MappingCouchbaseConverter());
baseMapping.mapEntity(User.class, userTemplate); // User goes in "mybucket"
// everything else goes in getBucketName()
} catch (Exception e) {
throw e;
}
}
@Override
public void configureRepositoryOperationsMapping(RepositoryOperationsMapping baseMapping) {
try {
CouchbaseTemplate personTemplate = myCouchbaseTemplate(myCouchbaseClientFactory("protected"),new MappingCouchbaseConverter());
baseMapping.mapEntity(Person.class, personTemplate); // Person goes in "protected" bucket
CouchbaseTemplate userTemplate = myCouchbaseTemplate(myCouchbaseClientFactory("mybucket"),new MappingCouchbaseConverter());
baseMapping.mapEntity(User.class, userTemplate); // User goes in "mybucket"
// everything else goes in getBucketName()
} catch (Exception e) {
throw e;
}
}
// do not use reactiveCouchbaseTemplate for the name of this method, otherwise the value of that bean
// will be used instead of the result of this call (the client factory arg is different)
public ReactiveCouchbaseTemplate myReactiveCouchbaseTemplate(CouchbaseClientFactory couchbaseClientFactory,
MappingCouchbaseConverter mappingCouchbaseConverter) {
return new ReactiveCouchbaseTemplate(couchbaseClientFactory, mappingCouchbaseConverter);
}
// do not use couchbaseTemplate for the name of this method, otherwise the value of that been
// will be used instead of the result from this call (the client factory arg is different)
public CouchbaseTemplate myCouchbaseTemplate(CouchbaseClientFactory couchbaseClientFactory,
MappingCouchbaseConverter mappingCouchbaseConverter) {
return new CouchbaseTemplate(couchbaseClientFactory, mappingCouchbaseConverter);
}
// do not use couchbaseClientFactory for the name of this method, otherwise the value of that bean will
// will be used instead of this call being made ( bucketname is an arg here, instead of using bucketName() )
public CouchbaseClientFactory myCouchbaseClientFactory(String bucketName) {
return new SimpleCouchbaseClientFactory(getConnectionString(),authenticator(), bucketName );
}