安装与配置

ChatGPT-4o-mini 中英对照 Installation & Configuration

本章描述了在使用该库时需要进行的常见安装和配置步骤。

安装

所有用于生产环境的版本都分发到 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>5.4.3</version>
</dependency>

xml

这将引入多个依赖项，包括底层的 Couchbase Java SDK、常见的 Spring 依赖项以及 Jackson 作为 JSON 映射基础设施。

你也可以从 spring snapshot 仓库 （https://repo.spring.io/snapshot）获取快照版本，或者从 spring milestone 仓库 （https://repo.spring.io/milestone）获取里程碑版本。以下是如何使用当前 SNAPSHOT 依赖的示例：

快照配置

示例 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>

xml

覆盖 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>

xml

示例 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>

xml

一旦你在类路径上拥有所有必要的依赖项，就可以开始配置它。仅支持 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";
    }
}

java

连接字符串由一系列主机和一个可选的方案（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()。请注意，这仅映射通过 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 );
}

java