【深度揭秘】Caffeine 缓存引发的内存泄漏全攻略：从根源到解决方案

前言

大家好！今天我要和你们分享一个在 Java 开发中常见但又容易被忽视的问题：Caffeine 缓存引起的内存泄漏。作为目前 Java 生态中性能最强的本地缓存库，Caffeine 被广泛应用于各种项目中。但是，如果使用不当，它可能会变成你系统中的"内存黑洞"。

在这篇文章中，我会用通俗易懂的语言，结合实际案例，深入分析 Caffeine 缓存可能导致的内存泄漏问题，并提供针对性的解决方案。无论你是刚接触 Caffeine 的新手，还是已经在项目中大量使用的老手，这篇文章都值得一读。

Caffeine 简介

Caffeine 是一个高性能的 Java 缓存库，它提供了近乎最优的命中率，同时具有出色的读写性能。它的设计灵感来源于 Google 的 Guava Cache，但在性能和功能上有了显著提升。

graph TD
    A[应用程序] -->|读/写| B[Caffeine缓存]
    B -->|命中| A
    B -->|未命中| C[数据源]
    C -->|加载数据| B
    B -->|过期/驱逐| D[GC回收]

Caffeine 的核心特性包括：

• 自动加载
• 基于大小、时间和引用的驱逐策略
• 统计和监控功能
• 异步刷新
• 写入传播

内存泄漏的根本原因

在讨论具体案例前，我们先来理解一下，为什么使用 Caffeine 会导致内存泄漏？

内存泄漏本质上是指那些不再需要的对象无法被垃圾回收器回收，从而占用着宝贵的内存空间。当使用缓存时，我们主动将对象保留在内存中，这本身就与垃圾回收的目标相悖。

graph LR
    A[正常对象] -->|不再使用| B[可回收]
    C[缓存对象] -->|仍被缓存引用| D[不可回收]
    D -->|缓存满/过期| B
    D -->|缓存配置不当| E[内存泄漏]

使用 Caffeine 时，以下几种情况容易导致内存泄漏：

1. 缓存无上限且没有合理的过期策略
2. 键值对象设计不当，导致意外的引用保留
3. 缓存的生命周期管理不当
4. 线程本地缓存未正确清理

接下来，我们通过具体案例来分析这些问题。

案例一：无上限缓存导致的内存泄漏

问题描述

小王在开发一个用户信息查询系统时，为了提高性能，使用了 Caffeine 缓存用户数据。他的实现代码如下：

// 错误示例
Cache<String, UserInfo> userCache = Caffeine.newBuilder()
    .build();

public UserInfo getUserInfo(String userId) {
    return userCache.get(userId, key -> loadUserFromDatabase(key));
}

系统上线后，随着用户量增加，应用服务器的内存使用率不断攀升，最终导致了 OutOfMemoryError。

问题分析

小王的代码看似简单，但埋下了严重的内存隐患：

1. 没有设置缓存大小上限
2. 没有设置过期策略
3. 没有任何驱逐机制

随着越来越多的用户数据被加载到缓存中，内存不断增长，而没有任何机制能够清理这些缓存项，最终导致内存溢出。

graph TD
    A[用户请求] -->|查询用户| B[Caffeine缓存]
    B -->|缓存未命中| C[数据库]
    C -->|加载数据| D[添加到缓存]
    D -->|无上限| E[缓存持续增长]
    E -->|内存耗尽| F[OutOfMemoryError]

解决方案

修改缓存配置，添加合理的大小限制和过期策略：

// 正确示例
Cache<String, UserInfo> userCache = Caffeine.newBuilder()
    .maximumSize(10000)           // 设置缓存大小上限
    .expireAfterWrite(1, TimeUnit.HOURS)  // 写入一小时后过期
    .recordStats()                // 记录统计信息，便于监控
    .build();

public UserInfo getUserInfo(String userId) {
    return userCache.get(userId, key -> loadUserFromDatabase(key));
}

这样配置后，缓存会自动控制大小，并且过期的项会被自动清理，有效防止内存无限增长。

案例二：大对象作为键导致的内存泄漏

问题描述

小李开发了一个文档处理系统，使用 Caffeine 缓存处理结果。为了提高缓存命中率，他使用文档对象作为缓存键：

// 有问题的代码
Cache<Document, ProcessResult> resultCache = Caffeine.newBuilder()
    .maximumSize(1000)
    .build();

public ProcessResult processDocument(Document doc) {
    return resultCache.get(doc, this::processDocumentInternal);
}

系统运行一段时间后，发现内存使用异常，即使设置了缓存大小，内存使用仍不断增长。

问题分析

问题的本质在于使用了包含大量数据的 Document 对象作为缓存键。即使 Document 类正确实现了 equals 和 hashCode 方法：

public class Document {
    private String id;
    private String title;
    private byte[] content; // 可能很大，例如几MB的文档内容

    @Override
    public boolean equals(Object obj) {
        if (obj instanceof Document) {
            return ((Document) obj).id.equals(this.id);
        }
        return false;
    }

    @Override
    public int hashCode() {
        return id.hashCode();
    }
}

这里的根本问题是：缓存会持有对键对象的强引用。当每次调用processDocument方法时，都会创建一个新的 Document 实例作为键。虽然由于 equals/hashCode 的实现，缓存能够识别出这些 Document 对象逻辑上是相同的（相同 id），但缓存依然会持有这些对象的引用，阻止它们被垃圾回收。

随着时间推移，大量包含文档内容的 Document 对象在内存中积累，尽管从缓存逻辑上看只有 1000 个条目，但实际上可能有成千上万个 Document 对象无法被回收。

graph TD
    A[新Document对象] -->|作为缓存键| B[Caffeine缓存]
    C[另一个Document对象] -->|相同id| B
    D[更多Document对象...] -->|相同id| B
    B -->|持有强引用| E[大量Document对象滞留]
    E -->|每个包含大量数据| F[内存泄漏]

解决方案

有两种解决方法：

1. 使用文档 ID 作为缓存键，而不是整个 Document 对象：

// 方案一：使用ID作为键
Cache<String, ProcessResult> resultCache = Caffeine.newBuilder()
    .maximumSize(1000)
    .build();

public ProcessResult processDocument(Document doc) {
    return resultCache.get(doc.getId(), id -> processDocumentInternal(doc));
}

2. 如果必须使用 Document 对象的更多信息作为键，创建轻量级的键对象：

// 方案二：使用轻量级对象作为键
public class DocumentKey {
    private final String id;
    private final String title; // 如需使用title作为键的一部分

    public DocumentKey(Document doc) {
        this.id = doc.getId();
        this.title = doc.getTitle();
    }

    @Override
    public boolean equals(Object obj) {
        if (obj instanceof DocumentKey) {
            DocumentKey other = (DocumentKey) obj;
            return this.id.equals(other.id) && this.title.equals(other.title);
        }
        return false;
    }

    @Override
    public int hashCode() {
        return Objects.hash(id, title);
    }
}

Cache<DocumentKey, ProcessResult> resultCache = Caffeine.newBuilder()
    .maximumSize(1000)
    .build();

public ProcessResult processDocument(Document doc) {
    DocumentKey key = new DocumentKey(doc);
    return resultCache.get(key, k -> processDocumentInternal(doc));
}

这两种方案都避免了在缓存键中包含大量数据（如文档内容），从而大大减少了内存占用。

案例三：值引用管理不当导致的内存泄漏

问题描述

小张在开发一个图像处理系统，使用 Caffeine 缓存处理后的大型图像：

// 有问题的代码
Cache<String, ProcessedImage> imageCache = Caffeine.newBuilder()
    .maximumSize(100)
    .build();

public ProcessedImage getProcessedImage(String imageId) {
    return imageCache.get(imageId, id -> {
        Image originalImage = loadOriginalImage(id);
        return processImage(originalImage);
    });
}

尽管设置了缓存大小限制，系统运行一段时间后仍然出现内存问题。

问题分析

问题出在 ProcessedImage 类的实现上：

public class ProcessedImage {
    private Image originalImage;  // 引用了原始图像
    private byte[] processedData; // 处理后的数据

    public ProcessedImage(Image originalImage, byte[] processedData) {
        this.originalImage = originalImage;  // 持有原始图像的引用
        this.processedData = processedData;
    }

    // 其他方法...
}

ProcessedImage 对象不仅包含处理后的数据，还持有对原始图像的引用。这意味着即使缓存控制了 ProcessedImage 对象的数量，每个缓存项仍然间接引用了大量内存（原始图像数据）。

graph TD
    A[缓存] -->|存储| B[ProcessedImage]
    B -->|引用| C[原始Image对象]
    B -->|包含| D[处理后数据]
    C -->|包含| E[原始图像数据]
    F[内存占用] -->|来自| D
    F -->|来自| E

解决方案

修改 ProcessedImage 类，不再持有原始图像的引用：

// 改进的ProcessedImage类
public class ProcessedImage {
    private byte[] processedData; // 仅保存处理后的数据

    public ProcessedImage(byte[] processedData) {
        this.processedData = processedData;
    }

    // 其他方法...
}

// 改进的缓存使用
public ProcessedImage getProcessedImage(String imageId) {
    return imageCache.get(imageId, id -> {
        Image originalImage = loadOriginalImage(id);
        byte[] processedData = processImage(originalImage);
        return new ProcessedImage(processedData);
        // originalImage可以被垃圾回收
    });
}

这样，当缓存方法返回后，原始图像对象就可以被垃圾回收，大大减少了内存占用。

案例四：线程本地缓存未正确清理

问题描述

小赵在开发一个高并发处理系统，为了避免线程间的缓存竞争，他为每个线程创建了专属的 Caffeine 缓存：

// 有问题的代码
private static final ThreadLocal<Cache<String, ExpensiveObject>> THREAD_LOCAL_CACHE =
    ThreadLocal.withInitial(() -> Caffeine.newBuilder()
        .maximumSize(1000)
        .build());

public ExpensiveObject processData(String key) {
    Cache<String, ExpensiveObject> cache = THREAD_LOCAL_CACHE.get();
    return cache.get(key, this::loadExpensiveObject);
}

系统测试中发现，即使负载降低，内存占用却持续增长，服务器长时间运行后最终出现 OOM 错误。特别是在使用线程池的环境中，线程池中的线程会被重用，若不清理 ThreadLocal，缓存实例会随着线程长期存活，导致内存累积。

问题分析

问题在于使用了 ThreadLocal 来存储 Caffeine 缓存实例，但是没有正确清理这些实例。在使用线程池的环境中（如应用服务器），线程不会结束，而是会被重用。因此，每个线程都会持有一个 Caffeine 缓存实例，随着时间推移，这些缓存实例会累积大量数据。

graph TD
    A[线程池] -->|包含| B[线程1]
    A -->|包含| C[线程2]
    A -->|包含| D[线程N]
    B -->|持有| E[ThreadLocal<Cache>]
    C -->|持有| F[ThreadLocal<Cache>]
    D -->|持有| G[ThreadLocal<Cache>]
    E -->|引用| H[Caffeine缓存实例1]
    F -->|引用| I[Caffeine缓存实例2]
    G -->|引用| J[Caffeine缓存实例N]
    H -->|存储| K[大量缓存项]
    I -->|存储| L[大量缓存项]
    J -->|存储| M[大量缓存项]

即使单个缓存实例设置了大小限制，但当有大量线程时，总的内存占用仍然会很高。而且，如果线程处理完某个任务后被放回线程池，其 ThreadLocal 中的缓存不会被清理，导致缓存数据长期存在。

解决方案

推荐以下两种解决方法：

1. 每次使用后清理 ThreadLocal：

// 方案一：使用后清理（推荐）
public ExpensiveObject processData(String key) {
    try {
        Cache<String, ExpensiveObject> cache = THREAD_LOCAL_CACHE.get();
        return cache.get(key, this::loadExpensiveObject);
    } finally {
        // 使用后清理
        THREAD_LOCAL_CACHE.remove();
    }
}

2. 使用共享缓存，而非线程本地缓存：

// 方案二：使用并发安全的共享缓存（推荐）
private static final Cache<String, ExpensiveObject> SHARED_CACHE =
    Caffeine.newBuilder()
        .maximumSize(5000) // 适当增加大小限制
        .build();

public ExpensiveObject processData(String key) {
    return SHARED_CACHE.get(key, this::loadExpensiveObject);
}

3. 定期清理所有线程的缓存（仅供参考，实际实现复杂且可能不可靠）：

// 方案三：定期清理（仅示意，实际中需结合具体场景设计）
private static final ScheduledExecutorService CLEANER =
    Executors.newSingleThreadScheduledExecutor();

static {
    // 每小时清理一次
    CLEANER.scheduleAtFixedRate(() -> {
        // 注意：实际实现中，通过反射访问所有线程的ThreadLocal是复杂且不可靠的
        // 在生产环境中，应优先考虑方案一或方案二
    }, 1, 1, TimeUnit.HOURS);
}

建议避免使用 ThreadLocal 存储缓存实例，改用共享缓存。如果确实需要线程隔离，应确保在使用后及时清理。线程本地缓存应只用于数据具有强线程隔离性且生命周期短于线程的场景。

案例五：自定义加载器导致的内存泄漏

问题描述

小陈实现了一个数据分析系统，使用 Caffeine 缓存分析结果。他使用了自定义的 CacheLoader：

// 有问题的代码
LoadingCache<String, AnalysisResult> analysisCache = Caffeine.newBuilder()
    .maximumSize(500)
    .build(new CacheLoader<String, AnalysisResult>() {
        private final DataProcessor processor = new ExpensiveDataProcessor();

        @Override
        public AnalysisResult load(String key) {
            Data data = fetchData(key);
            return processor.analyze(data);
        }
    });

系统运行后内存占用异常高，即使在缓存项被驱逐后也没有释放预期的内存量。

问题分析

问题在于使用了非静态内部类（匿名内部类）作为 CacheLoader。非静态内部类会隐式持有对外部类实例的引用。此外，DataProcessor 是一个重量级对象，包含大量资源：

public class ExpensiveDataProcessor {
    private final byte[] largeBuffer = new byte[100 * 1024 * 1024]; // 100MB缓冲区
    private final Map<String, Object> processingState = new HashMap<>();

    // 其他字段和方法...
}

即使缓存项被驱逐，CacheLoader 对象仍然存在，它引用的 ExpensiveDataProcessor 也无法被垃圾回收，导致内存泄漏。

graph TD
    A[Caffeine缓存] -->|持有| B[CacheLoader<br>非静态内部类]
    B -->|隐式引用| C[外部类实例]
    B -->|包含| D[ExpensiveDataProcessor]
    D -->|包含| E[100MB缓冲区]
    D -->|包含| F[处理状态Map]

解决方案

有三种方案可以解决这个问题：

1. 使用 Lambda 表达式（不会持有外部类引用）：

// 方案一：使用Lambda表达式
LoadingCache<String, AnalysisResult> analysisCache = Caffeine.newBuilder()
    .maximumSize(500)
    .build(key -> {
        // 只在需要时创建处理器
        DataProcessor processor = new ExpensiveDataProcessor();
        Data data = fetchData(key);
        return processor.analyze(data);
        // 方法结束后，局部变量processor会自动超出作用域，允许GC回收
    });

2. 使用静态内部类（不持有外部类引用）：

// 方案二：使用静态内部类
private static class AnalysisLoader implements CacheLoader<String, AnalysisResult> {
    @Override
    public AnalysisResult load(String key) {
        // 只在需要时创建处理器
        DataProcessor processor = new ExpensiveDataProcessor();
        Data data = fetchData(key);
        return processor.analyze(data);
        // 方法结束后，processor可以被垃圾回收
    }
}

LoadingCache<String, AnalysisResult> analysisCache = Caffeine.newBuilder()
    .maximumSize(500)
    .build(new AnalysisLoader());

3. 使用独立类（与内部类分离）：

// 方案三：使用独立类
public class AnalysisLoader implements CacheLoader<String, AnalysisResult> {
    @Override
    public AnalysisResult load(String key) {
        DataProcessor processor = new ExpensiveDataProcessor();
        Data data = fetchData(key);
        return processor.analyze(data);
    }
}

LoadingCache<String, AnalysisResult> analysisCache = Caffeine.newBuilder()
    .maximumSize(500)
    .build(new AnalysisLoader());

这些方案都避免了缓存长期持有对大型资源的引用，从而防止内存泄漏。

如何检测和监控 Caffeine 内存泄漏

发现和定位 Caffeine 相关的内存泄漏，可以使用以下技术：

1. JVM 内存监控

使用工具如 VisualVM、JConsole 或 Java Mission Control 来监控 JVM 内存使用情况。观察内存使用趋势，特别是老年代的增长情况。

graph LR
    A[应用运行] -->|产生| B[内存使用数据]
    B -->|监控| C[VisualVM/JConsole]
    C -->|分析| D[内存趋势]
    D -->|识别| E[潜在泄漏]

2. 堆转储分析

当怀疑存在内存泄漏时，生成堆转储并使用如 MAT(Memory Analyzer Tool)等工具分析：

// 在代码中触发堆转储
java.lang.management.ManagementFactory.getMemoryMXBean().dumpHeap("leak.hprof");

// 或使用jmap命令
// jmap -dump:format=b,file=heap.bin <pid>

在 MAT 中寻找 Caffeine 缓存相关的对象，检查它们的保留大小和引用链。

3. 启用 Caffeine 统计

Caffeine 提供了内置的统计功能，可以帮助你了解缓存的使用情况：

Cache<Key, Value> cache = Caffeine.newBuilder()
    .maximumSize(10_000)
    .recordStats()
    .build();

// 获取统计信息
CacheStats stats = cache.stats();
System.out.println("缓存大小: " + cache.estimatedSize());
System.out.println("命中率: " + stats.hitRate());
System.out.println("驱逐次数: " + stats.evictionCount());

观察缓存大小、命中率和驱逐次数，可以帮助你判断缓存是否按预期工作。

4. 添加 JMX 监控

将 Caffeine 缓存暴露为 JMX MBean，便于实时监控：

// 首先定义一个MXBean接口
public interface CacheStatsMXBean {
    long getSize();
    double getHitRate();
    long getEvictionCount();
    // 其他需要暴露的统计方法...
}

// 实现该接口
public class CacheStatsBean implements CacheStatsMXBean {
    private final Cache<?, ?> cache;

    public CacheStatsBean(Cache<?, ?> cache) {
        this.cache = cache;
    }

    @Override
    public long getSize() {
        return cache.estimatedSize();
    }

    @Override
    public double getHitRate() {
        return cache.stats().hitRate();
    }

    @Override
    public long getEvictionCount() {
        return cache.stats().evictionCount();
    }
    // 其他实现...
}

// 注册MBean
MBeanServer mBeanServer = ManagementFactory.getPlatformMBeanServer();
ObjectName name = new ObjectName("com.example:type=Cache,name=userCache");
StandardMBean mbean = new StandardMBean(new CacheStatsBean(cache), CacheStatsMXBean.class);
mBeanServer.registerMBean(mbean, name);

// 定期更新统计信息
ScheduledExecutorService executor = Executors.newSingleThreadScheduledExecutor();
executor.scheduleAtFixedRate(() -> {
    // 统计信息会自动更新，无需额外操作
}, 1, 1, TimeUnit.MINUTES);

预防 Caffeine 内存泄漏的策略

1. 合理配置缓存大小

始终设置最大缓存大小，基于预期的使用场景和可用内存：

Cache<Key, Value> cache = Caffeine.newBuilder()
    .maximumSize(10_000)  // 硬性限制
    // 或基于权重
    .maximumWeight(10_000_000)
    .weigher((key, value) -> value.getSize())
    .build();

2. 使用合适的过期策略

根据数据的新鲜度需求，配置适当的过期策略：

Cache<Key, Value> cache = Caffeine.newBuilder()
    .expireAfterWrite(10, TimeUnit.MINUTES)    // 写入后过期
    .expireAfterAccess(5, TimeUnit.MINUTES)    // 访问后过期
    .expireAfter(new Expiry<Key, Value>() {    // 自定义过期策略
        @Override
        public long expireAfterCreate(Key key, Value value, long currentTime) {
            return value.getExpirationNanos();
        }
        // 其他方法...
    })
    .build();

3. 使用弱引用

当缓存项的生命周期应该与外部对象相关联时，使用弱引用：

Cache<Key, Value> cache = Caffeine.newBuilder()
    .weakKeys()       // 当键不再被外部引用时，缓存项可以被回收
    .weakValues()     // 当值不再被外部引用时，缓存项可以被回收
    .build();

弱引用详解

• 重要提示：弱引用不应该是解决内存问题的主要策略，应优先考虑合理的大小限制和过期策略。弱引用应作为补充机制使用。
• 弱键（weakKeys）：当键对象在缓存外部没有强引用时，相应的缓存项将在下一次 GC 时被回收，即使该缓存未达到大小限制或未过期。适用于键对象生命周期由外部控制的场景，例如当键是临时对象或由其他组件管理的对象时。
• 弱值（weakValues）：当值对象在缓存外部没有强引用时，相应的缓存项将在下一次 GC 时被回收。适用于希望缓存不影响值对象正常生命周期的场景，例如当缓存是对象的"次要"引用来源时。

• 使用注意：

  • 弱引用的回收时机由 GC 决定，不保证即时清理
  • 弱引用会增加 GC 压力
  • 弱键对象仍需正确实现equals/hashCode，以确保缓存键的唯一性和正确性

graph TD
    A[Caffeine缓存] -->|强引用| B[普通键/值]
    A -->|弱引用| C[弱键/值]
    D[外部引用] -->|强引用| B
    D -.->|移除引用| B
    E[外部引用] -->|强引用| C
    E -.->|移除引用| F[GC回收]
    F -->|回收| C

4. 定期手动清理

对于长时间运行的应用，可以定期手动清理缓存：

// 定期执行清理
ScheduledExecutorService executor = Executors.newSingleThreadScheduledExecutor();
executor.scheduleAtFixedRate(() -> {
    cache.cleanUp();
}, 1, 1, TimeUnit.HOURS);

5. 使用轻量级键和值对象

设计专用的缓存键和值对象，避免无意中引用大对象：

// 轻量级缓存键
public class UserCacheKey {
    private final String userId;

    public UserCacheKey(String userId) {
        this.userId = userId;
    }

    // equals和hashCode实现...
}

// 使用
Cache<UserCacheKey, UserData> cache = Caffeine.newBuilder()
    .maximumSize(10_000)
    .build();

总结

下面通过表格总结本文的主要内容：

问题类型	表现症状	原因分析	解决方案
无上限缓存	内存持续增长，最终 OOM	未设置大小限制和过期策略	设置 maximumSize 和过期时间
大对象作为键	内存使用超出预期	缓存持有大对象键的强引用	使用轻量级键（如 ID）替代大对象
值引用管理不当	内存使用超出预期	缓存值对象引用了其他大对象	重新设计值对象，避免不必要引用
线程本地缓存未清理	线程池环境下内存持续增长	ThreadLocal 中的缓存未被释放	使用后清理或改用共享缓存
非静态内部类加载器	缓存驱逐后内存未释放	内部类隐式持有外部类引用	使用 Lambda、静态内部类或独立类

通过本文的学习，你应该能够更好地理解和避免 Caffeine 缓存中的内存泄漏问题。缓存是把双刃剑，用好了可以大幅提升性能，用不好则可能引入难以排查的内存问题。希望这篇文章对你有所帮助！

---

感谢您耐心阅读到这里！如果觉得本文对您有帮助，欢迎点赞 👍、收藏 ⭐、分享给需要的朋友，您的支持是我持续输出技术干货的最大动力！

如果想获取更多 Java 技术深度解析，欢迎点击头像关注我，后续会每日更新高质量技术文章，陪您一起进阶成长～