对于最新的稳定版本，请使用 Spring Data Cassandra 5.0.4！spring-doc.cadn.net.cn

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

Spring Data for Apache Cassandra 3.0 在从早期版本升级时引入了一系列破坏性变更。spring-doc.cadn.net.cn

审查依赖项

升级到 Spring Data Cassandra 需要同时将 DataStax 驱动程序升级到第 4 版。升级到新驱动程序会带来传递依赖项的变更，其中最值得注意的是，Google Guava 已被该驱动程序打包并进行了重命名（shaded）。 有关驱动程序相关变更的详细信息，请参阅 DataStax Apache Cassandra Java 驱动程序 4 升级指南。spring-doc.cadn.net.cn

适配配置

DataStax Java Driver 4 将 Cluster 和 Session 对象合并为单一的 CqlSession 对象，因此所有与 Cluster 相关的 API 均已被移除。 配置在很大程度上进行了修订，移除了大多数已迁移到 DriverConfigLoader 的配置项，而 SocketOptions 主要基于文件进行配置。 这意味着 AddressTranslator、7 以及许多其他选项现在需通过其他方式进行配置。spring-doc.cadn.net.cn

如果您使用的是基于 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）。spring-doc.cadn.net.cn

为了反映配置构建器的变更，ClusterBuilderConfigurer 已重命名为 SessionBuilderConfigurer，现在接受 CqlSessionBuilder 而不再是 Cluster.Builder。 请确保在您的配置中也提供本地数据中心，因为正确配置负载均衡需要此项设置。spring-doc.cadn.net.cn

连接性

Cluster（cassandra:cluster）和Session（cassandra:session）的配置元素已合并为一个单一的CqlSession（cassandra:session）元素，该元素同时配置键空间（keyspace）和端点（endpoints）。spring-doc.cadn.net.cn

升级后，模式支持被移至一个新的命名空间元素：cassandra:session-factory，该元素提供了一个 SessionFactory bean。spring-doc.cadn.net.cn

示例 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 不再注册默认的 Mapping Context、Context 和 Template API Bean。 默认行为应由应用程序或 Spring Boot 层面来应用。

模板 API

Spring Data for Apache Cassandra 封装了驱动程序升级所带来的大部分变更，前提是您的应用程序主要通过模板 API 和仓库支持与映射的实体或 Java 基本类型进行交互。spring-doc.cadn.net.cn

我们通常建议使用 CqlTemplate 和 CassandraTemplate 对象时，通过 SessionFactory 来创建，因为这种工厂用法可以实现模式（schema）创建的同步，并在处理多个数据库时提供一定程度的灵活性。spring-doc.cadn.net.cn

示例 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 的地方修改您的代码。 典型情况包括：spring-doc.cadn.net.cn

变更内容AsyncCqlTemplate

DataStax 驱动程序 4 已更改异步执行查询的结果类型。 为反映这些变更，您需要调整提供以下内容的代码：spring-doc.cadn.net.cn

结果集提取需要为 DataStax 的 AsyncResultSet 引入一个新的接口。 AsyncCqlTemplate 现在在其原先使用 AsyncResultSetExtractor 的地方改用 ResultSetExtractor。 请注意，AsyncResultSetExtractor.extractData(…) 返回的是一个 Future 而非普通对象，因此在迁移代码时，可以在提取器中完全使用非阻塞代码。spring-doc.cadn.net.cn

数据模型迁移

如果使用以下功能，您的数据模型可能需要更新：spring-doc.cadn.net.cn

@CassandraType

DataStax Driver 4 不再附带用于描述 Cassandra 类型的 Name 枚举。 我们决定通过 CassandraType.Name 重新引入该枚举。 请确保更新您的导入语句，以使用新引入的替代类型。spring-doc.cadn.net.cn

强制引用

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

属性类型

DataStax driver 4 不再使用 java.lang.Date。 请将您的数据模型升级为使用 java.time.LocalDateTime。 同时，请将原始的 UDT 和元组类型迁移至新驱动程序类型 UdtValue 和对应的 TupleValue。spring-doc.cadn.net.cn

其他变更

  • 驱动程序的 ConsistencyLevel 常量类已被移除，并重新引入为 DefaultConsistencyLevel。@Consistency 注解已适配为使用 DefaultConsistencyLevel。spring-doc.cadn.net.cn

  • RetryPolicy 在 QueryOptions 和 …CqlTemplate 类型上已被移除，且无替代方案。spring-doc.cadn.net.cn

  • 驱动程序的 PagingState 类型已被移除。 分页状态现在使用 ByteBuffer。spring-doc.cadn.net.cn

  • SimpleUserTypeResolver 接受 CqlSession 而不是 Cluster。spring-doc.cadn.net.cn

  • SimpleTupleTypeFactory 已迁移为 enum。SimpleTupleTypeFactory.INSTANCE 不再需要 Cluster/CqlSession 上下文。spring-doc.cadn.net.cn

  • 引入StatementBuilder，以函数式方式构建语句，因为 QueryBuilder API 使用的是不可变的语句类型。spring-doc.cadn.net.cn

  • Session bean 的名称已从 session 更改为 cassandraSession，SessionFactory bean 的名称已从 sessionFactory 更改为 cassandraSessionFactory。spring-doc.cadn.net.cn

  • ReactiveSession bean 的名称已从 reactiveSession 更改为 reactiveCassandraSession，ReactiveSessionFactory bean 的名称已从 reactiveSessionFactory 更改为 reactiveCassandraSessionFactory。spring-doc.cadn.net.cn

  • ReactiveSessionFactory.getSession() 现在返回一个 Mono<ReactiveSession>。 之前它仅返回 ReactiveSession。spring-doc.cadn.net.cn

  • 数据类型解析已移至 ColumnTypeResolver，因此所有与 DataType 相关的方法已从 CassandraPersistentEntity/CassandraPersistentProperty 移至 ColumnTypeResolver（受影响的方法包括 MappingContext.getDataType(…)、CassandraPersistentProperty.getDataType()、CassandraPersistentEntity.getUserType() 和 CassandraPersistentEntity.getTupleType()）。spring-doc.cadn.net.cn

  • 模式创建已从 MappingContext 移至 SchemaFactory（受影响的方法包括 CassandraMappingContext.getCreateTableSpecificationFor(…)、CassandraMappingContext.getCreateIndexSpecificationsFor(…) 和 CassandraMappingContext.getCreateUserTypeSpecificationFor(…)）。spring-doc.cadn.net.cn

弃用

  • CassandraCqlSessionFactoryBean，请改用 CqlSessionFactoryBean。spring-doc.cadn.net.cn

  • KeyspaceIdentifier 和 CqlIdentifier，请改用 com.datastax.oss.driver.api.core.CqlIdentifier。spring-doc.cadn.net.cn

  • CassandraSessionFactoryBean，请改用 CqlSessionFactoryBean。spring-doc.cadn.net.cn

  • AbstractCqlTemplateConfiguration，请改用 AbstractSessionConfiguration。spring-doc.cadn.net.cn

  • AbstractSessionConfiguration.getClusterName()，请改用 AbstractSessionConfiguration.getSessionName()。spring-doc.cadn.net.cn

  • CodecRegistryTupleTypeFactory，请改用 SimpleTupleTypeFactory。spring-doc.cadn.net.cn

  • Spring Data 的 CqlIdentifier，请改用驱动程序的 CqlIdentifier。spring-doc.cadn.net.cn

  • forceQuote 属性已不再需要，因为现在无需再进行引号转义。CqlIdentifier 能够正确地转义保留关键字，并处理大小写敏感问题。spring-doc.cadn.net.cn

  • fetchSize 和 QueryOptions 类型上的 …CqlTemplate 已被弃用，请改用 pageSizespring-doc.cadn.net.cn

  • CassandraMappingContext.setUserTypeResolver(…)、CassandraMappingContext.setCodecRegistry(…) 和 CassandraMappingContext.setCustomConversions(…)：在 CassandraConverter 上配置这些属性。spring-doc.cadn.net.cn

  • TupleTypeFactory 和 CassandraMappingContext.setTupleTypeFactory(…)：TupleTypeFactory 不再被使用，因为 Cassandra 驱动程序已自带 DataTypes.tupleOf(…) 工厂方法。spring-doc.cadn.net.cn

  • 通过 CqlSessionFactoryBean（cassandra:session）创建 Schema 已被弃用。 通过 CqlSessionFactoryBean（cassandra:session）创建 Keyspace 不受影响。spring-doc.cadn.net.cn

移除

配置 API

实用工具

  • GuavaListenableFutureAdapterspring-doc.cadn.net.cn

  • QueryOptions 和 WriteOptions 的构造函数接受 ConsistencyLevel 和 RetryPolicy 参数。 请结合执行配置文件（execution profiles）使用构建器（builder）作为替代方案。spring-doc.cadn.net.cn

  • CassandraAccessor.setRetryPolicy(…) 和 ReactiveCqlTemplate.setRetryPolicy(…) 方法。 请使用执行配置文件（execution profiles）作为替代方案。spring-doc.cadn.net.cn

命名空间支持

新增内容

配置 API

命名空间支持