从 2.x 迁移到 3.x 指南

Spring Data for Apache Cassandra 3.0 在从早期版本升级时引入了一系列重大变更。

查看依赖项

升级到 Spring Data Cassandra 需要升级到 DataStax Driver 4 版本。升级到新驱动程序会带来传递性依赖项变更，最值得注意的是，Google Guava 被驱动程序捆绑和混淆（shaded）。请查阅 DataStax Java Driver for Apache Cassandra 4 升级指南 以了解驱动程序相关变更的详细信息。

调整配置

DataStax Java Driver 4 将 Cluster 和 Session 对象合并为一个 CqlSession 对象，因此所有 Cluster 相关的 API 都已被移除。配置在很大程度上被修订，移除了大多数配置项，这些配置项已移至主要基于文件的 DriverConfigLoader 中。这意味着 SocketOptions、AddressTranslator 和更多其他选项现在通过其他方式进行配置。

如果您正在使用基于 XML 的配置，请确保将所有配置文件从 cql 命名空间（www.springframework.org/schema/cql www.springframework.org/schema/cql/spring-cql.xsd）迁移到 cassandra 命名空间（www.springframework.org/schema/data/cassandra www.springframework.org/schema/data/cassandra/spring-cassandra.xsd）。

为了反映配置构建器中的变化，ClusterBuilderConfigurer 已重命名为 SessionBuilderConfigurer，现在接受 CqlSessionBuilder 而不是 Cluster.Builder。请确保也在您的配置中提供本地数据中心，因为这是正确配置负载均衡所必需的。

连接性

Cluster (cassandra:cluster) 和 Session (cassandra:session) 的配置元素已合并为一个 CqlSession (cassandra:session) 元素，该元素同时配置 keyspace 和 endpoints。

随着升级，schema 支持已移至一个新的命名空间元素：cassandra:session-factory，它提供了一个 SessionFactory bean。

示例 1. 版本 2 中的 Cluster、Session 和 Schema 配置
<cassandra:cluster contact-points="localhost" port="9042">
  <cassandra:keyspace action="CREATE_DROP" name="mykeyspace" />
</cassandra:cluster>

<cassandra:session keyspace-name="mykeyspace" schema-action="CREATE">
  <cassandra:startup-cql>CREATE TABLE …</cassandra:startup-cql>
</cassandra:session>
示例 2. 版本 3 中的 Session 和 Schema 配置
<cassandra:session contact-points="localhost" port="9042" keyspace="mykeyspace" local-datacenter="datacenter1">
  <cassandra:keyspace action="CREATE_DROP" name="mykeyspace" />
</cassandra:session>

<cassandra:session-factory schema-action="CREATE">
  <cassandra:script location="classpath:/schema.cql"/>
</cassandra:session-factory>
Spring Data Cassandra 3.0 在使用 XML 命名空间配置时不再注册默认的 Mapping Context、Context 和 Template API bean。默认设置应在应用程序或 Spring Boot 层面应用。

Template API

如果您的应用程序主要与映射实体或 Java 基本类型交互，Spring Data for Apache Cassandra 会将驱动程序升级带来的大多数变化封装在 Template API 和 repository 支持中。

我们通常建议使用 SessionFactory 来创建 CqlTemplate 和 CassandraTemplate 对象，因为工厂的使用允许 schema 创建的同步，并在使用多个数据库时引入了一定程度的灵活性。

示例 3. 版本 2 中的 Template API 配置
<cql:template session-ref="…" />

<cassandra:template session-ref="…" cassandra-converter-ref="…"/>
示例 4. 版本 3 中的 Template API 配置
<cassandra:session-factory />

<cassandra:cql-template session-factory-ref="…" />

<cassandra:template session-factory-ref="…" cassandra-converter-ref="…"/>

您必须在所有直接使用 DataStax 驱动程序 API 的地方调整代码。典型情况包括

  • ResultSetExtractor 的实现

  • RowCallbackHandler 的实现

  • RowMapper 的实现

  • PreparedStatementCreator 的实现，包括异步和响应式变体

  • 调用 CqlTemplate.queryForResultSet(…)

  • 调用接受 Statement 的方法

AsyncCqlTemplate 中的变化

DataStax driver 4 改变了异步运行查询的结果类型。为了反映这些变化，您需要调整提供以下功能的代码

  • AsyncSessionCallback 的实现

  • AsyncPreparedStatementCreator 的实现

结果集提取需要 DataStax 的 AsyncResultSet 的新接口。AsyncCqlTemplate 现在在使用之前使用 ResultSetExtractor 的地方使用 AsyncResultSetExtractor。请注意，AsyncResultSetExtractor.extractData(…) 返回一个 Future 而不是标量对象，因此代码迁移带来了在提取器中使用完全非阻塞代码的可能性。

数据模型迁移

如果您使用以下特性，您的数据模型可能需要更新

  • @CassandraType

  • forceQuote 在 @Table, @Column, @PrimaryKeyColumn, @PrimaryKey 和 @UserDefinedType 中

  • 使用 java.lang.Date 的属性

  • 使用 UDTValue 或 TupleValue 的属性

@CassandraType

DataStax driver 4 不再附带用于描述 Cassandra 类型的 Name 枚举。我们决定通过 CassandraType.Name 重新引入该枚举。请确保更新您的导入以使用新引入的替代类型。

Force Quote

此标志现已弃用，我们建议不再使用它。Spring Data for Apache Cassandra 内部使用驱动程序的 CqlIdentifier，它确保在需要的地方进行引用（quoting）。

属性类型

DataStax driver 4 不再使用 java.lang.Date。请升级您的数据模型以使用 java.time.LocalDateTime。请也将原始 UDT 和 tuple 类型迁移到新的驱动程序类型 UdtValue 和 TupleValue。

其他变化

  • 驱动程序的 ConsistencyLevel 常量类已被移除，并作为 DefaultConsistencyLevel 重新引入。@Consistency 已适配 DefaultConsistencyLevel。

  • QueryOptions 和 …CqlTemplate 类型上的 RetryPolicy 已被移除，没有替代。

  • 驱动程序的 PagingState 类型已被移除。分页状态现在使用 ByteBuffer。

  • SimpleUserTypeResolver 现在接受 CqlSession 而不是 Cluster。

  • SimpleTupleTypeFactory 已迁移到 enum。SimpleTupleTypeFactory.INSTANCE 不再需要 Cluster/CqlSession 上下文。

  • 引入 StatementBuilder 以函数式构建 statements，因为 QueryBuilder API 使用不可变 statement 类型。

  • Session bean 已从 session 重命名为 cassandraSession，SessionFactory bean 已从 sessionFactory 重命名为 cassandraSessionFactory。

  • ReactiveSession bean 已从 reactiveSession 重命名为 reactiveCassandraSession，ReactiveSessionFactory bean 已从 reactiveSessionFactory 重命名为 reactiveCassandraSessionFactory。

  • ReactiveSessionFactory.getSession() 现在返回 Mono<ReactiveSession>。以前它只返回 ReactiveSession。

  • 数据类型解析已移至 ColumnTypeResolver 中，因此所有与 DataType 相关的方法都已从 CassandraPersistentEntity/CassandraPersistentProperty 移至 ColumnTypeResolver（受影响的方法是 MappingContext.getDataType(…), CassandraPersistentProperty.getDataType(), CassandraPersistentEntity.getUserType(), 和 CassandraPersistentEntity.getTupleType()）。

  • Schema 创建已从 MappingContext 移至 SchemaFactory（受影响的方法是 CassandraMappingContext.getCreateTableSpecificationFor(…), CassandraMappingContext.getCreateIndexSpecificationsFor(…), 和 CassandraMappingContext.getCreateUserTypeSpecificationFor(…)）。

已弃用

  • CassandraCqlSessionFactoryBean，请改用 CqlSessionFactoryBean。

  • KeyspaceIdentifier 和 CqlIdentifier，请改用 com.datastax.oss.driver.api.core.CqlIdentifier。

  • CassandraSessionFactoryBean，请改用 CqlSessionFactoryBean。

  • AbstractCqlTemplateConfiguration，请改用 AbstractSessionConfiguration。

  • AbstractSessionConfiguration.getClusterName()，请改用 AbstractSessionConfiguration.getSessionName()。

  • CodecRegistryTupleTypeFactory，请改用 SimpleTupleTypeFactory。

  • Spring Data 的 CqlIdentifier，请改用驱动程序的 CqlIdentifier。

  • forceQuote 属性，因为不再需要引用（quoting）。CqlIdentifier 会正确转义保留关键字并处理大小写敏感性。

  • QueryOptions 和 …CqlTemplate 类型上的 fetchSize 已被弃用，请改用 pageSize。

  • CassandraMappingContext.setUserTypeResolver(…), CassandraMappingContext.setCodecRegistry(…), 和 CassandraMappingContext.setCustomConversions(…)：在 CassandraConverter 上配置这些属性。

  • TupleTypeFactory 和 CassandraMappingContext.setTupleTypeFactory(…)：TupleTypeFactory 不再使用，因为 Cassandra 驱动程序附带了 DataTypes.tupleOf(…) 工厂方法。

  • 通过 CqlSessionFactoryBean (cassandra:session) 创建 Schema 已被弃用。通过 CqlSessionFactoryBean (cassandra:session) 创建 Keyspace 不受影响。

已移除

配置 API

  • PoolingOptionsFactoryBean

  • SocketOptionsFactoryBean

  • CassandraClusterFactoryBean

  • CassandraClusterParser

  • CassandraCqlClusterFactoryBean

  • CassandraCqlClusterParser

  • CassandraCqlSessionParser

  • AbstractClusterConfiguration

  • ClusterBuilderConfigurer（请改用 SessionBuilderConfigurer）

工具类

  • GuavaListenableFutureAdapter

  • 接受 ConsistencyLevel 和 RetryPolicy 参数的 QueryOptions 和 WriteOptions 构造函数。请结合执行配置文件使用构建器作为替代。

  • CassandraAccessor.setRetryPolicy(…) 和 ReactiveCqlTemplate.setRetryPolicy(…) 方法。请使用执行配置文件作为替代。

命名空间支持

新增内容

配置 API

  • CqlSessionFactoryBean

  • InitializeKeyspaceBeanDefinitionParser

  • SessionFactoryFactoryBean，包括通过 KeyspacePopulator 创建 schema

  • KeyspacePopulator 和 SessionFactoryInitializer 用于初始化 keyspace

命名空间支持

  • cassandra:cluster（endpoint 属性已合并到 cassandra:session）

  • cassandra:initialize-keyspace 命名空间支持

  • cassandra:session-factory，支持 cassandra:script