应使用 net.sf.ehcache:ehcache:2.10.9 并排除 Spring Boot 自动配置的 Ehcache 3，将 ehcache.xml 放入 classpath 根路径，确保 CacheManager Bean 名为 cacheManager，且 @Cacheable 用于 public 方法并经 Spring 代理调用。

如何在 Java 项目中正确引入 Ehcache 依赖

Ehcache 3 和 Ehcache 2 是完全不同的实现，XML 配置只在 Ehcache 2 中有效；如果你用的是 Maven，默认拉到的 ehcache 坐标（无 classifier）是 Ehcache 2，但 Spring Boot 2.0+ 默认集成的是 Ehcache 3（org.ehcache:ehcache），它不支持 XML 配置。

• 如果你明确要 XML 驱动的本地缓存（比如 legacy 系统迁移、团队熟悉 XML），必须锁定 Ehcache 2：net.sf.ehcache:ehcache:2.10.9
• Spring Boot 项目中，还需排除自动配置的 Ehcache 3：spring.cache.type=none，否则会冲突报错 CacheManager bean not found
• 不要混用 ehcache-core 和 ehcache，后者才含 XML 解析器和 CacheManager 实现

ehcache.xml 文件该放哪、怎么被加载

Ehcache 2 默认只从 classpath 根路径加载 ehcache.xml，不是任意位置都能自动识别。

• 文件必须放在 src/main/resources/ehcache.xml（Maven 结构下），不能叫 ehcache-config.xml 或放在 config/ 子目录
• 如果要用自定义路径，得手动初始化：CacheManager.newInstance("path/to/your/ehcache.xml")，但 Spring 环境下需配合 FactoryBean 或 @Bean 方法，否则 @Cacheable 注解不会生效
• 常见错误：IDE 编译后 ehcache.xml 没进 target/classes/ —— 检查 Maven 的 resources 配置是否过滤了 *.xml

XML 中 cache 配置的关键参数含义与误用点

maxElementsInMemory、overflowToDisk、eternal 这几个属性看着简单，但组合不当会导致缓存失效或 OOM。

JavaStoryDevelop

你接手一个需求时，是不是经常这样："改一个小字段 → 结果把不相关的代码也改了"、"需求说得很模糊 → 做着做着发现跑偏了"、"数据库加个字段 → 上线才发现漏了数据兼容"、"做了个新功能 → 一个月后自己都忘了当时怎么设计的"、"写到一半被中断 → 再回来不知道从哪继续"；这个 Skill 就是专门解决这些问题的。 它会自动探测你的项目环境（JDK、Spring Boot、ORM、数据库、前端框架），记在

下载

• maxElementsInMemory="1000" 是元素个数上限，不是内存字节数；单个对象太大时，实际堆内存可能远超预期
• overflowToDisk="true" 要求同时配置 diskStore path，且路径必须可写；若没配或路径无效，启动时无报错，但缓存满后直接丢弃数据（静默失败）
• eternal="false" 必须配 timeToIdleSeconds 或 timeToLiveSeconds，否则缓存项永不过期（即使写了 0，也代表“不限制”，不是“立即过期”）
• 示例片段：

  <cache name="userCache"
       maxElementsInMemory="500"
       overflowToDisk="true"
       diskStorePath="java.io.tmpdir"
       eternal="false"
       timeToIdleSeconds="60"
       timeToLiveSeconds="300" />

Spring 中启用 @Cacheable 但缓存不生效的常见原因

XML 配置好了，CacheManager 也声明了，@Cacheable 却像没加一样——大概率是 Bean 创建时机或代理问题。

立即学习“Java免费学习笔记（深入）”；

• 必须确保 CacheManager Bean 名为 cacheManager（默认名），否则 Spring 不识别；自定义名字需用 @EnableCaching(proxyTargetClass = true) + 显式指定 cache-manager 属性
• @Cacheable 只对 public 方法生效，且调用必须经过 Spring 代理（即不能 this.method() 自调用）
• Ehcache 2 的 CacheManager 初始化是懒加载的，第一次 getCache() 才真正解析 XML；如果 XML 有语法错误，异常会延迟抛出，表现为缓存操作卡住或返回 null

Ehcache 2 的 XML 模式老旧，不校验 schema，很多错误只有运行时才暴露。最稳妥的方式是：先用最小化 ehcache.xml 启动成功，再逐步加配置；别一上来就复制网上大段配置。