在分布式系统中，高性能缓存 是保障系统响应速度的关键。在使用 Redis 的同时，很多开发者也希望在本地保留一个缓存副本，以进一步提升读写效率，降低 Redis 的访问频率。Redisson 提供了丰富的工具来简化这种需求的实现。

在这篇文章中，我们将介绍如何基于 Redisson 的 RMapCache 实现：

• 带有 TTL（过期时间）控制；
• 支持本地 LRU 缓存淘汰策略；
• 自动监听 Redis 数据变更并同步更新本地缓存；
• 并且只缓存设置了 TTL 的 key，防止无限制增长。

为什么不用 RLocalCachedMap？

Redisson 提供了 RLocalCachedMap 来实现本地缓存，但我们在使用过程中发现了一些问题：

• 异步 put 后远程 Redis 更新成功但本地未更新；
• Redis 中数据为字符串格式，但 RLocalCachedMap 读取失败；
• 结构内部使用 Lua 脚本做同步，有兼容性 bug（如 unpack 异常）；
• 不支持仅缓存 Redis 中有 TTL 的数据。

因此，我们决定舍弃 RLocalCachedMap，改为自己封装一个缓存类，只使用 RMapCache 加上 Caffeine 本地缓存实现相同甚至更灵活的能力。

最终方案：TTLLocalCachedMap

我们将该封装命名为 TTLLocalCachedMap，它具备以下特性：

• Redis 端使用 Redisson 提供的 RMapCache，天然支持 TTL；
• 本地缓存使用 Caffeine，支持 LRU 和 TTL；
• 自动监听 Redis 端的 put/remove 操作并同步本地缓存；
• 初始化时只预热 Redis 中有 TTL 的 key，避免缓存过多无用数据。

核心代码实现

import com.github.benmanes.caffeine.cache.*;
import org.redisson.api.*;
import org.redisson.api.listener.*;
import org.redisson.api.map.event.EntryCreatedListener;
import org.redisson.api.map.event.EntryExpiredListener;
import org.redisson.api.map.event.EntryRemovedListener;
import org.redisson.api.map.event.EntryUpdatedListener;
import org.redisson.client.codec.Codec;
import org.redisson.client.codec.StringCodec;

import java.util.Map;
import java.util.concurrent.*;
import java.util.function.Function;

public class TTLLocalCachedMap<K, V> {

    private final RMapCache<K, V> redisMap;
    private final Cache<K, V> localCache;

    public TTLLocalCachedMap(RedissonClient redisson, String mapName, Codec codec, long maxLocalSize, long localTTLSeconds) {
        this.redisMap = redisson.getMapCache(mapName, codec);

        this.localCache = Caffeine.newBuilder()
            .maximumSize(maxLocalSize)
            .expireAfterWrite(localTTLSeconds, TimeUnit.SECONDS)
            .build();

        preloadFromRedis();

        // 设置监听器：远端写入 -> 同步本地
        redisMap.addListener((EntryCreatedListener<K, V>) event -> cacheIfTtlSet(event.getKey()));
        redisMap.addListener((EntryUpdatedListener<K, V>) event -> cacheIfTtlSet(event.getKey()));
        redisMap.addListener((EntryRemovedListener<K, V>) event -> localCache.invalidate(event.getKey()));
        redisMap.addListener((EntryExpiredListener<K, V>) event -> localCache.invalidate(event.getKey()));
    }

    public TTLLocalCachedMap(RedissonClient redisson, String mapName, long maxLocalSize, long localTTLSeconds) {
        this(redisson, mapName, StringCodec.INSTANCE, maxLocalSize, localTTLSeconds);
    }

    private void preloadFromRedis() {
        Map<K, V> allEntries = redisMap.readAllMap();
        for (Map.Entry<K, V> entry : allEntries.entrySet()) {
            cacheIfTtlSet(entry.getKey());
        }
    }

    private void cacheIfTtlSet(K key) {
        long ttl = redisMap.remainTimeToLive(key);
        if (ttl > 0) {
            V value = redisMap.get(key);
            if (value != null) {
                localCache.put(key, value);
            }
        } else {
            localCache.invalidate(key);
        }
    }

    public void put(K key, V value, long ttl, TimeUnit unit) {
        redisMap.put(key, value, ttl, unit);
        if (ttl > 0) {
            localCache.put(key, value);
        }
    }

    public void put(K key, V value) {
        redisMap.put(key, value); // no TTL => 本地不缓存
        localCache.invalidate(key);
    }

    public CompletableFuture<Void> putAsync(K key, V value, long ttl, TimeUnit unit) {
        return redisMap.putAsync(key, value, ttl, unit)
            .toCompletableFuture()
            .thenAccept(r -> {
                if (ttl > 0) localCache.put(key, value);
            });
    }

    public V get(K key) {
        return localCache.get(key, k -> {
            long ttl = redisMap.remainTimeToLive(k);
            if (ttl > 0) {
                return redisMap.get(k);
            } else {
                return null;
            }
        });
    }

    public void remove(K key) {
        redisMap.remove(key);
        localCache.invalidate(key);
    }

    public void clear() {
        redisMap.clear();
        localCache.invalidateAll();
    }

    public boolean containsKey(K key) {
        return get(key) != null;
    }
}

总结

本方案舍弃了 RLocalCachedMap 的复杂同步机制，而选择自己组合 RMapCache + Caffeine 的方式构建本地缓存，带来以下优势：

• 更好的可控性（只缓存 TTL key）；
• 更灵活的替换策略（支持 LRU）；
• 更少的 bug；
• 更清晰的同步逻辑。

这是一个简单但有效的分布式缓存优化实践，推荐在高性能系统中采用这种方案，尤其在对 TTL 管理要求严格的场景中。

如果你有类似的分布式缓存需求，欢迎交流或评论探讨～

你是否也遇到过 Redisson 中 RLocalCachedMap 带来的坑呢？

实践建议

• 确保 key 的 TTL 设置正确，否则会被自动踢出本地缓存；
• Caffeine 中的 TTL 应比 Redis 稍短一些，防止读取已过期值；
• 使用一致的 Codec（如 StringCodec）避免序列化异常；
• 如果 Redis 中有大量无 TTL 的 key，可考虑定期清理或隔离管理；
• 在服务启动时调用 preloadFromRedis()，能避免首次读取时的性能抖动。