从 2.x 迁移到 3.x

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

检查依赖项

升级到 Spring Data Cassandra 需要升级到 DataStax Driver 版本 4。升级到新驱动程序会带来传递依赖项更改，最值得注意的是，Google Guava 由驱动程序捆绑和隐藏。查看Apache Cassandra 4 升级指南的 DataStax Java 驱动程序，了解有关驱动程序相关更改的详细信息。

调整配置

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) 元素中，该元素同时配置键空间和端点。

升级后，模式支持已移动到新的命名空间元素：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>
使用 XML 命名空间配置时，Spring Data Cassandra 3.0 不再注册默认映射上下文、上下文和模板 API bean。默认值应在应用程序或 Spring Boot 级别应用。

模板 API

如果您的应用程序主要与映射实体或原始 Java 类型交互，则 Apache Cassandra 的 Spring Data 封装了驱动程序升级带来的大多数更改，如模板 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

  • @Table、@Column、@PrimaryKeyColumn、@PrimaryKey和@UserDefinedType中的forceQuote

  • 使用java.lang.Date的属性

  • 使用UDTValue或TupleValue的属性

@CassandraType

DataStax 驱动程序 4 不再附带用于描述 Cassandra 类型的Name枚举。我们决定使用CassandraType.Name重新引入枚举。请确保更新导入以使用新引入的替换类型。

强制引用

此标志现在已弃用，我们建议不再使用它。Apache Cassandra 的 Spring Data 在内部使用驱动程序的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相关的 method 都已从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) 创建 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 创建模式。

  • KeyspacePopulator 和SessionFactoryInitializer 用于初始化 keyspace。

命名空间支持

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

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

  • cassandra:session-factory 带有cassandra:script 支持