Installation & Configuration
本章介绍使用该库时所需要的常见安装和配置步骤。
This chapter describes the common installation and configuration steps needed when working with the library.
Installation
所有用于生产的版本在 Maven Central 和 Spring 发布仓库中都有分布。最终，该库可以像任何其他 maven 依赖项一样包含其中：
All versions intended for production use are distributed across Maven Central and the Spring release repository. As a result, the library can be included like any other maven dependency:
Configuration
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-couchbase</artifactId>
<version>{version}</version>
</dependency>这将拉进多个依赖项，包括底层的 Couchbase Java SDK、Spring 常见依赖项以及用作 JSON 映射基础架构的 Jackson。
This will pull in several dependencies, including the underlying Couchbase Java SDK, common Spring dependencies and also Jackson as the JSON mapping infrastructure.
你还可以从 spring snapshot repository ([role="bare"]https://repo.spring.io/snapshot) 获取快照，从 spring milestone repository ([role="bare"]https://repo.spring.io/milestone) 获取里程碑版本。以下示例演示如何使用当前 SNAPSHOT 依赖项：
You can also grab snapshots from the spring snapshot repository ( https://repo.spring.io/snapshot ) and milestone releases from the spring milestone repository ( https://repo.spring.io/milestone ). Here is an example on how to use the current SNAPSHOT dependency:
Snapshot Configuration
<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>Overriding the Couchbase SDK Version
某些用户可能希望使用与 Spring Data Couchbase 版本中引用的版本不同的 Couchbase Java SDK 版本，目的是获取错误和漏洞修复。由于 Couchbase Java SDK 次要版本向后兼容，因此此 Spring Data Couchbase 版本与任何高于发布依赖项中指定的版本的新版 Couchbase Java SDK 3.x 版本兼容并受其支持。要更改 Spring Data Couchbase 使用的 Couchbase Java SDK 版本，只需在应用程序 pom.xml 中覆盖依赖项，如下所示：
Some users may wish to use a Couchbase Java SDK version different from the one referenced in a Spring Data Couchbase release for the purpose of obtaining bug and vulnerability fixes. Since Couchbase Java SDK minor version releases are backwards compatible, this version of Spring Data Couchbase is compatible and supported with any 3.x version of the Couchbase Java SDK newer than the one specified in the release dependencies. To change the Couchbase Java SDK version used by Spring Data Couchbase, simply override the dependency in the application pom.xml as follows:
<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><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>将所有需要的依赖项放在类路径上后，即可开始对其进行配置。仅支持 Java 配置（在 4.0 中已删除 XML 配置）。
Once you have all needed dependencies on the classpath, you can start configuring it. Only Java config is supported (XML config has been removed in 4.0).
Annotation-based Configuration ("JavaConfig")
要开始配置，您所需要做的就是对 AbstractCouchbaseConfiguration 进行子类化并实现抽象方法。
To get started, all you need to do is subclass the AbstractCouchbaseConfiguration and implement the abstract methods.
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 将自动从群集中挑选所有节点，但您提供的唯一节点在应用程序启动时可能会遇到问题。
The connection string is made up of a list of hosts and an optional scheme (couchbase://) as shown in the code above.
All you need to provide is a list of Couchbase nodes to bootstrap into (separated by a ,). Please note that while one
host is sufficient in development, it is recommended to add 3 to 5 bootstrap nodes here. Couchbase will pick up all nodes
from the cluster automatically, but it could be the case that the only node you’ve provided is experiencing issues while
you are starting the application.
userName 和 password 通过 RBAC（基于角色的访问控制）在您的 Couchbase Server 群集中配置。bucketName 反映了您想用于此配置的存储桶。
The userName and password are configured in your Couchbase Server cluster through RBAC (role-based access control).
The bucketName reflects the bucket you want to use for this configuration.
此外，可以通过覆盖 configureEnvironment 方法来调整 SDK 环境，该方法获取一个 ClusterEnvironment.Builder 来返回一个配置的 ClusterEnvironment。
Additionally, the SDK environment can be tuned by overriding the configureEnvironment method which takes a
ClusterEnvironment.Builder to return a configured ClusterEnvironment.
可以通过此配置作为自定义 Bean 来自定义和覆盖更多内容（例如，存储库、验证和自定义转换器）。
Many more things can be customized and overridden as custom beans from this configuration (for example repositories, validation and custom converters).
|
如果你使用 |
|
If you use |
如果您启动您的应用程序，则应该看到日志中带有 Couchbase INFO 级别的日志，表明底层的 Couchbase Java SDK 正在连接到数据库。如果报告了任何错误，请确保给定凭据和主机信息正确无误。
If you start your application, you should see Couchbase INFO level logging in the logs, indicating that the underlying Couchbase Java SDK is connecting to the database.If any errors are reported, make sure that the given credentials and host information are correct.
Configuring Multiple Buckets
要利用多存储桶存储库，请在您的配置类中实现以下方法。config*OperationsMapping 方法配置了实体-对象到存储桶的映射。在使用下列方法名称时要小心 - 使用作为 Bean 的方法名称将导致使用该 Bean 的值，而不是方法的结果。
To leverage multi-bucket repositories, implement the methods below in your Config class. The config*OperationsMapping methods configure the mapping of entity-objects to buckets. Be careful with the method names - using a method name that is a Bean will result in the value of that bean being used instead of the result of the method.
此示例将 Person → protected、User → mybucket 进行映射，而其他所有内容都将作为 getBucketName()。请注意，这仅对通过存储库进行的调用进行映射。
This example maps Person → protected, User → mybucket, and everything else goes to getBucketName(). Note that this only maps calls through the Repository.
@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 );
}