Java 本地 TTL 缓存小项目：用 ConcurrentHashMap 实现过期淘汰和命中统计

接口里经常会遇到一类很小但很实际的缓存需求：某个配置、用户临时状态、验证码结果或接口短期响应，只想在本机保存几十秒到几分钟。直接上外部缓存当然可以，但学习阶段更适合先把“写入、过期、读取、统计”这条链路自己走一遍。

这篇文章用一个可运行的小项目实现 Java 本地 TTL 缓存。它不是为了替代成熟缓存库，而是帮助你看清本地缓存的基本骨架：数据怎么存、过期怎么判断、读到旧数据时怎么清理，以及最终怎么确认结果正确。

项目目标：做一个最小可用的 TTL 缓存

TTL 是 Time To Live 的缩写，可以理解为一条缓存记录能存活多久。我们要做的项目只保留四个能力：

• put：写入 key、value 和存活时间。
• get：读取 value，过期时返回空结果。
• cleanup：主动清理已经过期的记录。
• stats：查看命中、未命中、过期清理次数。

这四个能力足够支撑一个小型本地缓存的学习闭环。先看整体数据流：

环境准备：只需要 JDK 和一个目录

这个示例不依赖 Maven，也不引入第三方库。你只需要本机已经安装 JDK 17 或更高版本，然后创建一个空目录：

mkdir ttl-cache-demo
cd ttl-cache-demo
touch LocalTtlCache.java

确认 Java 命令可用：

java -version
javac -version

如果这两条命令都能输出版本号，就可以继续写代码。

核心代码：缓存条目、读写方法和过期判断

先把完整代码放到 LocalTtlCache.java。核心思路是用 ConcurrentHashMap 保存缓存条目，条目里除了 value，还保存一个到期时间戳。

import java.time.Duration;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicLong;

public class LocalTtlCache {
    private final Map> store = new ConcurrentHashMap();
    private final AtomicLong hitCount = new AtomicLong();
    private final AtomicLong missCount = new AtomicLong();
    private final AtomicLong removedCount = new AtomicLong();

    public void put(K key, V value, Duration ttl) {
        if (ttl == null || ttl.isZero() || ttl.isNegative()) {
            throw new IllegalArgumentException("ttl must be positive");
        }
        long expireAt = System.currentTimeMillis() + ttl.toMillis();
        store.put(key, new Entry(value, expireAt));
    }

    public Optional get(K key) {
        Entry entry = store.get(key);
        if (entry == null) {
            missCount.incrementAndGet();
            return Optional.empty();
        }
        if (entry.isExpired()) {
            store.remove(key, entry);
            missCount.incrementAndGet();
            removedCount.incrementAndGet();
            return Optional.empty();
        }
        hitCount.incrementAndGet();
        return Optional.of(entry.value());
    }

    public int cleanup() {
        int before = store.size();
        store.entrySet().removeIf(item -> item.getValue().isExpired());
        int removed = before - store.size();
        removedCount.addAndGet(removed);
        return removed;
    }

    public String stats() {
        return "size=" + store.size()
                + ", hit=" + hitCount.get()
                + ", miss=" + missCount.get()
                + ", removed=" + removedCount.get();
    }

    private record Entry(V value, long expireAt) {
        boolean isExpired() {
            return System.currentTimeMillis() >= expireAt;
        }
    }

    public static void main(String[] args) throws Exception {
        LocalTtlCache cache = new LocalTtlCache();

        cache.put("token:1001", "ok", Duration.ofMillis(800));
        System.out.println("first read: " + cache.get("token:1001").orElse("empty"));
        System.out.println("after first read: " + cache.stats());

        Thread.sleep(1000);
        System.out.println("second read: " + cache.get("token:1001").orElse("empty"));
        System.out.println("after second read: " + cache.stats());

        cache.put("config:site", "dark-mode", Duration.ofSeconds(5));
        System.out.println("cleanup removed: " + cache.cleanup());
        System.out.println("final stats: " + cache.stats());
    }
}

这里有三个细节值得注意：

• get 方法不是简单取值，而是先判断记录是否已经过期。
• 过期记录会在读取时顺手移除，避免旧数据长期留在内存里。
• cleanup 是主动清理入口，适合在业务空闲点或固定维护流程里调用。

本地运行：观察命中、未命中和过期

编译并运行这个单文件项目：

javac LocalTtlCache.java
java LocalTtlCache

你会看到类似输出：

first read: ok
after first read: size=1, hit=1, miss=0, removed=0
second read: empty
after second read: size=0, hit=1, miss=1, removed=1
cleanup removed: 0
final stats: size=1, hit=1, miss=1, removed=1

第一读取命中，等待 1 秒后第二次读取返回空结果，并把过期记录移除。这个结果说明 TTL 判断、生效清理和统计计数都已经串起来了。

集成方式：放到业务服务里的边界

如果要把它接入接口服务，建议把这个类作为一个单例组件使用，不要在每次请求里重新创建缓存对象。典型边界可以这样划分：

• 短期接口结果：key 使用 api:user:1001 这类业务前缀。
• 临时校验状态：value 只保存必要结果，不保存大对象。
• 配置快照：TTL 设置短一些，让配置有机会自然刷新。
• 内存保护：需要给项目补充最大容量限制，防止 key 数量无限增长。

本地缓存最大的边界是“只在当前进程内有效”。多台机器部署时，不同机器的缓存互不共享；如果业务要求全局一致，就应该改用 Redis 这类集中式缓存。

验收清单：确认缓存行为符合预期

最后用一张清单确认项目是否可用：

• 写入后立刻读取，应该返回原始 value。
• 超过 TTL 后读取，应该返回空结果。
• 过期读取后，缓存 size 应该减少。
• 命中、未命中、清理计数应该随着操作变化。
• 同一个 key 重复写入时，应该覆盖旧 value 和旧到期时间。

到这里，一个最小可用的 Java 本地 TTL 缓存就完成了。继续扩展时，可以加入最大容量、分段清理、缓存淘汰策略和指标上报，但这些都应该建立在本文这个最小模型已经验证通过的基础上。