跳到主要内容
版本：4.4.3

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

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

Spring Data for Apache Cassandra 2.0 引入了一些重大更改，当从早期版本升级时会影响现有代码：

  • 将 spring-cql 和 spring-data-cassandra 模块合并为一个单一模块。

  • 将 CqlOperations 和 CassandraOperations 中的异步和同步操作分离到专用接口和模板中。

  • 修改了 CqlTemplate API，使其与 JdbcTemplate 保持一致。

  • 移除了 CassandraOperations.selectBySimpleIds 方法。

  • 为 CassandraRepository 使用了更好的命名。

  • 移除了 SD Cassandra 的 ConsistencyLevel 和 RetryPolicy 类型，改为使用 DataStax 的 ConsistencyLevel 和 RetryPolicy 类型。

  • 将 CQL 规范重构为值对象和值配置器。

  • 将 QueryOptions 重构为不可变对象。

  • 将 CassandraPersistentProperty 重构为单列。

废弃内容​

  • 弃用 QueryOptionsBuilder.readTimeout(long, TimeUnit)，推荐使用 QueryOptionsBuilder.readTimeout(Duration)。

  • 弃用 CustomConversions，推荐使用 CassandraCustomConversions。

  • 弃用 BasicCassandraMappingContext，推荐使用 CassandraMappingContext。

  • 弃用 o.s.d.c.core.cql.CachedPreparedStatementCreator，推荐使用 o.s.d.c.core.cql.support.CachedPreparedStatementCreator。

  • 弃用 CqlTemplate.getSession()，推荐使用 getSessionFactory()。

  • 弃用 CqlIdentifier.cqlId(…) 和 KeyspaceIdentifier.ksId(…)，推荐使用 .of(…) 方法。

  • 弃用 QueryOptions 的构造函数，推荐使用其构建器。

  • 弃用 TypedIdCassandraRepository，推荐使用 CassandraRepository。

合并的 Spring CQL 和 Spring Data Cassandra 模块​

Spring CQL 和 Spring Data Cassandra 现在已合并为一个模块。独立的 spring-cql 模块不再可用。所有类型已合并到 spring-data-cassandra 中。以下列表展示了如何将 spring-data-cassandra 包含到您的 maven 依赖中：

<dependencies>

  <dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-cassandra</artifactId>
    <version>4.4.3</version>
  </dependency>

</dependencies>

通过合并，我们将所有 CQL 包合并到了 Spring Data Cassandra 中：

  • 将 o.s.d.cql 移动到 o.s.d.cassandra.core.cql。

  • 将 o.s.d.cql 与 o.s.d.cassandra.config 合并，并扁平化 XML 和 Java 子包。

  • 将 CassandraExceptionTranslator 和 CqlExceptionTranslator 移动到 o.s.d.c.core.cql。

  • 将 Cassandra 异常 o.s.d.c.support.exception 移动到 o.s.d.cassandra。

  • 将 o.s.d.c.convert 移动到 o.s.d.c.core.convert（影响转换器）。

  • 将 o.s.d.c.mapping 移动到 o.s.d.c.core.mapping（影响映射注解）。

  • 将 MapId 从 o.s.d.c.repository 移动到 o.s.d.c.core.mapping。

[[revised-cqltemplate/cassandratemplate]] == 修订版 CqlTemplate / CassandraTemplate

我们将 CqlTemplate 和 CassandraTemplate 分为三种方式：

  • CassandraTemplate 不再是 CqlTemplate，而是使用一个实例，允许重用并对提取大小、一致性级别和重试策略进行精细控制。您可以通过 CassandraTemplate.getCqlOperations() 获取 CqlOperations。由于这一变化，CqlTemplate 的依赖注入需要额外的 bean 设置。

  • CqlTemplate 现在仅反映基本的 CQL 操作，而不是混合高级和低级 API 调用（例如 count(…) 与 execute(…)），减少的方法集与 Spring Framework 的 JdbcTemplate 对齐，提供了方便的回调接口。

  • 异步方法在 AsyncCqlTemplate 和 AsyncCassandraTemplate 中重新实现，使用了 ListenableFuture。我们移除了 Cancellable 和各种异步回调监听器。ListenableFuture 是一种灵活的方法，允许过渡到 CompletableFuture。

移除 CassandraOperations.selectBySimpleIds()​

该方法被移除，因为它不支持复杂 ID。新引入的查询 DSL 允许映射和复杂 ID 用于单列 ID，如以下示例所示：

cassandraTemplate.select(Query.query(Criteria.where("id").in(…)), Person.class)

CassandraRepository 的更好命名​

我们重命名了 CassandraRepository 和 TypedIdCassandraRepository，以便使 Spring Data Cassandra 的命名与其他 Spring Data 模块保持一致：

  • 将 CassandraRepository 重命名为 MapIdCassandraRepository

  • 将 TypedIdCassandraRepository 重命名为 CassandraRepository

  • 引入 TypedIdCassandraRepository，继承自 CassandraRepository，作为已弃用类型以简化迁移

移除了 SD Cassandra ConsistencyLevel 和 RetryPolicy 类型，改用 DataStax ConsistencyLevel 和 RetryPolicy 类型​

Spring Data Cassandra ConsistencyLevel 和 RetryPolicy 已被移除。请使用 DataStax 驱动程序提供的类型。

Spring Data Cassandra 的类型限制了 Cassandra 原生驱动程序提供的可用功能的使用。因此，每当驱动程序引入新功能时，Spring Data Cassandra 的类型都需要进行更新。

重构的 CQL 规范到值对象和配置器​

尽可能地，CQL 规范类型现在是值类型（例如 FieldSpecification、AlterColumnSpecification），对象通过静态工厂方法构造。这允许简单值对象的不可变性。操作强制属性（例如表名或键空间名）的配置对象（例如 AlterTableSpecification）最初通过静态工厂方法构造，并允许进一步配置，直到创建所需状态。

重构 QueryOptions 为不可变对象​

QueryOptions 和 WriteOptions 现在是不可变的，可以通过构建器创建。接受 QueryOptions 的方法强制要求非空对象，这些对象可以通过静态 empty() 工厂方法获得。以下示例展示了如何使用 QueryOptions.builder()：

QueryOptions queryOptions = QueryOptions.builder()
		.consistencyLevel(ConsistencyLevel.ANY)
		.retryPolicy(FallthroughRetryPolicy.INSTANCE)
		.readTimeout(Duration.ofSeconds(10))
		.fetchSize(10)
		.tracing(true)
		.build();

重构 CassandraPersistentProperty 为单列​

此更改仅在您直接操作映射模型时才会影响您。

CassandraPersistentProperty 之前允许多个列名绑定以用于复合主键。现在，CassandraPersistentProperty 的列减少为单个列。解析后的复合主键通过 MappingContext.getRequiredPersistentEntity(…) 映射到一个类。