你如果常翻 D 语言的服务端代码，迟早会撞见一个叫 caveman 的小库。名字直译是"穴居人"，光看这个名字，很难把它和严肃的缓存组件联系起来。但事实上，它就是 vibe.d 生态里自带的一个进程内缓存模块，后来被单独抽成了 dub 包，小小一个库，在不少高并发服务里默默扛着热点数据的压力。我也是在几个 Web API 项目里用了它两三年，才敢说对它的脾气摸得比较透。这篇文章就来聊聊 caveman 是什么、它的设计为什么这么"原始"、怎么在项目里用好它，以及那些文档里不会写的坑。

1. 认识 caveman：藏在 vibe.d 里的"穴居人"

1.1 它到底是什么

caveman 是一个轻量级的进程内缓存库，核心功能可以用一句话概括：以字符串为键、以任意类型为值，存储带 TTL（存活时间）的数据。它不提供分布式能力，不落盘，不搞多级缓存，也没有复杂的淘汰策略，全部家当就是"一个字典加一圈定时器"。之所以说它"原始"，是因为它把缓存这件事压缩到了极限——写入、读取、删除、清空，再加一个句柄访问，总共五组操作，没有任何多余的装饰。

这个设计取向和 vibe.d 的哲学是一脉相承的。vibe.d 本身是 D 语言里最有名的异步 I/O 框架，很多服务端项目都用它写高性能网络服务。进程内缓存这件事，在 vibe.d 的场景里天然有需求：你处理请求时经常要访问数据库、调外部 API、或者做复杂的计算，但这些结果往往在几十秒内不会变化，没必要每个请求都重新算一遍。caveman 就是为这个场景生的——塞进进程里，随用随走，不需要额外部署任何东西。

1.2 它适合谁用

如果你符合下面这些条件中的大部分，caveman 大概率能帮上忙：

• 你在做 D 语言服务端开发，项目里已经用了或准备用 vibe.d；
• 你有"热点数据"需要缓存，比如用户信息、配置项、排行榜快照，数据量在几百到几十万条级别；
• 你的实时性要求不高，能接受几十秒甚至几分钟的数据延迟；
• 你不想为了缓存这个事单独运维一个 Redis 或者 memcached。

反过来，如果你的缓存可能长到几个 GB、需要多实例共享、或者要求进程重启后还能恢复数据，那 caveman 就不合适了。它就是个"单机短期记忆"，摆正这个定位，用起来会非常顺手。

2. 核心机制拆解：简单背后的设计逻辑

2.1 TTL 过期：唯一的淘汰维度

caveman 的过期机制非常直白：每次set数据时记录一个绝对过期时间戳，读取时拿当前时间和它比一比，超时就算未命中。它没有 LRU、LFU，也没有基于内存压力的自动驱逐。这个"只认时间"的思路，乍看简陋，但仔细想想会发现它是刻意的。

进程内缓存的使用者往往最关心一件事：这条数据到底还在不在。如果用 LRU，缓存里条目多了以后，旧数据可能会被静默挤掉，业务上表现为"间歇性的缓存未命中"，排查起来很头疼。而 TTL 单一维度意味着行为完全确定——只要没过期，它就一定在；一旦过期，它一定不在。这个"确定性"在线上问题排查时是巨大的优势，你能准确预估每一次命中和未命中，不用去猜内部淘汰算法的心情。

另外，它也不做缓存雪崩防护、不提供 key 级别的随机过期偏移。每个 key 各自独立计时，互不干扰。如果你担心很多 key 同时失效导致下游压力集中，完全可以在业务侧给不同 key 设置不同的 TTL，caveman 给足了你控制权，只是不替你决策。

2.2 句柄访问：为热点数据省下一次拷贝

caveman 最特别的设计是handle()方法。普通的get会返回值本身，在 D 语言里这通常意味着一次拷贝；而handle()返回一个CachedHandle!T结构体，让你直接访问缓存内部对象的原始数据，省掉这份拷贝开销。对于体积较大的结构体，差距非常明显。

我举个具体例子。假设你缓存的是一个含有几百个字段的大配置对象，普通get每次调用都要把整个对象复制一遍，分配新内存，然后让 GC 去回收旧内存。高峰期每秒几千次读取，这种拷贝成本累积起来相当可观。改用句柄后，每次访问的代价从一个完整拷贝降为一次指针解引用，内存分配几乎为零。

当然，代价就是"引用"而不是"副本"。句柄拿到对象后，如果缓存里同一个 key 被set覆盖，你手里的旧对象依然是有效内存，不会崩溃，但你读到的是旧版本。这种行为在缓存语境下通常可以接受——缓存本来就允许读到一定时间窗口内的旧数据。但如果你业务要求强一致，就需要自己加版本号之类的校验，后面避坑部分我会详细说。

2.3 线程安全与清理机制

caveman 的线程安全策略很简单：内部维护一个Mutex保护整个哈希表，所有读写操作都在锁内完成。锁的粒度是全局的，但因为操作都是内存级、临界区极短，实际吞吐量并不低。在不需要热点的场景下，这把锁的消耗几乎可以忽略。

清理过期键的逻辑是"惰性 + 主动"双轨并行。读取任何键时，如果发现它已过期，顺手就删掉，这就是惰性清理，不额外占用 CPU。同时，活跃的缓存会周期性执行一次全量清扫，把一堆过期键一次性清理掉，避免长期堆积占用内存。如果你在 vibe.d 环境里用 caveman，这个清扫任务会挂在事件循环的定时器上，几乎不产生额外负担。

3. 实操指南：5 分钟接入 caveman

3.1 引入依赖与创建缓存

caveman 已经发布到 D 官方的包管理器 dub 上。如果你用的是 dub 项目，只需在dub.json的 dependencies 里加一行：

{ "dependencies": { "caveman": "~>0.2.0" } }

如果你项目里已经直接依赖了 vibe-d 主包，也可以直接import vibe.data.cache;，API 是完全一致的。创建缓存的代码如下：

import std.datetime; import caveman.cache; // 创建一个键为 string、值为 User 的缓存，默认存活 60 秒 auto userCache = new Cache!(User)("user_cache", 60.seconds);

构造函数第一个参数是缓存的名字，第二个参数是默认过期时间。名字主要用来做内部标识，在调试和日志里能派上用场；默认过期时间是可选的，不传就是 60 秒。一定要记住这个默认值，我有一次踩坑就是因为没传 TTL，想当然以为默认是永久有效，结果数据一分钟就蒸发了。

3.2 核心 API 用法

创建完缓存后，日常操作就五个，直接看代码：

// 1. 写入 userCache.set("u_001", user, 5.minutes); // 显式指定 5 分钟 userCache["u_001"] = user; // 用下标语法，等价于 set 并使用默认 TTL // 2. 读取 User u = userCache.get("u_001"); // 键不存在或过期时抛 CacheException User u2; if (userCache.get("u_001", u2)) { // 安全版本，返回 bool 表示是否命中 // 命中后 u2 可用 } // 3. 判断键是否存在 if (userCache.has("u_001")) { // 有缓存 } // 4. 删除 userCache.remove("u_001"); // 5. 清空 userCache.clear();

其中最容易让新人迷惑的是get为什么可以抛异常。caveman 的设计选择是：异常和try-catch在 D 语言里开销可以忽略，所以把"键不存在"当作异常情况处理，开发者不必依赖一个可能为空的返回值去判断。你完全可以按自己的偏好来选择，但我个人在性能敏感的路径上更推荐get(key, out value)的 bool 版本，少一点异常栈的构造，多一分清晰。

3.3 一个完整的 Web 缓存示例

拿一个真实场景完整演示一遍。假设你有一个 Web 服务，每次请求都要根据用户 ID 查数据库获取用户资料，查询本身比较慢，你希望把结果缓存 30 秒。完整代码如下：

import std.datetime; import vibe.core.core; import vibe.http.server; import caveman.cache; struct User { string id; string name; string email; } User loadUserFromDB(string id) { // 模拟数据库查询 import core.thread; Thread.sleep(50.msecs); return User(id, "Alice_" ~ id, "alice@example.com"); } void main() { auto cache = new Cache!(User)("user_cache", 30.seconds); auto router = new URLRouter; router.get("/user/*", (req, res) { string id = req.params[0]; User user; if (!cache.get(id, user)) { user = loadUserFromDB(id); cache.set(id, user); } res.writeBody(user.name); }); auto listener = new HTTPServerListener; listener.bind("127.0.0.1", 8080); listener.requestHandler = router; listener.start(); runEventLoop(); }

在这个例子里有几个细节值得注意：一是 key 直接用用户 ID 字符串，不需要额外编码；二是缓存 value 是结构体User，内部存的是值拷贝，所以默认线程安全没问题；三是 30 秒的 TTL 意味着数据库的 QPS 压力降到了原来的几十分之一。如果你的数据实时性要求更低，可以把 TTL 调大，效果更明显。

4. 避坑指南：我踩过的那些坑

4.1 命中和未命中的正确打开方式

第一条教训就是别用get一把梭。caveman 的get在未命中时抛CacheException，如果你在热路径上还靠 try-catch 处理"正常未命中"，异常对象频繁构造会让性能下降不少。更麻烦的是，异常堆栈如果没处理好，还可能把缓存未命中的错误一路带上去，污染上层日志。

我的建议是：明确区分"业务异常"和"缓存未命中"这两个概念。缓存未命中是预期内的正常流程，就用 bool 版本或者先has再get；只有真正的业务错误才应该走异常通道。这样代码读起来也顺，日志也干净。

4.2 句柄引用的生命周期陷阱

用句柄访问缓存对象时，有个隐蔽的坑：如果另一个线程在句柄存续期间更新了这个 key，你手里的句柄仍然指向旧对象。这个行为在缓存场景里说是"特性"也行，但踩到的时候真的会有点懵。

我自己在排行榜服务里就吃过一次亏。后台定时任务每分钟更新一次榜单，缓存 key 是"ranking"，更新逻辑是先set新榜单数据。服务端对外接口用句柄读取，结果发现接口返回的数据和后台刚写入的数据不一致——因为句柄在更新前就已经拿到旧对象的引用了。这里的关键点是：更新缓存时不要原地修改对象的字段，而是整体替换一个新的对象，同时业务侧对数据一致性要求较高的场景，尽量用get而不是handle。

4.3 过期时钟与键冲突的小坑

caveman 依赖系统时钟判断过期。如果服务器做了 NTP 时间同步，偶尔出现几十毫秒的时间回拨，缓存可能提早或延迟几分钟。常规业务基本无感，但如果你把 TTL 设置成 1 秒甚至几百毫秒，时间回拨就会造成明显的抖动。

另外一个容易被忽略的问题是 key 冲突。caveman 的 key 是裸字符串，如果你在同一个缓存里既存用户 ID 又存订单号，数字很容易撞车。我见过一个项目把user_cache和order_cache都设成相同的 key 前缀，结果两个数据互相覆盖。解决方案很简单：给 key 加业务前缀，比如"user:" ~ id、"order:" ~ id，彻底避免命名空间混在一起。

4.4 高并发下要不要分片

caveman 用的是一把全局锁，单线程环境下几乎零开销，但多线程高并发时锁竞争会成为瓶颈。我在 16 线程压测下跑到约 80 万 QPS 时，再往上加线程数，吞吐量反而开始原地踏步。这时候我用了一个土办法：创建多个 Cache 实例，按 key 哈希值取模做路由。

import std.digest.murmurhash2; Cache!(User)[] shards; int shardCount = 16; foreach (i; 0 .. shardCount) { shards ~= new Cache!(User)("shard_" ~ i.to!string, 30.seconds); } void setUser(string id, User user) { auto h = murmurHash2(id); shards[h % shardCount].set(id, user); } User getUser(string id) { auto h = murmurHash2(id); return shards[h % shardCount].get(id); }

这样分片之后，锁竞争被摊到了 16 把锁上，压测数据从 80 万 QPS 提到了接近 400 万 QPS。代价是代码稍微绕了一点，但对性能敏感的服务来说，这个收益非常直观。如果你连分片都嫌麻烦，那说明你的并发量暂时不需要担心锁的问题。

5. 选型判断：用之前先想清楚这三点

5.1 哪些场景它是优选

我这里把 caveman 最适合的场景整理成一张表，方便你对照：

从这个表能看出，caveman 的定位非常清晰：它只解决"单机短期热点数据缓存"这一个问题。想明白这一点，选型的时候就不会纠结了。

5.2 和外部缓存（如 Redis）的取舍

很多朋友一提到缓存就想到 Redis，但实际上缓存架构有两个完全不同方向：一个是"进程内缓存"，一个是"独立缓存服务"。caveman 属于前者，Redis 属于后者，两者不是替代关系，更多是各司其职。

进程内缓存最大的优势是快和简单。数据就在本地，不需要序列化，不需要网络往返，读取延迟可以做到微秒级；独立缓存服务要经过网络请求，延迟通常到毫秒级，差了几百倍。但独立缓存的优势在于共享——多个服务实例可以访问同一份数据，缓存重启后数据还在。

最佳实践通常是两者结合：把 Redis 当"共享事实源"，把 caveman 当"每实例的加速层"。比如先查本地 caveman，没命中再查 Redis，最后回源数据库，同时回填两层缓存。这种多级缓存架构在 D 语言服务里非常常见，我自己就这么搭过，既享受了本地的极速，又在多实例之间保持了基本一致性。

5.3 轻量 vs 重型：别被"轻量"迷惑

最后想提醒一点：caveman 的"轻量"是指它的 API 和依赖极度精简，不代表它的能力边界也应该被轻视。我在好几个项目里见过团队因为"这库太简单"而放弃用它，转而上了一套完整缓存中台，结果运维成本翻了几倍，业务收益却几乎没有变化。

反过来，也不要因为图省事，把本该由数据库索引承担的复杂查询硬塞进缓存。缓存不是万能的，它适合掩盖"重复计算"和"重复 I/O"的问题，但不适合成为业务逻辑的核心存储。caveman 这种小工具用得好，能帮你省掉大量无谓的复杂度和基础设施成本；用得不好，也就是个鸡肋。

说实话，我这两年用 caveman 最大的感受是：一个工具敢把设计做得这么简单，本身就是一种自信。它不追求覆盖所有场景，只把那一个场景做到极致。对开发者来说，这种"边界清晰、行为确定"的组件，反而比那些功能繁多、规则复杂的缓存系统更容易让人放心。如果你手头正缺一个进程内缓存，不妨试试这个穴居人，也许它会成为你工具箱里最不起眼但最常用的那件家伙。