跳到主要内容

使用 Spring 连接 Cassandra

ChatGPT-4o-mini 中英对照 Connecting to Cassandra with Spring

使用 Apache Cassandra 和 Spring 的第一个任务之一是通过使用 Spring IoC 容器创建一个 com.datastax.oss.driver.api.core.CqlSession 对象。您可以通过使用基于 Java 的 bean 元数据或使用基于 XML 的 bean 元数据来实现。这些将在以下部分中讨论。

备注

对于那些不熟悉如何使用基于 Java 的 bean 元数据而非基于 XML 的元数据来配置 Spring 容器的人，可以查看参考文档中的高层次介绍 这里，以及详细的文档 这里。

使用基于 Java 的元数据注册会话实例​

以下示例展示了如何使用基于 Java 的 bean 元数据注册一个 com.datastax.oss.driver.api.core.CqlSession 实例：

示例 1. 使用基于 Java 的 Bean 元数据注册 com.datastax.oss.driver.api.core.CqlSession 对象

@Configuration
public class AppConfig {

	/*
	 * Use the standard Cassandra driver API to create a com.datastax.oss.driver.api.core.CqlSession instance.
	 */
	public @Bean CqlSession session() {
		return CqlSession.builder().withKeyspace("mykeyspace").build();
	}
}
java

这种方法让你可以使用你可能已经熟悉的标准 com.datastax.oss.driver.api.core.CqlSession API。

一种替代方案是通过使用 Spring 的 CqlSessionFactoryBean 将 com.datastax.oss.driver.api.core.CqlSession 的实例注册到容器中。与直接实例化 com.datastax.oss.driver.api.core.CqlSession 实例相比，FactoryBean 方法的额外优点是还为容器提供了一个 ExceptionTranslator 实现，该实现将 Cassandra 异常转换为 Spring 可移植的 DataAccessException 层次结构中的异常。该层次结构及 @Repository 的使用在 Spring 的 DAO 支持特性 中进行了描述。

以下示例展示了基于 Java 的工厂类的使用：

示例 2. 使用 Spring 的 CqlSessionFactoryBean 注册一个 com.datastax.oss.driver.api.core.CqlSession 对象：

@Configuration
public class FactoryBeanAppConfig {

	/*
	 * Factory bean that creates the com.datastax.oss.driver.api.core.CqlSession instance
	 */
	@Bean
	public CqlSessionFactoryBean session() {

		CqlSessionFactoryBean session = new CqlSessionFactoryBean();
		session.setContactPoints("localhost");
		session.setKeyspaceName("mykeyspace");

		return session;
	}
}
java

使用 CassandraTemplate 进行对象映射和仓库支持时，需要 CassandraTemplate、CassandraMappingContext、CassandraConverter，并启用仓库支持。

以下示例展示了如何注册组件以配置对象映射和仓库支持：

示例 3. 注册组件以配置对象映射和仓库支持

@Configuration
@EnableCassandraRepositories(basePackages = { "org.springframework.data.cassandra.example" })
public class CassandraConfig {

	@Bean
	public CqlSessionFactoryBean session() {

		CqlSessionFactoryBean session = new CqlSessionFactoryBean();
		session.setContactPoints("localhost");
		session.setKeyspaceName("mykeyspace");

		return session;
	}

	@Bean
	public SessionFactoryFactoryBean sessionFactory(CqlSession session, CassandraConverter converter) {

		SessionFactoryFactoryBean sessionFactory = new SessionFactoryFactoryBean();
		sessionFactory.setSession(session);
		sessionFactory.setConverter(converter);
		sessionFactory.setSchemaAction(SchemaAction.NONE);

		return sessionFactory;
	}

	@Bean
	public CassandraMappingContext mappingContext() {
		return new CassandraMappingContext();
	}

	@Bean
	public CassandraConverter converter(CqlSession cqlSession, CassandraMappingContext mappingContext) {

		MappingCassandraConverter cassandraConverter = new MappingCassandraConverter(mappingContext);
		cassandraConverter.setUserTypeResolver(new SimpleUserTypeResolver(cqlSession));

		return cassandraConverter;
	}

	@Bean
	public CassandraOperations cassandraTemplate(SessionFactory sessionFactory, CassandraConverter converter) {
		return new CassandraTemplate(sessionFactory, converter);
	}
}
java

创建配置类来注册 Spring Data for Apache Cassandra 组件可能是一项繁重的挑战，因此 Spring Data for Apache Cassandra 提供了一个预构建的配置支持类。继承自 AbstractCassandraConfiguration 的类会注册用于 Spring Data for Apache Cassandra 的 bean。AbstractCassandraConfiguration 允许您提供各种配置选项，例如初始实体、默认查询选项、池化选项、套接字选项等。AbstractCassandraConfiguration 还支持您基于提供的初始实体进行模式生成（如果有提供）。从 AbstractCassandraConfiguration 继承要求您至少通过实现 getKeyspaceName 方法提供 keyspace 名称。以下示例演示了如何通过使用 AbstractCassandraConfiguration 注册 bean：

示例 4. 使用 AbstractCassandraConfiguration 注册 Spring Data for Apache Cassandra beans

@Configuration
public class CassandraConfiguration extends AbstractCassandraConfiguration {

	/*
	 * Provide a contact point to the configuration.
	 */
	@Override
	public String getContactPoints() {
		return "localhost";
	}

	/*
	 * Provide a keyspace name to the configuration.
	 */
	@Override
	public String getKeyspaceName() {
		return "mykeyspace";
	}
}
java

Abstract…Configuration 类会为从应用程序使用 Cassandra 所需的所有 bean 进行配置。该配置假设使用一个单独的 CqlSession，并通过 SessionFactory 将其连接到相关组件，例如 CqlTemplate。如果你想自定义 CqlSession 的创建，你可以提供一个 SessionBuilderConfigurer 函数来定制 CqlSessionBuilder。这对于提供例如 Astra 的 Cloud Connection Bundle 非常有用。

示例 5. 通过 AbstractCassandraConfiguration 连接到 Astra

@Configuration
public class CustomizedCassandraConfiguration extends AbstractCassandraConfiguration {

	/*
	 * Customize the CqlSession through CqlSessionBuilder.
	 */
	@Override
	protected SessionBuilderConfigurer getSessionBuilderConfigurer() {

		Path connectBundlePath = …;

		return builder -> builder
				.withCloudSecureConnectBundle(Path.of(connectBundlePath));
	}

	/*
	 * Provide a keyspace name to the configuration.
	 */
	@Override
	public String getKeyspaceName() {
		return "mykeyspace";
	}

}
java

XML 配置​

本节描述了如何使用 XML 配置 Spring Data Cassandra。

注意

虽然我们仍然支持命名空间配置，但我们通常推荐使用 基于 Java 的配置。

外部化连接属性​

要外部化连接属性，您首先应该创建一个包含连接到 Cassandra 所需信息的属性文件。contactpoints 和 keyspace 是必需的字段。

以下示例显示了我们的属性文件，名为 cassandra.properties：

cassandra.contactpoints=10.1.55.80:9042,10.1.55.81:9042
cassandra.keyspace=showcase
none

在接下来的两个示例中，我们使用 Spring 将这些属性加载到 Spring 上下文中。

使用基于 XML 的元数据注册会话实例​

虽然您可以使用 Spring 的传统 <beans/> XML 命名空间将 com.datastax.oss.driver.api.core.CqlSession 的实例注册到容器中，但 XML 可能会相当冗长，因为它是通用的。XML 命名空间是配置常用对象（例如 CqlSession 实例）的更好替代方案。cassandra 命名空间允许您创建一个 CqlSession 实例。

以下示例展示了如何配置 cassandra 命名空间：

示例 6. 使用 cassandra 命名空间配置 Cassandra 的 XML 架构

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:cassandra="http://www.springframework.org/schema/data/cassandra"
  xsi:schemaLocation="
    http://www.springframework.org/schema/data/cassandra
    https://www.springframework.org/schema/data/cassandra/spring-cassandra.xsd
    http://www.springframework.org/schema/beans
    https://www.springframework.org/schema/beans/spring-beans.xsd">

  <!-- Default bean name is 'cassandraSession' -->
  <cassandra:session contact-points="localhost" port="9042">
    <cassandra:keyspace action="CREATE_DROP" name="mykeyspace" />
  </cassandra:session>

  <cassandra:session-factory>
    <cassandra:script
            location="classpath:/org/springframework/data/cassandra/config/schema.cql"/>
  </cassandra:session-factory>
</beans>
xml

下面显示了更高级 Cassandra 配置的 XML 配置元素。这些元素都使用默认的 bean 名称，以保持配置代码的简洁和可读。

虽然前面的示例展示了如何轻松配置 Spring 以连接到 Cassandra，但还有许多其他选项。基本上，任何在 DataStax Java Driver 中可用的选项在 Spring Data for Apache Cassandra 配置中也都可用。这包括但不限于身份验证、负载均衡策略、重试策略和连接池选项。所有 Spring Data for Apache Cassandra 的方法名称和 XML 元素都与驱动程序上的配置选项命名完全相同（或尽可能接近），因此映射任何现有的驱动程序配置应该是直接的。以下示例展示了如何通过使用 XML 配置 Spring Data 组件。

示例 7. 使用 XML 配置 Spring Data 组件

<!-- Loads the properties into the Spring Context and uses them to fill
in placeholders in the bean definitions -->
<context:property-placeholder location="classpath:cassandra.properties" />

<!-- REQUIRED: The Cassandra Session -->
<cassandra:session contact-points="${cassandra.contactpoints}" keyspace-name="${cassandra.keyspace}" />

<!-- REQUIRED: The default Cassandra mapping context used by `CassandraConverter` -->
<cassandra:mapping>
  <cassandra:user-type-resolver keyspace-name="${cassandra.keyspace}" />
</cassandra:mapping>

<!-- REQUIRED: The default Cassandra converter used by `CassandraTemplate` -->
<cassandra:converter />

<!-- REQUIRED: The Cassandra template is the foundation of all Spring
Data Cassandra -->
<cassandra:template id="cassandraTemplate" />

<!-- OPTIONAL: If you use Spring Data for Apache Cassandra repositories, add
your base packages to scan here -->
<cassandra:repositories base-package="org.spring.cassandra.example.repo" />
xml