在Cassandra这种去中心化的宽列存储里，多个客户端同时向同一行写入数据时，如果没有额外约束，后到的请求会直接覆盖先到的数据。IF NOT EXISTS轻量级事务就是用来解决“只有这行不存在才插入”这类需求的。它底层走的是Paxos共识，而不是普通写路径里的 eventual consistency 直接提交，因此能在集群多数派节点之间确认状态后再决定是否落盘。
IF NOT EXISTS的底层执行原理
Cassandra的轻量级事务（LWT）基于Paxos算法做了工程化改造。当客户端发送带IF NOT EXISTS的INSERT时，协调者节点不会直接写数据，而是先进入Paxos的Prepare阶段，向所有副本询问当前这行数据的最大承诺轮次（ballot）。如果多数派节点返回说没有更高轮次的提议，协调者才会进入Accept阶段，把“插入这行”作为提议值广播出去，等多数派确认后真正提交。这意味着一次IF NOT EXISTS写入，在网络上实际发生了两轮往返，延迟通常是普通写的数倍。
从存储引擎角度看，LWT还会在系统表system.paxos里记录提议状态，用于崩溃恢复和轮次比对。正因为要维护Paxos状态，这类操作对节点CPU和磁盘的压力也更大。很多新手以为IF NOT EXISTS只是加了个判断条件，其实它把单行操作升级成了跨节点共识，隔离级别达到了SERIALIZABLE，这是普通QUORUM写做不到的。
还需要注意，IF NOT EXISTS只对“整行不存在”生效。如果某行主键存在但某些普通列值为null，LWT依然会认为行已存在而拒绝插入。下面是一段典型的CQL使用示例，展示了条件插入以及返回结果中applied字段的含义。
-- 只有当用户id=1001这行不存在时才插入
INSERT INTO users (id, name, age)
VALUES (1001, 'Alice', 30)
IF NOT EXISTS;
-- 返回结果示例
-- [{applied: false, id: 1001, name: 'Bob', age: 25}]
-- 表示插入未生效，且当前已存在的行内容如上
和普通写入及IF EXISTS的对比分析
普通INSERT语句在Cassandra里是幂等覆盖语义：不论行在不在，都会用新值替换旧值。这在计数器、日志追加等场景没问题，但在“用户注册首条记录”“全局配置初始化”等只需要创建一次的场景就会出乱子。IF NOT EXISTS保证了创建动作的原子性，而IF EXISTS则常用于“存在才更新”的防御性修改，两者都走LWT路径。
我们用一张简表对比三者在一致性、延迟和适用面上的差异。可以看到，LWT牺牲了吞吐和延迟换来线性一致判断，不适合写热点。如果业务能用时间戳或UUID天然避不开冲突，就尽量不要用IF NOT EXISTS；只有真正需要“全集群看一眼再决定”时才启用。
| 写入方式 | 一致性模型 | 典型延迟 | 适用场景 |
|---|---|---|---|
| 普通INSERT | 最终一致 | 低 | 覆盖写、高频日志 |
| INSERT IF NOT EXISTS | 串行一致 | 高 | 唯一初始化、防重复建 |
| UPDATE IF EXISTS | 串行一致 | 高 | 存在才改、防误建 |
在驱动层面，条件写返回的applied为false时，应用必须处理“别人已经建了”的情况，而不是盲目重试。错误的做法是捕获异常后无脑重发同样的IF NOT EXISTS，这只会放大Paxos竞争。正确做法是读取当前行，走后续的更新或读取逻辑。
ResultSet rs = session.execute(
"INSERT INTO users (id, name) VALUES (?, ?) IF NOT EXISTS",
1001, "Alice");
if (!rs.one().getBool("applied")) {
// 已被其他客户端创建，改为查询或更新
Row row = session.execute("SELECT name FROM users WHERE id=?", 1001).one();
System.out.println("existing user: " + row.getString("name"));
}
生产环境使用时的避坑与调优
第一个常见误区是把IF NOT EXISTS用在超高并发的计数器自增上。由于每次都要走Paxos，热点主键会让协调者节点CPU飙高，甚至出现超时。对于这类需求，应改用Cassandra的counter类型或把写入打散到不同分区。第二个坑是忽略了序列化级别配置：LWT默认使用SERIAL，但读端如果用ONE级别去读，可能短时间内看不到刚applied的行，造成业务层误以为插入失败。
调优方面，可以适当增大paxos_purge_grace_period让Paxos状态留存更久以便排障，同时把条件写集中在少数表上，避免全库到处用LWT。另外，网络往返多意味着客户端超时时间要调大，Java驱动里建议把LWT的request timeout设为普通写的3到5倍。下面的配置片段展示了在yaml里调整相关参数。
# cassandra.yaml 相关调优项 paxos_purge_grace_period: 86400 # 驱动侧超时（application.conf 示例） basic.request.timeout = 10 seconds basic.request.extended-verbosity = true
最后要强调，IF NOT EXISTS不是分布式锁的替代品。它只保证“插入那一下”的串行判断，插入成功后后续并发更新依然要靠应用层版本号或条件更新来约束。把LWT当成全局锁来设计系统，往往会把集群拖垮。合理评估冲突概率，只在真正低冲突且强一致要求的创建环节使用，才能既安全又高效。
Cassandralightweight_transactionIF_NOT_EXISTS修改时间：2026-08-14 01:33:33