跳到主要内容
版本：4.4.3

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

ChatGPT-4o-mini 中英对照 Migration Guide from 2.x to 3.x

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

审查依赖​

升级到 Spring Data Cassandra 需要将 DataStax 驱动程序升级到版本 4。升级到新驱动程序会带来传递依赖关系的变化，最显著的是，Google Guava 被驱动程序捆绑并遮蔽。有关驱动程序相关更改的详细信息，请查看 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](http://www.springframework.org/schema/cql) [www.springframework.org/schema/cql/spring-cql.xsd](https://www.springframework.org/schema/cql/spring-cql.xsd)）迁移到 cassandra 命名空间（[www.springframework.org/schema/data/cassandra](http://www.springframework.org/schema/data/cassandra) [www.springframework.org/schema/data/cassandra/spring-cassandra.xsd](https://www.springframework.org/schema/data/cassandra/spring-cassandra.xsd)）。

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

连接性​

Cluster（cassandra:cluster）和Session（cassandra:session）的配置元素被合并为一个单独的CqlSession（cassandra:session）元素，该元素同时配置键空间和端点。

随着升级，架构支持被移动到一个新的命名空间元素：cassandra:session-factory，该元素提供一个 SessionFactory bean。

示例 1. 版本 2 中的集群、会话和模式配置：

<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 中的会话和架构配置:

<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 命名空间配置时不再注册默认的映射上下文、上下文和模板 API bean。默认设置应在应用程序或 Spring Boot 级别应用。

模板 API​

Spring Data for Apache Cassandra 封装了大部分随着驱动程序升级而来的变化，因为如果您的应用程序主要与映射实体或原始 Java 类型交互，则可以使用 Template API 和存储库支持。

我们通常建议通过使用 SessionFactory 创建 CqlTemplate 和 CassandraTemplate 对象，因为使用工厂可以实现模式创建的同步，并在处理多个数据库时引入一定的灵活性。

示例 3. 版本 2 中的模板 API 配置：

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

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

示例 4. 版本 3 中的模板 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 驱动程序 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 驱动程序 4 不再附带用于描述 Cassandra 类型的 Name 枚举。我们决定重新引入该枚举，使用 CassandraType.Name。请确保更新您的导入以使用新引入的替代类型。

强制引用​

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

属性类型​

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

其他更改​

  • 驱动程序的 ConsistencyLevel 常量类被移除并重新引入为 DefaultConsistencyLevel。 @Consistency 被调整为 DefaultConsistencyLevel。

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

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

  • SimpleUserTypeResolver 接受 CqlSession 而不是 Cluster。

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

  • 引入 StatementBuilder 以功能性地构建语句，因为 QueryBuilder API 使用不可变的语句类型。

  • 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()）。

  • 架构创建被移动从 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 属性不再需要引号。CqlIdentifier 正确转义保留关键字并处理大小写敏感性。

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

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

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

  • 通过 CqlSessionFactoryBean（cassandra:session）创建模式已被弃用。通过 CqlSessionFactoryBean（cassandra:session）创建键空间不受影响。

删除​

配置 API​

  • PoolingOptionsFactoryBean

  • SocketOptionsFactoryBean

  • CassandraClusterFactoryBean

  • CassandraClusterParser

  • CassandraCqlClusterFactoryBean

  • CassandraCqlClusterParser

  • CassandraCqlSessionParser

  • AbstractClusterConfiguration

  • ClusterBuilderConfigurer （请使用 SessionBuilderConfigurer 代替）

工具​

  • GuavaListenableFutureAdapter

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

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

命名空间支持​

  • cql 命名空间 ([www.springframework.org/schema/cql](http://www.springframework.org/schema/cql)，请改用 [www.springframework.org/schema/data/cassandra](http://www.springframework.org/schema/data/cassandra))

  • cassandra:cluster（端点属性合并到 cassandra:session）

  • cql:template，请改用 cassandra:cql-template

  • 移除了隐式的 bean 注册：映射上下文、上下文和模板 API 的 bean。必须显式声明这些 bean。

添加​

配置 API​

  • CqlSessionFactoryBean

  • InitializeKeyspaceBeanDefinitionParser

  • SessionFactoryFactoryBean 包括通过 KeyspacePopulator 创建架构

  • KeyspacePopulator 和 SessionFactoryInitializer 用于初始化键空间

命名空间支持​

  • cassandra:cluster（端点属性合并到 cassandra:session）

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

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