Spring Data Cassandra实战：主键设计、实体映射与高并发写入

1. 为什么后端项目最终用上了 Spring Data Cassandra

我第一次认真评估 Cassandra，是在某后台看板项目需要接收大量设备上报数据的时候。表结构不复杂，但写入量每天千万级，传统关系库扛到后面又贵又麻烦。当时团队里有人提出先用 CQL 写几个查询验证，但真正介入后发现，直接用官方 Java 驱动确实能跑，Spring Data Cassandra 真正的价值，是让后端团队用熟悉的 Repository 模式去操作 Cassandra，省掉大量的样板代码。

后端应用里使用 Spring Data Cassandra，表面上是多了一个数据访问层，实际上是换了一套数据建模思维。很多人以为能像 JPA 那样，把 MySQL 的表结构搬过来，加几个注解就能用，这个想法是大坑。Cassandra 是列族存储，它的查询能力受限于主键设计，不提供跨分区的 join 和复杂聚合。Spring Data 管的是对象如何映射成 CQL，不管该不该这么建表。

这个选型适合谁？适合那些已经决定使用 Cassandra、并且团队里有人能拍板数据模型的团队。如果你的业务是高并发写入、海量历史数据、按某个业务主键高频读取，Cassandra 很合适，Spring Data Cassandra 也会帮你把 Repository、实体映射、连接管理做得很舒服。但如果业务需要频繁多表关联和强事务，那第一关就不是选 Spring Data 还是直连驱动的问题，而是压根不该选 Cassandra。

1.1 Cassandra 在后端适合什么场景，不适合什么场景

适合的场景，特征基本一致：写多读少、数据增长快、需要水平扩展、对一致性要求可以妥协。比如 IoT 传感器数据、用户行为日志、设备状态心跳、订单事件溯源。这类数据有几个共同点：不需要修改历史数据，按设备 ID 或者用户 ID 访问即可，最新的数据往往比老数据重要。

不适合的场景也相对清晰：需要跨表 join 的报表系统、需要强一致的账户交易流程、频繁修改主键的业务、复杂的聚合统计。Cassandra 的数据分布在多个节点上，跨分区查一次就要访问多个节点，效率难以接受。如果业务里到处都是 group by 和 join，用 Spring Data Cassandra 写出来的 Repository 方法会非常别扭，不是语法写不出来，而是 Cassandra 根本不适合执行这类查询。

我判断一个项目要不要上 Cassandra，就问三个问题：写入量是否远大于读取量？查询是不是大多数都能带上固定主键？数据库是不是需要靠横向扩展来分担压力？如果三个问题里有任何一个答案是否定的，我宁可劝对方继续用关系库。技术选型最怕“看起来能用”，硬把一个 OLAP 风格的需求塞进 Cassandra，后面没有任何好处。

1.2 直连官方驱动与 Spring Data 之间怎么权衡

直接使用官方 Java 驱动写数据访问，优点是完全透明。连接池怎么配置、重试策略怎么写、一致性级别怎么设置，都由自己控制，异常也能直接看到最原始的堆栈。缺点也很明显：每个实体都要手工映射到查询结果，每条 CQL 都要维护，查询一多，代码量会快速增长。

Spring Data Cassandra 在官方 Driver 之上做了一层对象映射。它帮我们完成了实体注解到 CQL 的转换、Repository 接口方法名到查询语句的解析、连接配置的自动装配。最直观的感受是，写一个 CRUD 仓储接口只需要几行代码，省下来的时间可以拿去优化数据模型。

但注意，它不是万能 ORM。Spring Data Cassandra 不会自动建索引，不会做关联集合的懒加载，也不会根据 Java 实体变化去同步线上表结构。它更像一个“带注解的 CQL 客户端”，所有底层能力都来自 Cassandra 自身。所以权衡的时候，我建议团队里至少要有一个人能看懂官方驱动层面的日志和异常，否则一旦 Spring Data 包装底层异常，排查会变得很难受。

1.3 这个选型规避了什么，又引入了什么

选 Spring Data Cassandra，规避的是大量重复的驱动层代码。不用再自己写实体到行的转换器，不用自己封装连接池，不用为每个表复制一套增删改查，这是实打实的开发效率提升。

引入的则是新的规则。第一，实体上的注解规则比 JPA 更严格，@Table、@PrimaryKeyClass、@PrimaryKeyColumn、@Column、@CassandraType 每个都有自己设计的用途，理解不深就会踩坑。第二，版本对齐比直连更敏感，Spring Data 与官方 Java 驱动之间存在版本匹配关系，谁随便升级一版都可能让启动直接失败。第三，调试链路过长，一句简单查询报错后，要从前端方法一路找到 Spring Data 生成的 CQL，再到驱动层面的执行日志，如果你不熟悉生成规则，看日志会很痛苦。

综合来看，这个选型的结果是：把“写代码”的工作量压缩了，但把“理解数据模型和底层机制”的要求拉高了。后端组里如果没有 Cassandra 基础，第一批需求做完后大概率会留一堆技术债。

2. 把实体和 CQL 表之间的映射关系理顺

Spring Data Cassandra 的使用难点不在 Repository 接口，而在实体映射是否与 CQL 表结构一致。很多人把实体定义当成 POJO 来写，字段类型和主键含义没有考虑底层表结构，结果查询方法生成出来的 CQL 根本不是预期的东西。

CQL 表的主键由分区键和聚簇键组成。分区键负责决定数据落在哪个节点，聚簇键决定同一分区内的物理存储顺序。映射到 Java 实体时，如果只有一个主键列，可以用 @Id 标注；但多数的实用场景都是复合主键，我建议用独立的 @PrimaryKeyClass 主键类，而不是在一个实体类上堆多个 @PrimaryKeyColumn。原因很简单：实体类的职责是描述业务字段，主键类的职责是描述 CQL 主键结构，两者分开，Repository 泛型也更干净。

2.1 主键拆解：分区键、聚簇键和隐含的顺序

先解释分区键。Cassandra 会根据分区键计算 hash，把数据分配到不同节点。查询语句里如果没带分区键的等值条件，Cassandra 根本不知道去哪个节点找数据，所以很多查询直接被拒绝。这不是 Spring Data 的限制，是 Cassandra 分布式存储的前提。

聚簇键则决定了分区内部的数据排序。比如一张传感器表，分区键是 device_id，聚簇键是 event_time，如果聚簇键定义成 Order.DESCENDING，同一个设备的数据在磁盘上就会按时间从新到旧排列，读最近十条的数据就不需要额外排序。这个设计直接决定了查询效率。

设计主键时千万不要把关系库的“唯一标识”思路带进来。关系库只要保证主键唯一即可，而 Cassandra 必须把查询条件设计进去。一个典型错误是把城市、类型、时间全部塞进分区键，看起来可以区分不同设备，实际业务只按设备查询时会跨多个分区读取，性能很差。实体主键应该跟着高频查询走，不是跟着“唯一性”走。

2.2 派生查询的边界在哪里

Spring Data 的 Repository 方法名可以直接生成查询语句，比如 findByDeviceIdOrderByEventTimeDesc 这种。简单的分区内查询这么写很爽，不写 CQL 就能拿到结果。但它有明确的边界。

第一个边界，是 Cassandra 本身的主键约束。如果派生方法里没有带分区键条件，Spring Data 是不会凭空加一个 allow filtering 的。即使强行写出来，底层查询也会被 Cassandra 拒绝，或者因为全表扫描慢得不可用。

第二个边界，是排序和范围查询。Cassandra 的 order by 只能用于聚簇键，而且排序方向通常要与表定义匹配。Spring Data 的派生查询如果解析出不支持的排序字段，运行时会报错。范围查询虽然支持 Between 和 GreaterThan 这类关键词，但前提是操作对象是聚簇键或二级索引字段。

第三个边界，是批量操作。Repository 里的 saveAll 听上去像批量，但底层通常就是循环执行单条 upsert，并没有 Cassandra 原生的批量协议优化。真正需要批量写入时，要么自己分组处理，要么走更底层的批量操作 API。

我个人的习惯是：分区内简单等值查询用派生方法，范围、排序、分页这些复杂场景直接用 @Query 写 CQL。CQL 就放在 Repository 方法上，可读性、可控性都会好很多，也不容易触发全表扫描。

2.3 时间、集合、UDT 等类型映射的细节

时间类型是实体映射中最容易踩坑的一类。Cassandra 的 timestamp 字段在官方驱动里通常映射为 Instant，但很多后端代码习惯用 LocalDateTime。两者语义有差异，LocalDateTime 不带时区，写入后会被转成 UTC 存储，再读出来时，如果你在东八区做展示，很容易差 8 小时。我建议内部字段一律使用 Instant，只在接口层做时区转换。

集合类型方面，Cassandra 支持 set、list、map，Java 的实体字段也可以映射成对应的 Set、List、Map。但要注意，集合里的元素类型如果用了自定义枚举，默认情况下驱动可能找不到对应的 codec，运行时会报错。这种场景最好注册显式 codec，或者在实体映射时就把枚举字段转成字符串。

UDT 用户自定义类型是另一个深水区。@CassandraType(type = NameType.UDT, userTypeName = "location") 能帮我们绑定一个 UDT 列，但前提是 keyspace 里已经存在这个 UDT 类型，并且 Java 实体的字段名要跟 UDT 内部字段相对应。它不像普通表那样可以自动创建，做实体映射之前必须先把 CQL 类型准备好。

字段命名映射也值得强调。Java 字段默认会被当作列名使用，如果你不写 @Column("reading_value")，Spring Data 就会按 readingValue 这样的驼峰名去建列或者找列。手工建的表如果使用下划线列名，启动时虽然不报错，运行查询就会报列不存在。团队里最好约定所有列名都显式标注，不要依赖框架默认规则。

3. 一个可直接抄作业的读写示例

网上讲 Spring Data Cassandra 的文章不少，但大多只给单主键的简单 CRUD，真正落地时会发现复合主键、批量写入、分页这些环节才是大头。这里我结合一个 IoT 传感器场景，写一个最小可运行示例，从依赖配置到 Repository 都串一遍。

这个例子会覆盖三个点：分区键加聚簇键的复合主键设计、按设备查最新数据、按时间范围查询。这些是设备上报类后端最常见的需求。

3.1 依赖与基础配置

如果是 Spring Boot 项目，直接用 starter 最省心：

xml复制<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-cassandra</artifactId>
</dependency>

非 Boot 项目需要自己引入 Spring Data Cassandra 和官方 Java 驱动，并且一定要核对版本对应关系。驱动从 3.x 升到 4.x 时 API 有大幅调整，Spring Data 内部是编译期依赖某个版本的接口，版本不对最常见的就是 NoSuchMethodError，启动阶段就崩。

本地演示，我一般用 Docker 起一个单节点 Cassandra：

bash复制docker run -d --name cassandra-dev -p 9042:9042 cassandra:4.1
docker exec -it cassandra-dev cqlsh -e "
CREATE KEYSPACE IF NOT EXISTS sensor_space
WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1};"

然后在 Spring Boot 配置里指定 keyspace 和连接参数：

yaml复制spring:
  data:
    cassandra:
      keyspace-name: sensor_space
      contact-points: 127.0.0.1:9042
      local-datacenter: datacenter1
      schema-action: create-if-not-exists

local-datacenter 一定要配置，官方驱动 4.x 连接时需要知道本地数据中心，否则起连就报错。schema-action 开发环境用 create-if-not-exists 方便，生产环境务必改成 none。

3.2 定义主键类与实体

先看主键类。传感器表按设备号分区，同一个设备的数据按时间倒序存放：

java复制@PrimaryKeyClass
public class SensorReadingKey implements Serializable {

    @PrimaryKeyColumn(
            name = "device_id",
            ordinal = 0,
            type = PrimaryKeyPartitioning.PARTITIONED)
    private String deviceId;

    @PrimaryKeyColumn(
            name = "event_time",
            ordinal = 1,
            type = PrimaryKeyPartitioning.CLUSTERED,
            ordering = Order.DESCENDING)
    private Instant eventTime;

    // 构造方法、getter/setter、equals/hashCode 略
}

再看实体：

java复制@Table(value = "sensor_readings")
public class SensorReading {

    @PrimaryKey
    private SensorReadingKey key;

    @Column("reading_value")
    private Double readingValue;

    @Column("battery_level")
    private Integer batteryLevel;

    // getter/setter 略
}

这个设计不是随便来的。device_id 是业务查询必带条件，所以放进分区键；event_time 决定同设备数据的物理排列顺序，倒序排列后，读最新 N 条数据不需要排序，这是 Cassandra 建模的核心技巧。

3.3 仓储层：简单查询、写入、异步化

Repository 接口如下：

java复制public interface SensorReadingRepository
        extends CassandraRepository<SensorReading, SensorReadingKey> {

    @Query("select * from sensor_readings where device_id = ?0 limit ?1")
    List<SensorReading> findLatestByDeviceId(String deviceId, int limit);

    @Query("select * from sensor_readings where device_id = ?0 and event_time > ?1")
    List<SensorReading> findSince(String deviceId, Instant since);
}

CassandraRepository 自带 save、findById、deleteById 等基础方法，满足日常大部分需求。save 的语义是 upsert，不存就插入，存在就覆盖，这一点比关系型 ORM 更贴近 Cassandra 的 insert ... update 合并模型。

如果写入量很大，建议不要在请求线程里同步执行 save。Spring 的 @Async 可以帮我们把写入丢到独立线程池，但要注意，异步方法内部如果直接操作 Repository，实际上是并发线程在跑驱动调用，线程池大小和拒绝策略要提前设定好。数据量再大一些，可以考虑先落本地消息，再后台刷到 Cassandra，进一步解耦。

3.4 全表扫描与分页的底线

Cassandra 最忌讳的操作是全表扫描。Spring Data 的 findAll 看起来没什么问题，但线上如果表很大，一次 findAll 就会把整个集群拖慢。实际上，Cassandra 的 CQL 对不带分区键条件的查询默认是直接拒绝的，只有在明确允许 allow filtering 或者非常小的表上才会执行。

真正的全量遍历，应该按分区逐个查。比如一个设备一个设备地扫，每个分区单独查一遍。如果分区内数据也很多，就要用分页。Spring Data Cassandra 的分页能力和关系库的 offset 分页不一样，它是基于驱动层的 PagingState 游标，每次请求返回一页和下一页的游标。写后台导出任务时，用分页游标一批批取数，比一次性 findAll 可靠得多。

4. 实际操作中最容易翻车的几个地方

Spring Data Cassandra 在代码风格上很像 JPA，但深入之后会发现完全不是一回事。有些问题不是语法错误，而是数据结果不符合预期，这类坑我以前排过不少，挑几个最典型的分享。

4.1 版本不齐，连接报错

最常见的启动失败，是 Spring Data 和官方 Java 驱动版本不匹配。项目里用 Boot starter 时，版本本来已经被统一管理，但经常有第三方依赖传递性地把驱动版本降下去，导致启动时出现 NoSuchMethodError 或 ClassNotFoundException。

排查方法也不复杂。启动日志会告诉你异常发生在哪个类，顺着类名找是 Spring Data 调用了哪个驱动方法。然后再看最终生效的依赖版本，我一般用 mvn dependency:tree 过滤驱动相关的 artifact，确认是不是被其他依赖覆盖了。解决办法通常是检查全局依赖版本管理，把驱动固定到 Spring Data 发布说明里对应的那一档。

这个坑看起来简单，但在大项目里很容易被忽略，尤其是同时引入多个 Spring 生态依赖时。团队里一定不要随意覆盖 starter 内嵌的版本。

4.2 @Transactional 不是银弹

Spring 的 @Transactional 给了大家一个惯性：在服务方法上加个注解，Cassandra 上的多行写入也应该能回滚。这是我在多个项目里看到最多的误解。

Cassandra 本身不提供跨分区事务。它只保证单个分区的写入原子性，跨分区多条写入失败后，成功的那部分不会被自动回滚。Spring Data Cassandra 也不会帮你实现这个能力。所以只要面向的是多分区写入，@Transactional 注解基本就是摆设。

能做的事情是这么几件。一是利用 LWT（轻量事务）做 compare-and-set，比如带 IF NOT EXISTS 条件的插入，保证“不存在才写入”。二是业务层自己设计补偿逻辑，写失败就发消息、做标记，后续手动处理。三是最根本的：把需要保持一致的字段设计在同一个分区键下，这样至少可以依赖单分区原子性。

生产环境里我看到过有人用 @Transactional 包住两条不同设备的数据写入，最后发现一条成功一条失败，数据处于不一致状态。这类问题比查询慢更危险，因为它会直接影响业务正确性。

4.3 更新主键、对象映射与 schema action 的坑

Cassandra 主键写入后不可变。这跟关系库完全不同，别想着用 update ... set device_id = xxx 改主键。如果业务上确实需要变更分区键，只能先删旧数据再插新数据，而且这两步没有原子性保证，中间会有一段“查不到数据”的空窗期。这种需求必须在模型评审阶段跟业务说清楚。

对象映射方面，最大的隐患是列名默认规则。Java 字段 readingValue 如果没写 @Column("reading_value")，Spring Data 会用它自己的驼峰名称去访问和建列。手工建表时如果用下划线风格，运行阶段就会列名匹配不上。这个坑不会在启动时报错，往往要等第一个查询返回空数据或者异常才发现。

schema-action 的坑则更隐蔽。开发阶段开启 create-if-not-exists，确实方便，但它只负责“ если表不存在就创建”，不会自动修改已存在表的结构。你在实体里新增了一个字段，启动时并不会帮你 ALTER TABLE，运行查询时才会发现列不存在。数据库结构变更应该走独立的 CQL 脚本发布流程，实体映射只管读写，不要把 DDL 交给应用。

4.4 超时与线程池问题

Cassandra 在负载升高时不会立刻报错，而是请求延迟变大，最后驱动层抛超时异常。Spring Data 的默认超时不一定适合你，尤其是一致性级别调高或查询数据量大时，可能 2 秒就超时，但业务上多等一会其实能拿到结果。

我的做法是分三层控制。第一层，驱动连接配置里的连接超时和请求超时设成合理值。第二层，业务代码里的异步调用设置等待就绪时间。第三层，写任务和读任务用不同的线程池，避免一个大查询把执行线程占满，其他正常请求排队等待。生产环境要先压测再调，不要一边出问题一边改参数。

5. 从能用到好用：建模、一致性与运维建议

代码层面的坑摸清楚之后，真正考验后端应用的是建模水平、一致性策略和运维节奏。Spring Data Cassandra 只能处理对象与表的映射，无法控制数据分布是否合理。

5.1 一致性级别怎么定

Cassandra 的一致性级别不是越高越好。LOCAL_QUORUM 在大多数后端场景下是性价比最高的选择，它等待本地数据中心多数副本确认，网络开销可控。QUORUM 和 EACH_QUORUM 会更严格，但代价是跨数据中心等待，延迟明显上升。

如果你的业务能接受最终一致，写入级别可以适当放宽，保证可用性优先。如果是关键业务，需要读己之写，就需要把读写一致性都调到 LOCAL_QUORUM。不要所有表都试图追求强一致，Cassandra 的优势之一就是让你按场景灵活选择一致性级别，这是关系库给不了的弹性。

5.2 批量写入与异步的正确打开方式

批量写入不是越多越好。把几千条数据塞进一个 batch，看起来很快，实际性能反而不稳定。Cassandra 的批量操作只对同一分区的数据有最好的效果，跨分区的 batch 会变成一个多分区协调任务，很容易成为集群瓶颈。

正确方式是：尽量按分区键分组批量提交，单批次控制在合理大小，配合异步线程池执行。写入失败时要有重试策略，但重试要带退避，不然失败风暴会放大问题。批量写入代码里，我一般会加一个独立的批量队列和提交任务，服务启动、停止时都能安全flush，不会因为应用重启丢数据。

5.3 监控、运维和测试的补充建议

Cassandra 的运维监控重点和关系库不同。我最关注的是热分区，也就是某些分区数据量远大于其他分区，造成个别节点压力大。这个在启动阶段就可以通过主键设计规避，比如分区键取值不够分散时，可以考虑加一个桶位字段。

测试方面，本地用 Docker 起单节点很方便，但单节点和真实集群在高一致性、高并发下的表现差别很大。集成测试尽量在集群环境跑，准备一套真实的复制因子和一致性配置。单元测试侧可以试嵌入式 Cassandra 组件，但不要用它来测超时和负载问题。

线上表结构变更要有 CQL 脚本管理，不要依赖应用自动建表。每次变更先备份、再灰度执行脚本，然后逐步调整实体映射。这个流程不复杂，但能避免很多生产事故。

结尾的个人体会

Spring Data Cassandra 用了不少时间后，我的整体感觉是：它没有传说的那么可怕，也没有某些框架那样的“安上就能飞”。它把驱动层的繁琐操作封装得足够友好，让后端团队可以专注于业务字段和查询逻辑，但前提是你必须真正理解 Cassandra 的主键模型。只要主键设计对了，Repository 写起来很顺；主键设计错了，后面每一步都会别扭。最后分享一个小技巧：实体里所有字段显式写 @Column，所有主键单独抽成 @PrimaryKeyClass，所有复杂查询用 @Query 显式表达 CQL。这三个习惯看似简单，却能让项目从一开始就少踩很多坑。