Spring Boot 3 中集成 Ehcache 3 的完整配置指南-java教程-PHP中文网

Spring Boot 3 中集成 Ehcache 3 的完整配置指南

本文详解 Spring Boot（2.7+ 及 3.x）中正确集成 Ehcache 3 的关键步骤，包括依赖调整、配置迁移、Java DSL 替代 XML、JCache 兼容性适配及 CacheManager 手动注册要点，解决 No cache manager could be auto-configured 启动异常。

本文详解 spring boot（2.7+ 及 3.x）中正确集成 ehcache 3 的关键步骤，包括依赖调整、配置迁移、java dsl 替代 xml、jcache 兼容性适配及 cachemanager 手动注册要点，解决 `no cache manager could be auto-configured` 启动异常。

在 Spring Boot 2.7 及更高版本（尤其是 Spring Boot 3.x）中，Ehcache 2 的自动配置已被完全移除，而 Ehcache 3 不再原生支持 spring.cache.type=ehcache 这一旧式配置——它仅兼容 JCache（JSR-107）标准。因此，当项目错误地设置 spring.cache.type=ehcache 时，Spring Boot 的 CacheAutoConfiguration 将无法识别任何可用的缓存管理器，最终抛出 IllegalArgumentException: No cache manager could be auto-configured。

✅ 正确集成 Ehcache 3 的三步核心实践

1. 依赖声明：使用 Ehcache 3 + JCache API（非 Ehcache 2）

务必排除旧版 net.sf.ehcache:ehcache，引入 Ehcache 3 和 JCache 规范实现：

<!-- Maven POM -->
<dependency><groupid>org.ehcache</groupid><artifactid>ehcache</artifactid><version>3.10.6</version><!-- 推荐 3.10.x 或 3.11.x（兼容 SB 3.2+） --></dependency><dependency><groupid>javax.cache</groupid><artifactid>cache-api</artifactid><version>1.1.1</version><!-- 注意：SB 3.x 已迁至 jakarta.cache，若用 SB 3.2+，请改用 jakarta.cache-api --></dependency>

⚠️ 注意：Spring Boot 3.2+ 已全面转向 Jakarta EE 9+ 命名空间，应使用 jakarta.cache:jakarta.cache-api:2.1.0 并配合 org.ehcache:ehcache:3.11.0+；若仍用 javax.cache，需确保与 Spring Boot 版本兼容（如 SB 3.0.5 可接受 1.1.1）。

2. 配置切换：启用 jcache 类型，弃用 ehcache

在 application.properties 或 application.yml 中，必须设置为 jcache：

# ✅ 正确：启用 JSR-107 兼容模式
spring.cache.type=jcache

# ❌ 错误：Ehcache 3 不响应此配置（将导致启动失败）
# spring.cache.type=ehcache

# 可选：指定 JCache 配置文件路径（但推荐 Java 配置，更可控）
# spring.cache.jcache.config=classpath:ehcache-jcache.xml

? 提示：spring.cache.jcache.config 仅在使用 ehcache-jcache.xml（基于 JSR-107 格式）时生效；但 Ehcache 3 官方推荐优先使用类型安全的 Java DSL 配置。

3. Java 配置类：手动构建并注册 CacheManager

由于 Spring Boot 不再为 Ehcache 3 提供自动配置的 CacheManager Bean，必须通过 @Bean 显式创建，并确保其符合 JCache 规范：

import org.ehcache.config.CacheConfiguration;
import org.ehcache.config.builders.CacheConfigurationBuilder;
import org.ehcache.config.builders.ExpiryPolicyBuilder;
import org.ehcache.config.builders.ResourcePoolsBuilder;
import org.ehcache.jsr107.Eh107Configuration;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import javax.cache.CacheManager;
import javax.cache.Caching;
import javax.cache.spi.CachingProvider;
import java.time.Duration;

@Configuration
@EnableCaching
public class CacheConfig {

    @Bean
    public CacheManager cacheManager() {
        // Step 1: 定义 Ehcache 3 原生缓存配置
        CacheConfiguration<string string> cacheConfig = CacheConfigurationBuilder
                .newCacheConfigurationBuilder(String.class, String.class,
                        ResourcePoolsBuilder.heap(1000)) // 1000 条堆内条目
                .withExpiry(ExpiryPolicyBuilder.timeToIdleExpiration(Duration.ofSeconds(3600)))
                .build();

        // Step 2: 获取 JCache 兼容的 CacheManager（由 Ehcache 提供）
        CachingProvider provider = Caching.getCachingProvider();
        CacheManager cacheManager = provider.getCacheManager();

        // Step 3: 将 Ehcache 配置桥接到 JCache Configuration
        javax.cache.configuration.Configuration<string string> jcacheConfig =
                Eh107Configuration.fromEhcacheCacheConfiguration(cacheConfig);

        // Step 4: 创建具名缓存（名称需与 @Cacheable.value 一致）
        cacheManager.createCache("myCustomCache", jcacheConfig);

        // Step 5: 注册 JVM 关闭钩子，确保缓存资源优雅释放
        Runtime.getRuntime().addShutdownHook(new Thread(cacheManager::close));

        return cacheManager;
    }
}</string></string>

✅ 此 CacheManager Bean 将被 Spring 的缓存抽象自动识别，后续 @Cacheable("myCustomCache") 即可正常工作，无需修改 Controller 层代码。

? 补充说明与最佳实践

XML 配置已废弃：Ehcache 3 不再支持 ehcache.xml（Ehcache 2 格式）。若需 XML，必须使用 JSR-107 兼容的 ehcache-jcache.xml，但强烈建议采用上述类型安全的 Java 配置。
缓存名称即契约：@Cacheable(value = "myCustomCache") 中的 "myCustomCache" 必须与 cacheManager.createCache(...) 中传入的名称完全一致，否则运行时抛出 CacheNotFoundException。
多缓存定义：可在同一 cacheManager() 方法中连续调用 createCache() 创建多个缓存，例如 myUserCache、myProductCache。

Spring Boot 3.2+ 迁移提示：若升级至 Jakarta EE 9+，需替换导入：

import jakarta.cache.CacheManager;     // 替代 javax.cache.CacheManager
import jakarta.cache.Caching;          // 替代 javax.cache.Caching
import jakarta.cache.spi.CachingProvider; // 替代 javax.cache.spi.CachingProvider

并更新依赖为 jakarta.cache-api。

通过以上配置，即可彻底解决 No cache manager could be auto-configured 异常，实现 Ehcache 3 在现代 Spring Boot 应用中的稳定、可维护集成。