Spring Reactive Cassandra 复合主键表访问完整教程

在基于Spring WebFlux的微服务架构里，集成Cassandra数据库时，如果表结构用到了复合主键——比如一个分区键（Partition Key）加上一个或多个聚类列（Clustering Column），很多开发者会发现自己踩进了一个“坑”。沿用传统的单主键实体和仓库定义方式，那些看似合理的findByKeyXXX()方法，执行起来要么悄无声息地返回一个空的Mono.empty()，要么干脆抛出一个InvalidQueryException，让人摸不着头脑。

问题的根源其实很明确：Spring Data Cassandra Reactive对复合主键的默认方法派生逻辑存在限制。当你的主键是一个嵌套的@PrimaryKeyClass对象时，框架在解析方法名并自动构建CQL查询条件时，尤其当查询需要精确匹配聚类列时，往往无法正确映射到最终的WHERE子句。这导致生成的查询语句不符合Cassandra的语法规则，查询自然就失败了。

那么，正确的打开方式是什么？经过实践验证，一套稳定可靠的方案是采用“扁平化实体 + 原生CQL查询”的组合策略。下面我们就来拆解这个方案的具体步骤。

1. 简化实体类：告别独立主键类

首先，我们需要抛弃为复合主键单独定义一个@PrimaryKeyClass的做法。相反，直接把分区键和聚类列作为普通字段，定义在实体类本身，并用@PrimaryKeyColumn注解明确标注它们的角色和顺序。

@Data
@AllArgsConstructor
@Table("user_table")
public class UserConfig implements Serializable {
    @PrimaryKeyColumn(
        name = "user_name",
        ordinal = 0,
        type = PrimaryKeyType.PARTITIONED
    )
    private String userName;

    @PrimaryKeyColumn(
        name = "department_name",
        ordinal = 1,
        type = PrimaryKeyType.CLUSTERED,
        ordering = Ordering.ASCENDING // 显式声明排序方向（必需！）
    )
    private String departmentName;

    @Column("address")
    private String address;
}

这里有个关键点必须注意：@PrimaryKeyColumn注解必须直接用在实体类的字段上，而不是某个嵌套类的字段上。另外，对于聚类列（CLUSTERED类型），ordering属性是强制要求指定的（如ASCENDING或DESCENDING），否则Cassandra驱动将无法生成合法的CQL语句。

2. 仓库接口：放弃猜测，明确查询

实体扁平化之后，仓库接口（Repository）的定义也需要调整。核心原则是：放弃依赖方法名派生查询，转而使用@Query注解编写明确的CQL语句。这样，查询逻辑完全掌握在你手中，避免了框架的“误判”。

@Repository
public interface UserRepository extends ReactiveCassandraRepository {
    // ✅ 按分区键查询（返回所有该用户的部门记录）
    @Query("SELECT * FROM user_table WHERE user_name = ?0")
    Flux findByUserName(String userName);

    // ✅ 按分区键 + 聚类列精确查询（推荐用于复合主键精准匹配）
    @Query("SELECT * FROM user_table WHERE user_name = ?0 AND department_name = ?1")
    Mono findByUserNameAndDepartmentName(String userName, String departmentName);

    // ✅ 支持范围查询（利用聚类列有序特性）
    @Query("SELECT * FROM user_table WHERE user_name = ?0 AND department_name >= ?1 AND department_name <= ?2")
    Flux findDepartmentsInRange(String userName, String startDept, String endDept);
}

这里有个小细节：接口定义中的第二个泛型参数（示例中是String），在启用了@Query后其实不再起实际作用，因为查询逻辑已经不依赖它来推导主键了。但为了满足ReactiveCassandraRepository的接口契约，仍然需要保留，可以设为String或任何类型。

3. 关键配置：确保万无一失

代码写对了，配置也不能掉链子。下面这两项是经常被忽略但又至关重要的检查点：

• 应用配置（application.yml）：在开发阶段，建议启用Schema自动创建，避免手动建表的麻烦。

  spring:
    cassandra:
      schema-action: CREATE_IF_NOT_EXISTS # 或 RECREATE_DROP_UNUSED
      contact-points: localhost
      port: 9042
      keyspace-name: demo_keyspace
      local-datacenter: datacenter1

• Session Bean配置：如果你在@Configuration类中自定义了cassandraSession() Bean，请务必确认两件事：一是如果Cassandra集群启用了认证，需要正确设置username和password；二是localDatacenter的设置必须与Cassandra集群配置文件（cassandra.yaml）中的数据中心名称严格一致，一个字母都不能错，否则连接会失败。

总结

面对Cassandra的复合主键表，最稳妥的策略就是绕开框架的“自动挡”，自己掌握“方向盘”。总结起来就三步：

第一，实体扁平化。把分区键和聚类列直接作为实体字段，用@PrimaryKeyColumn清晰定义，别忘了给聚类列加上ordering。

第二，查询显式化。在Repository中果断使用@Query注解编写CQL，让查询意图一目了然。

第三，遵循顺序约束。编写CQL的WHERE条件时，必须严格遵守Cassandra的“分区键优先，聚类列前缀有序”原则，这是Cassandra数据模型的基石。

这套方案虽然看起来多写了几行CQL，但它彻底规避了Spring Data层在解析复杂主键时可能存在的缺陷，同时完全保留了响应式编程的非阻塞和高性能特性，是经过生产环境验证的可靠实践。