使用 Cassandra 访问数据 - springboot guide中文文档

本指南将引导您使用 Spring Data Cassandra 构建一个应用程序，该应用程序在 Apache Cassandra 中存储数据并从中检索数据，Apache Cassandra 是一个高性能的分布式数据库。

你将构建什么

您将使用 Spring Data Cassandra 来存储和检索 Apache Cassandra 中的数据。

你需要什么

大约 15 分钟
一个常用的文本编辑器或 IDE
Java 17 或更高版本
Gradle 7.5+ 或 Maven 3.5+
您也可以直接将代码导入到您的 IDE 中：

如何完成本指南

与大多数 Spring 入门指南一样，您可以从头开始并完成每个步骤，也可以跳过您已经熟悉的基本设置步骤。无论哪种方式，您最终都会得到可运行的代码。

要从头开始，请继续阅读使用 Spring Initializr 开始。

要跳过基础部分，请执行以下操作：

下载并解压本指南的源码仓库，或使用 Git 克隆它：git clone https://github.com/spring-guides/gs-accessing-data-cassandra.git
进入 gs-accessing-data-cassandra/initial 目录
跳转到设置数据库。

当您完成后，可以对照 gs-accessing-data-cassandra/complete 中的代码检查您的结果。

从 Spring Initializr 开始

您可以使用这个预初始化项目并点击生成以下载一个 ZIP 文件。该项目已配置为适合本教程中的示例。

要手动初始化项目：

访问 https://start.spring.io。该服务会拉取应用程序所需的所有依赖项，并为您完成大部分设置。
选择 Gradle 或 Maven 以及您想要使用的语言。本指南假设您选择了 Java。
点击 Dependencies 并选择 Spring Data for Apache Cassandra。
点击 Generate。
下载生成的 ZIP 文件，这是一个根据您的选择配置的 Web 应用程序的存档。

如果您的 IDE 集成了 Spring Initializr，您可以直接在 IDE 中完成此过程。

您还可以从 Github 上 fork 该项目，并在您的 IDE 或其他编辑器中打开它。

配置数据库

在构建应用程序之前，您需要设置一个 Cassandra 数据库。Apache Cassandra 是一个开源的 NoSQL 数据存储，针对大型数据集中的快速读写进行了优化。在接下来的小节中，您可以选择使用 DataStax Astra DB Cassandra-as-a-Service 或在本地 Docker 容器中运行它。本指南将介绍如何使用 DataStax Astra Cassandra-as-a-Service 的免费版，以便您可以在几分钟内创建数据并将其存储在 Cassandra 数据库中。

在您的 application.properties 文件（src/main/resources/application.properties）中添加以下属性以配置 Spring Data Cassandra：

spring.cassandra.schema-action=CREATE_IF_NOT_EXISTS
spring.cassandra.request.timeout=10s
spring.cassandra.connection.connect-timeout=10s
spring.cassandra.connection.init-query-timeout=10s

spring.data.cassandra.schema-action 属性定义了启动时要执行的模式操作，可以是 none、create、create-if-not-exists、recreate 或 recreate-drop-unused。我们使用 create-if-not-exists 来创建所需的模式。详情请参阅文档。

在生产环境中将此设置为 none 是一个良好的安全实践，以避免在启动时创建或重新创建数据库。

我们还增加了默认的超时时间，这在首次创建架构或网络连接较慢时可能是必要的。

Astra DB 设置

要使用托管数据库，您可以使用 DataStax Astra DB 的强大免费层级，这是一个 Cassandra 即服务（Cassandra-as-a-Service）解决方案。它在未使用时可以缩放到零。按照以下链接中的说明创建一个数据库和一个名为 spring_cassandra 的密钥库。

Spring Boot Astra starter 会自动引入并配置所有必需的依赖项。要使用 DataStax Astra DB，您需要将其添加到您的 pom.xml 中：

<dependency>
    <groupId>com.datastax.astra</groupId>
    <artifactId>astra-spring-boot-starter</artifactId>
    <version>0.1.13</version>
</dependency>

对于 Gradle，将 implementation 'com.datastax.astra:astra-spring-boot-starter:0.1.13' 添加到您的 build.gradle 文件中。

Astra 自动配置需要配置信息以连接到您的云数据库。您需要：

定义凭证：客户端 ID、客户端密钥和应用程序令牌。
选择您的实例，包括云区域、数据库 ID 和键空间（spring_cassandra）。

然后您需要在 application.properties 文件（src/main/resources/application.properties）中添加这些额外的属性来配置 Astra：

# Credentials to Astra DB
astra.client-id=<CLIENT_ID>
astra.client-secret=<CLIENT_SECRET>
astra.application-token=<APP_TOKEN>

# Select an Astra instance
astra.cloud-region=<DB_REGION>
astra.database-id=<DB_ID>
astra.keyspace=spring_cassandra

Docker 配置

如果您更倾向于在容器化环境中本地运行 Cassandra，请运行以下 docker run 命令：

docker run -p 9042:9042 --rm --name cassandra -d cassandra:4.0.7

在容器创建后，访问 Cassandra 查询语言 shell:

docker exec -it cassandra bash -c "cqlsh -u cassandra -p cassandra"

为应用程序创建一个 keyspace：

CREATE KEYSPACE spring_cassandra WITH replication = {'class' : 'SimpleStrategy', 'replication_factor' : 1};

现在您的数据库已经启动，配置 Spring Data Cassandra 以访问您的数据库。

在您的 application.properties 文件（src/main/resources/application.properties）中添加以下属性以连接到本地数据库：

spring.cassandra.local-datacenter=datacenter1
spring.cassandra.keyspace-name=spring_cassandra

另外，为了方便地使用 Cassandra 及相关 Kubernetes 生态系统项目，您可以在 K8ssandra 上启动一个单节点 Cassandra 集群，大约只需 10 分钟。

创建 Cassandra 实体

在本示例中，您定义了一个 Vet（兽医）实体。以下清单展示了 Vet 类（位于 src/main/java/com/example/accessingdatacassandra/Vet.java 中）：

package com.example.accessingdatacassandra;

import java.util.Set;
import java.util.UUID;

import org.springframework.data.cassandra.core.mapping.PrimaryKey;
import org.springframework.data.cassandra.core.mapping.Table;

@Table
public class Vet {

  @PrimaryKey
  private UUID id;

  private String firstName;

  private String lastName;

  private Set<String> specialties;

  public Vet(UUID id, String firstName, String lastName, Set<String> specialties) {
    this.id = id;
    this.firstName = firstName;
    this.lastName = lastName;
    this.specialties = specialties;
  }

  public UUID getId() {
    return id;
  }

  public void setId(UUID id) {
    this.id = id;
  }

  public String getFirstName() {
    return firstName;
  }

  public void setFirstName(String firstName) {
    this.firstName = firstName;
  }

  public String getLastName() {
    return lastName;
  }

  public void setLastName(String lastName) {
    this.lastName = lastName;
  }

  public Set<String> getSpecialties() {
    return specialties;
  }

  public void setSpecialties(Set<String> specialties) {
    this.specialties = specialties;
  }
}

Vet 类使用 @Table 注解进行标记，这将其映射到 Cassandra 表。每个属性都映射到一个列。

该类使用了一个简单的 UUID 类型的 @PrimaryKey。选择正确的主键至关重要，因为它决定了我们的分区键，并且之后无法更改。

为什么它如此重要？分区键不仅定义了数据的唯一性，还控制着数据的局部性。在插入数据时，主键会被哈希并用于选择存储数据的节点。这样，我们就知道数据总是可以在那个节点上找到。

Cassandra 对数据进行非规范化处理，不像 SQL/RDBMS 那样需要表连接，这使您能够更快地检索数据。因此，我们将 specialties 建模为 Set<String>。

创建简单查询

Spring Data Cassandra 专注于将数据存储在 Apache Cassandra 中。然而，它继承了 Spring Data Commons 项目的功能，包括派生查询的能力。基本上，您不需要学习 Cassandra 的查询语言。相反，您可以编写少量方法，让查询为您自动生成。

要了解这是如何工作的，可以创建一个查询 Vet 实体的仓库接口，如下面的代码清单（位于 src/main/java/com/example/accessingdatacaddandra/VetRepository.java）所示：

package com.example.accessingdatacassandra;

import java.util.UUID;

import org.springframework.data.repository.CrudRepository;

public interface VetRepository extends CrudRepository<Vet, UUID> {  
  Vet findByFirstName(String username);
}

VetRepository 继承了 CassandraRepository 接口，并为存储库操作的值和键的泛型类型参数指定了类型 —— 分别是 Vet 和 UUID。该接口提供了许多操作，包括基本的 CRUD（创建、读取、更新、删除）和简单的查询（例如 findById(..)）数据访问操作。CassandraRepository 没有继承 PagingAndSortingRepository，因为使用 limit 或 offset 的经典分页模式不适用于 Cassandra。

您可以通过声明方法签名来根据需要定义其他查询。但是，您只能执行包含主键的查询。findByFirstName 方法在 Spring Data 中是有效的，但在 Cassandra 中不允许使用，因为 firstName 不是主键的一部分。

仓库中某些生成的方法可能需要进行全表扫描。例如，findAll 方法需要查询集群中的所有节点。对于大数据集，不建议使用此类查询，因为它们可能会影响性能。

添加 CommandLineRunner

定义一个类型为 CommandLineRunner 的 bean，并注入 VetRepository 来设置一些数据并使用其方法。

只要这些仓库包含在您的 @SpringBootApplication 类所在的包（或子包）中，Spring Boot 就会自动处理这些仓库。为了对注册过程有更多控制，您可以使用 @EnableCassandraRepositories 注解。

默认情况下，@EnableCassandraRepositories 会扫描当前包中所有扩展了 Spring Data 存储库接口的接口。如果您的项目布局包含多个项目，并且找不到您的存储库，您可以使用 basePackageClasses=MyRepository.class 来安全地告诉 Spring Data Cassandra 按类型扫描不同的根包。

Spring Data Cassandra 使用 CassandraTemplate 来执行 find* 方法背后的查询。您也可以自行使用该模板来执行更复杂的查询，但本指南不涉及这部分内容。（请参阅 Spring Data Cassandra 参考指南[https://docs.spring.io/spring-data/cassandra/docs/current/reference/html/#reference]）。

以下清单展示了完整的 AccessingDataCassandraApplication 类（位于 /src/main/java/com/example/accessingdatacassandra/AccessingDataCassandraApplication.java）：

package com.example.accessingdatacassandra;

import java.util.Arrays;
import java.util.HashSet;
import java.util.UUID;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.data.cassandra.core.CassandraTemplate;

@SpringBootApplication
public class AccessingDataCassandraApplication {

  private final static Logger log = LoggerFactory.getLogger(AccessingDataCassandraApplication.class);

  public static void main(String[] args) {
    SpringApplication.run(AccessingDataCassandraApplication.class, args);
  }

  @Bean
  public CommandLineRunner clr(VetRepository vetRepository) {
    return args -> {
      vetRepository.deleteAll();

      Vet john = new Vet(UUID.randomUUID(), "John", "Doe", new HashSet<>(Arrays.asList("surgery")));
      Vet jane = new Vet(UUID.randomUUID(), "Jane", "Doe", new HashSet<>(Arrays.asList("radiology, surgery")));

      Vet savedJohn = vetRepository.save(john);
      Vet savedJane = vetRepository.save(jane);

      vetRepository.findAll()
        .forEach(v -> log.info("Vet: {}", v.getFirstName()));

      vetRepository.findById(savedJohn.getId())
        .ifPresent(v -> log.info("Vet by id: {}", v.getFirstName()));
    };
  }
}

构建可执行的 JAR

您可以使用 Gradle 或 Maven 从命令行运行应用程序。您还可以构建一个包含所有必要依赖、类和资源的单一可执行 JAR 文件并运行它。构建可执行 JAR 文件使得在整个开发生命周期中、跨不同环境等场景下，轻松地打包、版本控制和部署服务变得简便。

如果您使用 Gradle，可以通过 ./gradlew bootRun 命令来运行应用程序。或者，您可以使用 ./gradlew build 命令构建 JAR 文件，然后运行该 JAR 文件，如下所示：

java -jar build/libs/gs-accessing-data-cassandra-0.1.0.jar

如果您使用 Maven，可以通过 ./mvnw spring-boot:run 来运行应用程序。或者，您可以使用 ./mvnw clean package 构建 JAR 文件，然后按如下方式运行 JAR 文件：

java -jar target/gs-accessing-data-cassandra-0.1.0.jar

这里描述的步骤会创建一个可运行的 JAR 文件。您也可以构建一个经典的 WAR 文件。

总结

恭喜！您已经开发了一个使用 Spring Data Cassandra 来访问分布式数据的 Spring 应用程序。

另请参阅

以下指南可能也会对您有所帮助：