Spring Boot微服务Hibernate二级缓存注解配置失效问题排查

从你提到的几个文件来看，实体缓存配置失效通常是几个容易踩的坑导致的，我帮你逐个梳理：

1. 实体类的缓存注解用错了（最常见！） #

很多人会混淆Spring的缓存注解和Hibernate的二级缓存注解，导致配置完全无效。你得确保UserEntity.java上用的是Hibernate专属的缓存注解，而不是Spring的@Cacheable（那个是Spring的方法级缓存，和Hibernate二级缓存不是一回事）。

正确的实体类配置示例：

import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import org.hibernate.annotations.Cache;
import org.hibernate.annotations.CacheConcurrencyStrategy;

@Entity
// 这行是核心：Hibernate的缓存注解，指定缓存策略和缓存区域
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE, region = "userCache")
public class UserEntity {
    @Id
    private Long id;
    private String username;
    // getter、setter等方法
}

⚠️ 注意：Hibernate的@Cache注解来自org.hibernate.annotations.Cache，别导成Spring的org.springframework.cache.annotation.Cache！

2. CacheConfig.java 没正确开启Hibernate二级缓存 #

光加@EnableCaching是不够的（那只是启用Spring的缓存框架），你还得显式配置Hibernate的二级缓存开关和缓存提供者。

正确的CacheConfig示例（以Caffeine缓存为例）：

import org.springframework.boot.autoconfigure.orm.jpa.HibernatePropertiesCustomizer;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableCaching // Spring缓存框架，和Hibernate二级缓存互补而非替代
public class CacheConfig {

    @Bean
    public HibernatePropertiesCustomizer hibernateCacheCustomizer() {
        return properties -> {
            // 必须开启二级缓存开关
            properties.put("hibernate.cache.use_second_level_cache", true);
            // 可选：开启查询缓存（如果需要缓存JPQL/HQL查询结果）
            properties.put("hibernate.cache.use_query_cache", true);
            // 指定缓存提供者的RegionFactory，这里用Caffeine
            properties.put("hibernate.cache.region.factory_class", "org.hibernate.cache.caffeine.CaffeineRegionFactory");
            // 如果用EHCache，替换为：org.hibernate.cache.jcache.JCacheRegionFactory
        };
    }
}

如果没配置HibernatePropertiesCustomizer来设置这些属性，Hibernate根本不知道要启用二级缓存，自然会输出实体缓存未生效的警告。

3. application.properties 配置冲突或缺失 #

如果你的application.properties里有缓存相关配置，要确保和Java配置一致，不要互相覆盖。比如：

# 可以在这里配置，和Java配置二选一即可，避免重复配置导致冲突
spring.jpa.properties.hibernate.cache.use_second_level_cache=true
spring.jpa.properties.hibernate.cache.region.factory_class=org.hibernate.cache.caffeine.CaffeineRegionFactory

如果这里把use_second_level_cache设为false，哪怕Java配置里是true也会被覆盖，直接导致缓存失效。

4. build.gradle 缺少缓存提供者依赖 #

Hibernate二级缓存需要具体的缓存实现（比如Caffeine、EHCache），如果依赖没加，Hibernate找不到提供者，就会跳过缓存配置，只会输出警告不会报错。

比如用Caffeine的话，build.gradle里要加：

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    // Caffeine缓存核心依赖
    implementation 'com.github.ben-manes.caffeine:caffeine'
    // Hibernate集成Caffeine的适配器
    implementation 'org.hibernate:hibernate-caffeine'
    // 数据库驱动（根据你的数据库替换）
    runtimeOnly 'com.mysql:mysql-connector-j'
}

如果用EHCache，替换为：

implementation 'org.ehcache:ehcache'
implementation 'org.hibernate:hibernate-ehcache'

5. Hibernate版本兼容问题 #

如果你的Spring Boot是3.x版本，对应的Hibernate是6.x，部分缓存提供者的类路径可能有变化。比如JCache的RegionFactory在Hibernate 6中依然是org.hibernate.cache.jcache.JCacheRegionFactory，但其他小众缓存实现可能有调整，要确保依赖版本和Spring Boot版本完全匹配。

最后验证缓存是否生效 #

可以开启Hibernate的SQL日志，观察第二次查询同一个实体时是否没有生成SQL：

spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

如果第一次查询有SQL输出，第二次查询同一个ID的实体时没有SQL，说明缓存生效了；如果两次都有SQL，那还是配置存在问题，回头再检查上面的几个点。

内容的提问来源于stack exchange，提问作者rvit34