本文详解如何在 Spring WebFlux 项目中正确使用 Reactive Cassandra 访问含复合主键（Partition Key + Clustering Column）的 Cassandra 表，解决 ReactiveCassandraRepository 无法查询的常见问题。
本文详解如何在 spring webflux 项目中正确使用 reactive cassandra 访问含复合主键（partition key + clustering column）的 cassandra 表，解决 `reactivecassandrarepository` 无法查询的常见问题。
在基于 Spring Reactive 的微服务架构中，集成 Cassandra 时若表结构包含复合主键（如 user_name 为分区键、department_name 为聚类列），直接沿用传统单主键模式定义实体与仓库极易失败——典型表现为 findByKeyXXX() 方法始终返回空 Mono.empty() 或抛出 InvalidQueryException。根本原因在于：Spring Data Cassandra Reactive 对复合主键的默认方法派生逻辑存在限制，不支持嵌套主键对象（如 UserKey）作为泛型参数的自动条件构建，尤其当聚类列参与精确匹配时，方法名解析无法正确映射至 CQL 的 WHERE 子句。
✅ 正确实践是采用「扁平化实体 + 原生 CQL 查询」组合方案：
1. 简化实体类：取消独立 @PrimaryKeyClass，将主键字段直定义于实体中
@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 必须标注在实体字段上（而非嵌套类），且 ordering 属性对聚类列是强制要求，否则驱动无法生成合法 CQL。
2. 仓库接口：放弃派生查询，改用 @Query 编写明确 CQL
@Repository
public interface UserRepository extends ReactiveCassandraRepository<UserConfig, String> {
// ✅ 按分区键查询（返回所有该用户的部门记录）
@Query("SELECT * FROM user_table WHERE user_name = ?0")
Flux<UserConfig> findByUserName(String userName);
// ✅ 按分区键 + 聚类列精确查询（推荐用于复合主键精准匹配）
@Query("SELECT * FROM user_table WHERE user_name = ?0 AND department_name = ?1")
Mono<UserConfig> findByUserNameAndDepartmentName(String userName, String departmentName);
// ✅ 支持范围查询（利用聚类列有序特性）
@Query("SELECT * FROM user_table WHERE user_name = ?0 AND department_name >= ?1 AND department_name <= ?2")
Flux<UserConfig> findDepartmentsInRange(String userName, String startDept, String endDept);
}? 提示：泛型
中第二个参数可设为任意类型（如 String），因 ReactiveCassandraRepository 在启用 @Query 后不再依赖该泛型推导主键；但必须保留以满足接口契约。
3. 关键配置验证（确保无遗漏）
- application.yml 中需启用 schema 自动创建（开发阶段）：
spring: cassandra: schema-action: CREATE_IF_NOT_EXISTS # 或 RECREATE_DROP contact-points: localhost port: 9042 keyspace-name: demo_keyspace local-datacenter: datacenter1 - CassandraConfig 类中 cassandraSession() Bean 必须显式设置 username/password（如已启用认证），且 localDatacenter 需与 Cassandra cassandra.yaml 中配置严格一致。
总结
当面对 Cassandra 复合主键表时，不要依赖 ReactiveCassandraRepository 的方法名派生机制，而应：
① 将分区键与聚类列统一声明为实体字段，并用 @PrimaryKeyColumn 标注；
② 使用 @Query 编写符合 CQL 规则的显式查询语句；
③ 牢记聚类列必须指定 ordering，且查询条件必须遵循「分区键 → 聚类列前缀」的顺序约束（Cassandra 分区局部有序原则）。
此方案规避了 Spring Data 层对复杂主键的解析缺陷，同时保持响应式流的高性能特性，是生产环境推荐的标准实践。
