Installation & Configuration

本章介绍使用该库时所需要的常见安装和配置步骤。

Installation

所有用于生产的版本在 Maven Central 和 Spring 发布仓库中都有分布。最终，该库可以像任何其他 maven 依赖项一样包含其中：

Configuration

Example 1. Including the dependency through maven
<dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-couchbase</artifactId>
    <version>{version}</version>
</dependency>

这将拉进多个依赖项，包括底层的 Couchbase Java SDK、Spring 常见依赖项以及用作 JSON 映射基础架构的 Jackson。

你还可以从 spring snapshot repository ([role="bare"]https://repo.spring.io/snapshot) 获取快照，从 spring milestone repository ([role="bare"]https://repo.spring.io/milestone) 获取里程碑版本。以下示例演示如何使用当前 SNAPSHOT 依赖项：

Snapshot Configuration

Example 2. Using a snapshot version
<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 中覆盖依赖项，如下所示：

Example 3. If Using the spring-data-couchbase Dependency Directly
<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>
Example 4. If Using the spring-data-starter-couchbase Dependency (from Spring Initialzr)
<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 配置）。

Annotation-based Configuration ("JavaConfig")

要开始配置，您所需要做的就是对 AbstractCouchbaseConfiguration 进行子类化并实现抽象方法。

Example 5. Extending the 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 正在连接到数据库。如果报告了任何错误，请确保给定凭据和主机信息正确无误。

Configuring Multiple Buckets

要利用多存储桶存储库，请在您的配置类中实现以下方法。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 );
}