缓存这东西，用对了是加速器，用错了就是隐形炸弹。我之前维护活动系统时，遇到过一次线上事故：运营在后台把商品状态从“下架”改成“上架”，前端页面却迟迟不刷新，最后排查到下游定时任务用set把刚更新的状态又覆盖回了旧值。问题暴露得很典型——很多人对 Memcachedreplace命令的理解仅限于“可以更新缓存”，但真正到生产环境里，把它的语义和set分清、把它的边界条件吃透，才能避免同类问题。这篇文章我就把replace命令从使用姿势、协议参数、踩坑案例到源码行为完整讲一遍，希望能帮到正在用 Memcached 或者准备入手的同学。
1. replace命令解决的问题，远不止“更新缓存”这么简单
很多文档给replace的定义只有一句话：替换已存在的键。听起来理所当然，甚至有点多余——毕竟set也能覆盖已存在的键，那我为什么还要单独记一个replace？这套逻辑在单机单线程测试环境里没问题，一旦进入多服务、多线程、有淘汰和过期策略的生产环境，replace的语义价值就体现出来了。
1.1 一个让我记忆深刻的生产事故
事故背景是这样的：我们的商品服务里有一个状态机，商品状态依次是“待审核 -> 审核通过 -> 上架 -> 下架”。缓存 key 的格式是product:{id}:status，value 是状态枚举。运营在后台操作“上架”时，接口会写库然后更新缓存；与此同时，有一个定时任务在扫描待审核商品，把“超过72小时未审核”的商品自动驳回为“待审核”。定时任务的逻辑很简单：set(product:{id}:status, "待审核")。
看起来没问题对吧？但它用的就是全量覆盖的set。运营刚把状态改成“上架”，定时任务同一秒扫描到该商品之前处于“审核通过”状态，于是又用set写回了“待审核”。前端轮询到的缓存就一直是旧状态，直到缓存过期才恢复。这个问题的本质不是业务逻辑错误，而是写缓存时没有区分“我要确保覆盖一个已存在的值”和“我只想更新我预期的那个值”——这正是replace和set的核心分水岭。
1.2 replace的语义定位：只在“键已存在”时执行替换
replace的实际行为是：如果 key 存在，就用新 value 覆盖旧 value；如果 key 不存在，什么都不做，返回NOT_STORED。也就是说，它不是一个无条件的写操作，而是一个带前置条件“key 必须存在”的写操作。用数据库的话来类比，replace更像UPDATE WHERE key = XXX，而set是标准数据库里的UPSERT（存在则更新，不存在则插入）。
“Key 是否存在的判定”里面有一个容易被忽略的细节：如果 key 已经过期，Memcached 在内部执行惰性删除，逻辑上等同于不存在。你向一个已经过期的 key 发replace，返回的也是NOT_STORED，并不会因为“这个 key 以前存在过”就让你替换成功。这一点在下一节的过期时间参数里还会再强调。
从命令设计的历史来看，Memcached 最初只有set，后来才补充了add和replace。add解决的是“仅在不存在时写入”，replace解决的是“仅在存在时写入”，两者合在一起，才让缓存的写入从全量覆盖进化到了带条件写入，为分布式锁、状态机更新、防重复初始化这类场景提供了底层支持。
2. 命令格式与参数细节：flags不是摆设，exptime有隐藏规则
无论你用的是 telnet 手敲命令，还是通过 PHP、Python、Java 客户端调用，最终都会转换为 Memcached 的文本协议或者二进制协议。文本协议上手最快，也最适合排查问题，所以我先从文本协议讲起。
2.1 完整的文本协议格式
replace的文本协议格式如下：
replace <key> <flags> <exptime> <bytes>\r\n <data block>\r\n注意这里有两个\r\n。第一行是请求头，以\r\n结束；紧接着发送长度为<bytes>的数据块；数据块发送完毕后，再补一个\r\n表示数据结束。一个完整的 telnet 会话示例：
replace user:1001 0 0 4 男 STORED这里key是user:1001，flags是0，exptime是0（永不过期），bytes是4（“男”的 UTF-8 字节数是 6？这里注意，中文在 UTF-8 下是 3 字节一个字符，所以你要按实际字节数写），数据块是具体内容。
2.2 flags、exptime、bytes的隐藏规则
flags是一个 32 位无符号整数，Memcached 本身不关心它的值，只是在存储和返回时原样带出。很多语言客户端会把序列化方式、压缩标记、数据类型写进 flags，比如 flags=1 表示 JSON，flags=2 表示 MessagePack。实际踩坑点在于：如果你在一个客户端里设置数据时用了 flags，读取时必须从 Get 的返回里拿到 flags，否则可能无法反序列化。之前有个同事用set写数据时没经过统一封装，flags 写成了 0，但业务读取端用php-memcached扩展默认按 PHP 序列化格式解析，结果读到一堆乱码，排查了半天才发现 flags 不一致。
exptime是过期时间，规则如下：
| exptime 值 | 含义 |
|---|---|
| 0 | 永不过期 |
| 1 到 2592000（30天） | 相对时间，表示从现在起多少秒后过期 |
| 大于 2592000 | 绝对时间，Unix 时间戳 |
也就是说，你写replace key 0 3600 5表示一个小时后过期；如果是replace key 0 1893456000 5，表示的是 2030 年 1 月 1 日零点过期（按 Unix 时间戳算）。还有一点容易踩坑：replace 成功之后，key 的过期时间会被重置为本次命令里设置的 exptime，而不是保留原来的剩余时间。也就是说，你每次 replace 一个 key，就是给它续了一次命，即使那个 key 原本只剩 1 秒就过期了，replace 之后它又按你设置的过期时间重新计时了。这一点在下面的“踩坑记录”里会展开。
bytes是数据块的实际字节数，不是字符数。如果你存的是中文、emoji 或二进制内容，必须用字节数计算。发少了，Memcached 会等不到完整数据然后返回CLIENT_ERROR bad data chunk；发多了，多余的部分会被当成下一条命令解析，直接导致协议错乱。
2.3 STORED、NOT_STORED、EXISTS到底谁返回哪个
replace执行之后的响应码取决于当前状态：
| 响应码 | 触发条件 |
|---|---|
| STORED | key 存在，替换成功 |
| NOT_STORED | key 不存在，没有被存储 |
| CLIENT_ERROR | 数据格式错误，比如 bytes 和实际数据不一致 |
| SERVER_ERROR | 服务端问题，例如数据超过最大 item 大小（默认 1MB） |
这里特别提一下EXISTS，它主要用于cas命令，表示版本号冲突。文本协议下replace不会返回EXISTS，因为 replace 不带版本校验，它只关心 key 是否存在。如果你在代码里看到了对EXISTS的异常处理但又没用cas，那说明可能是你的客户端内部做了封装，需要去看客户端的源码。
3. 为什么说replace比set更适合“只更新已存在键”的场景
从表面语法上看，set和replace都可以覆盖一个已存在的 key，很多人觉得set就够了。但实际工程里，两者在“更新已存在的键”这个场景下行为差异非常大。
3.1 Upsert与条件更新的本质区别
set是 upsert 语义：key 不存在就创建，key 存在就覆盖。它天然适合“无论缓存里有没有，反正我要保证这条数据是我的最新值”这种场景，比如用户登录后更新他的 session 数据。
replace是条件更新：key 不存在就失败。它天然适合“缓存里必须已经有一条数据了，我才有资格更新它”这种场景，比如计数器累加、状态迁移、锁续期。用一个日常类比：set就像你走进自习室，不管有没有人占座，你坐下就说“这位置是我的了”；replace则像你预约了某个座位，只有确认座位牌上写的是你的名字，你才落座，否则连椅子都不能碰。
3.2 一个典型的伪代码对比
假设我们要实现“只有商品处于上架状态时，才允许更新库存缓存”：
# 错误的做法：无条件覆盖 memcached.set("product:1001:stock", 99) # 正确的做法：先查再替？不行，这种写法有竞态 stock = memcached.get("product:1001:stock") if stock is not None: memcached.set("product:1001:stock", 99)上面的“先查再替”在单线程里没问题，但并发环境下，两个线程同时 get 到旧值，然后都执行 set，后 set 的线程可能覆盖前一个线程基于旧值计算的库存，产生超卖。如果用replace，语义就变成了“只有缓存里已经有库存这个 key 了，我才能把新库存写进去”，至少保证了更新的前提条件是“key 存在”而不是“什么条件都没有”。
# 更合理的做法：用 replace 表达“只更新已存在的 key” stored = memcached.replace("product:1001:stock", 99) if not stored: # 说明缓存里还没有这个 key，需要先初始化 memcached.add("product:1001:stock", 99)3.3 并发场景下的语义差异
再想深一层：如果两个线程同时都要replace同一个 key，会发生什么？谁的replace最后执行，谁的值就生效，replace本身不提供任何版本校验，这跟set没有区别。所以在严格的并发控制场景下，replace替代不了cas。
但即便如此，replace的价值在于它划分了“写入的资格边界”：它可以保证一个本来就存在的 key 不会被误删或者跳过，也可以保证一个不存在的 key 不会被意外创建。比如，你做缓存预热时，先用add写入初始值，然后所有后续更新统一用replace，这样整个缓存的生命周期就是“创建 -> 更新 -> 过期”，逻辑非常清晰。而如果全程用set，一旦预热失败，后续的set会默默把 key 补上，掩盖了上游数据缺失的问题，反而不利于排障。
4. 真实踩坑记录：replace返回NOT_STORED之后怎么办
纸上谈兵到这里，分享几个我在生产环境里的实际踩坑案例。每一个都配上了解法和思路，希望能帮你省掉几晚上的排查时间。
4.1 场景一：缓存被淘汰后replace失败，需要回退策略
Memcached 内存管理的机制是 LRU + 过期惰性删除：内存不足时，最久未访问的 item 会被淘汰，即使它还没到过期时间。所以“key 存在”这个前置条件是脆弱的，一个 key 可能在没有任何人操作的情况下，突然被 LRU 淘汰掉。
我遇到的一个真实案子是：用户购物车的缓存 key，正常情况下设置 24 小时过期，但由于某个大促时段数据量暴涨，部分用户的购物车缓存被 LRU 提前淘汰。此时用户只要一加购，代码里执行的逻辑是replace(cart:{uid}, new_cart)，结果返回NOT_STORED，购物车在缓存层面就“丢”了。表面看用户没报错，但实际他的购物车加购操作没生效，数据在底层数据库里也是对的，只是缓存一直没更新。
解决办法是：replace失败之后，要么回退set/add重新初始化，要么捕获NOT_STORED后重新从数据库加载并add回去。但这里必须小心两个问题：
- 回退用
set会让“key 不存在”这个信号失效，等于把条件更新退化成了无脑更新。 - 回退用
add更合理，一旦并发情况下多个线程都发现replace失败，只有一个线程能add成功，其他线程会继续拿到NOT_STORED，但它们的作用本来只是“确保有一条数据”，所以失败也没关系。
4.2 场景二：replace也解决不了并发互相覆盖，要用cas
有一次做秒杀库存扣减，我用replace写剩余库存，逻辑是：先从库中读一次余量，扣减后再replace。看起来没问题，但高并发下一测试就出现了超卖。原因很简单：两个并发请求都读到了库存为 1，请求 A 扣减为 0 后replace成功，请求 B 基于旧的 1 再扣减也写成 0，但实际库存已经被扣了两次，业务上等于卖了两件只减了一次。
replace只保证“key 存在”才更新，不保证“value 是我上次读到的那个版本”。这种情况必须用cas（Compare And Swap），也就是 Memcached 里的gets+cas组合。gets会返回一个唯一版本号，cas带上这个版本号去更新，如果版本号不匹配就返回EXISTS，由业务层决定重试还是拒绝。这是我反复跟团队强调的一点：不要因为有了 replace 就把原语级别的并发控制忘掉，它们解决的是不同层次的问题。
4.3 场景三：bytes算错，replace直接CLIENT_ERROR
这个坑在写脚本或者 telnet 调试时最容易碰到。比如你想往 Memcached 里写一条中文数据，Python 里看字符串长度是 3，但用 UTF-8 编码后字节数是 9，如果命令里的 bytes 写 3，Memcached 会认为数据块还没结束，一直等不到结束符，最终返回CLIENT_ERROR bad data chunk。
实际操作里，bytes 应该是编码之后的数据长度：
import memcache value = "新的状态" raw = value.encode("utf-8") print(len(raw)) # 12，而不是 4 mc = memcache.Client(["127.0.0.1:11211"]) # 一定要传字节长度 mc._unsafe_set(b"key", raw)如果你的客户端已经封装好了 set/replace，它内部会自动处理编码问题。但如果你想通过 telnet 或者 netcat 手动发协议包，一定要先把数据编码好再数 bytes。
4.4 场景四：过期时间被重置，不是保留旧TTL
我刚用 replace 的时候有一种错觉：replace 只是更新 value，原来的过期时间应该保持不变。但实际行为是，replace 和 set 一样会应用你这次命令里的 exptime。也就是说，如果你每次 replace 都传了一个比较大的过期时间，那么这个 key 的理论过期时间会被不断往后推，相当于续期。
这在有些场景里是好事，比如活跃用户 session 续期。但在另一些场景里却是坏事，比如你想让一个 key“过期后自动消失”，但某个服务会定期对它执行 replace，导致它永远不过期。我曾经排查过一个缓存雪崩的前兆：某个排行榜缓存设计了 5 分钟过期，但由于刷榜任务每 1 分钟就 replace 一次并重置过期时间为 5 分钟，这个 key 实际上永远不会过期，一旦原服务重启，缓存里全是旧数据，直到手动清掉才恢复。
所以用 replace 之前想清楚：你重置过期时间的行为，是不是你想要的？如果不是，考虑是否应该只在 value 变化时才更新，而不是定时无条件 replace。
5. 调试与源码验证：从telnet到items.c把replace彻底看透
文字说了一堆，不如实际动手验证一次。这里给出一套完整的调试路径，从外部协议到内部源码，真正把 replace 的运行机制从外到内看透。
5.1 telnet直连Memcached实操
Memcached 默认端口是 11211，文本协议可以直接通过 telnet 调试（Windows 上记得先在“启用或关闭 Windows 功能”里打开 Telnet 客户端）。连上之后，先确认服务正常：
telnet 127.0.0.1 11211 stats看到STAT pid、STAT uptime说明服务正常。然后模拟一次完整的 replace 流程：
# 先塞一个 key set greeting 0 0 6 hello STORED # 用 replace 更新 replace greeting 0 0 6 world STORED # 用 get 验证 get greeting VALUE greeting 0 6 world END # 对不存在的 key 执行 replace replace not_exist_key 0 0 2 hi NOT_STORED这里有个细节：get greeting返回的第二行VALUE greeting 0 6中的0就是当时的 flags，最后面的6是字节数。如果之前用set时 flags 写的 1，get 时这里就会显示 1，客户端拿到这个值才能正确反序列化。
如果系统里没装 telnet，也可以配合 bash 自带的/dev/tcp来做快速验证：
exec 3<>/dev/tcp/127.0.0.1/11211 printf "replace dev_tcp_test 0 0 3\r\nbar\r\n" >&3 head -n 1 <&35.2 源码层面确认replace的“存在”判定
Memcached 的源码结构不算复杂，关键函数在items.c的do_store_item和proto/text.c（老版本在memcached.c）里的process_update_command。文本协议收到replace时，命令解析后会把操作类型标记为NREAD_REPLACE。核心逻辑大体是：先对 key 执行一次内部查找，如果 key 为空且操作类型是 replace，直接返回NOT_STORED，不会进入真正的存储流程。只有 key 存在，才会走item_replace或者类似的覆盖逻辑。
为什么要讲这个？因为“key 存在”的判定并不等于“内存里有一个没过期的 item”。Memcached 的 item 带有过期时间，查找时会做一次过期检查，如果发现已经过期，会先执行惰性删除，再返回空。所以你今天通过 telnet 手敲replace一个“你记得存在但已经过期”的 key，返回的一定是NOT_STORED。理解了这一点，你再看前面讲到的 LRU 淘汰场景，就会明白 replace 的“存在”前提比我们想象得更脆弱，也更需要配合 add/set 回退策略。
5.3 stats是验证replace行为的好帮手
调试完命令后，建议用stats命令观察 Memcached 的内部统计指标，重点看这几个：
| 指标 | 意义 |
|---|---|
| get_hits / get_misses | get 的命中与未命中情况 |
| delete_misses | 删除操作没有命中 key 的次数 |
| curr_items | 当前存储的 item 数量 |
| total_items | 累计存储的 item 数量 |
| expired_unfetched | 已过期但尚未被外部 get 读取到的 item 数量 |
一个典型的验证思路：先stats记录curr_items和total_items，然后对同一个 key 多次执行 set，你会发现curr_items不变但total_items增加；而对同一个 key 多次执行 replace，curr_items不变但total_items也不一定增加（视版本而定）。这个差异可以帮你确认你操作的是“创建”还是“替换”，尤其适合写脚本自动化验证大批量缓存操作时检查是否发生意外的新增。
6. 工程实践习惯：set、replace、add、cas该怎么选
最后聊聊我在实际编码中一直遵守的选择逻辑。Memcached 这几个写命令可以简单梳理成四种语义：
| 命令 | 语义 | 适用场景 |
|---|---|---|
| set | upsert，存在则覆盖，不存在则创建 | 普通缓存写入，可以无脑覆盖 |
| add | 仅在不存在时创建 | 缓存预热、分布式锁占位、避免并发重复初始化 |
| replace | 仅在存在时替换 | 只更新已存在的 key，不创建新 key |
| cas | 带版本校验的更新 | 并发场景下的强一致性更新 |
6.1 什么时候用replace
我一般在这种场景下优先选择 replace：
- 更新一个已经确认存在且应该由本次写操作独占的缓存对象；
- 做缓存续期，比如活跃用户 session、在线状态；
- 实现“只更新不新增”的业务约束，比如状态机流转，缓存里没有状态就不能生成新状态；
- 多服务之间对某个 key 的“存在性”有依赖，希望写操作在 key 被淘汰/过期时显式失败而不是默默创建。
用 replace 最大的价值不是性能，性能上和 set 没有本质差别；它的价值在于失败可见。NOT_STORED是一个明确的信号，它告诉你“这个 key 不在了”，你可以据此触发回源加载、重建缓存、或者告警。而 set 的静默创建会把这些问题掩盖掉。
6.2 什么时候用cas
如果你发现“两个服务同时更新同一个 key，谁后写谁赢”是不可接受的，那 cas 才是答案。cas 需要搭配 gets 使用，流程是：
value, cas_token = mc.gets("product:1001:stock") new_value = value - 1 result = mc.cas("product:1001:stock", new_value, cas_token) if not result: # 版本冲突，重读重试 ...cas 的重试逻辑要控制好次数，否则高并发下可能一直冲突。实际经验是重试 3 次以内，超过就直接返回失败或者走降级方案，不要在 cas 重试上消耗太多时间。
6.3 生产环境代码示例
下面是一段我比较推荐的缓存初始化加更新“模板”，把 add + replace + cas 都串起来了：
import memcache mc = memcache.Client(["127.0.0.1:11211"], socket_timeout=2) CACHE_KEY = "product:1001:stock" def init_cache(value: int) -> bool: """只有不存在的 key 才初始化，避免并发重复写""" return bool(mc.add(CACHE_KEY, value, time=3600)) def update_cache(value: int) -> bool: """只更新已存在的 key，失败时返回 False 由调用方处理""" return bool(mc.replace(CACHE_KEY, value, time=3600)) def update_with_retry(value: int, max_retry: int = 3) -> bool: """并发安全更新，使用 gets/cas""" for _ in range(max_retry): _, cas_token = mc.gets(CACHE_KEY) if cas_token is None: # key 不存在，先初始化 if not init_cache(value): continue return True if mc.cas(CACHE_KEY, value, cas_token, time=3600): return True return False这套模板把缓存的生命周期划分得很清晰：初始化走 add，普通更新走 replace，高并发更新走 cas。调用方不需要在业务代码里频繁判断 key 是否存在，成功和失败都由返回值明确表达，出了问题日志也容易定位。
6.4 最后的补充建议
我在实际运维中发现，很多 Memcached 分配的异常都源于对 flags 和 bytes 的忽视。如果你用的是字符串类型，一定要确认客户端在 get 时是否拿到了正确的 flags；如果你自己写协议解析器，一定要对 bytes 做异校验，防止数据错位。另外线上环境建议开启-o modern或按需调优 LRU 相关参数，避免热点 key 过早被淘汰，减少 replace 失败率。
回头看那场商品状态被覆盖的事故，其实只要当初写代码的同学把“更新缓存”从 set 换成 replace，并且做好 NOT_STORED 的回退处理，问题根本不会发生。缓存命令虽小，选错了就是线上事故，选对了就是让系统少一个隐患。希望这篇能帮你把 replace 这个命令用得明明白白，以后遇到“只更新已存在的 key”这种需求，第一反应不再是无脑 set。
