Spring에서 캐시 사용하기: CaffeineCache, @Cacheable, @CachePut, @CacheEvict

🔖 먼저 읽으면 좋은 글

로컬 캐시 & 분산 캐시 이해하기

스프링 프로젝트에서 성능을 개선하는 데 자주 사용되는 기술 중 하나가 캐시입니다.

 

지난 글들에서 캐시 개념에 대해 알아보았습니다. 이번 글에서는 스프링 프로젝트에 로컬 캐시를 적용해보려 합니다.

대표적인 로컬 캐시 Caffeine을 적용하고, @Cacheable, @CachePut, @CacheEvict와 같은 스프링의 캐시 어노테이션에 대해 정리해봅시다.

---

⚙️ 환경

• SpringBoot 3.4.0
• build.gradle에 dependency 추가

// Cache
implementation 'org.springframework.boot:spring-boot-starter-cache'

 

이 글에서는 로컬 캐시 중 가장 많이 사용되는 캐시 중 하나인 Caffeine 캐시를 사용합니다.

---

☕ Caffeine Cache

카페인 캐시는 Java에서 사용하는 고성능 로컬 캐시 라이브러리로

빠른 속도와 높은 적중률, 그리고 다양한 추가 기능을 지원하며 Spring에서도 공식적으로 지원하는 좋은 캐시입니다.

 

카페인 캐시를 사용하기 위해서 다음과 같은 의존성을 추가해주세요.

 

build.gradle

implementation 'com.github.ben-manes.caffeine:caffeine'

 

그리고 Configuration 파일을 추가해줍시다.

 

Cache Configuration

@Configuration
@EnableCaching
@Slf4j
class CacheConfig {

    @Bean
    public CaffeineCacheManager cacheManager() {
        CaffeineCacheManager cacheManager = new CaffeineCacheManager("users", "notifications");
        cacheManager.setCaffeine(caffeineCacheBuilder());
        return cacheManager;
    }

    @Bean
    public Caffeine<Object, Object> caffeineCacheBuilder() {
        return Caffeine.newBuilder()
            .expireAfterWrite(30, TimeUnit.MINUTES) // 쓰고 30분 후 만료
            .expireAfterAccess(10, TimeUnit.MINUTES)    // 무사용 10분 후 만료
            .maximumSize(5000)  // 최대 엔트리 수
            .recordStats()  // 통계 수집 활성화
            .removalListener((key, value, cause) -> // 제거 이벤트 리스너
                log.info("Cache removed: key={}, cause={}", key, cause));
    }
 }

 

🧑‍💼 캐시 매니저(Cache Manager)란?

캐시 매니저는 스프링에서 여러 캐시 인스턴스를 통합 관리하는 핵심 컴포넌트입니다.

어떤 캐시를 어떤 이름으로 생성할지, 정책은 어떻게 적용할건지 결정하죠.

 

CaffeineCacheManager는 CacheManager의 구현체 중 하나로, 우리는 카페인 캐시를 사용하니 이 매니저를 사용합니다.

캐시를 구체적으로 설정하여 setCaffeine() 메서드를 통해 설정을 적용합니다.

 

☕ 카페인 캐시 상세 설정

• 만료 정책
  • expireAfterWrite: 데이터가 생성/수정된 후 30분이 지나면 캐시에서 자동 삭제됩니다. 캐시에 저장한지 오래된 데이터는 틀릴 가능성이 높기 때문입니다.
  • expireAfterAccess: 10분 동안 접근이 없으면 불필요한 캐싱이라 간주하여 삭제됩니다.
• 용량 관리
  • maximumSize(5000): 캐시에 데이터가 무한으로 저장되지 않도록 최대 5000개의 데이터만 저장하도록 제한합니다.
    • 로컬 캐시는 서버 메모리 내에 위치하므로 용량이 너무 크면 서버 성능에 영향을 줄 수 있습니다.
    • 데이터 초과로 인해 삭제 시 LRU(Least Recently Used) 알고리즘에 따라 사용한지 가장 오래된 데이터부터 삭제합니다.
• 모니터링
  • recordStats(): 캐시 적중률 통계를 수집합니다.
    • cacheManager.getCache("users").getStats()로 적중률 확인 가능합니다.

removalListener: 캐시 삭제 원인(만료, 수동 삭제 등)을 로깅할 수 있습니다.

---

캐시 어노테이션을 이용해 손쉽게 캐시 기능을 사용할 수 있습니다.

✅ @Cacheable

@Cacheable 어노테이션을 메서드 위에 붙여 데이터를 캐시에 저장합니다.

메서드 호출 결과를 캐시에 저장하고,

같은 인자로 재호출 시 메서드 내부 로직이 실행되지 않고, 캐시에서 바로 반환합니다.

// 유저별로 알림 목록을 조회하는 서비스 메서드
// userId를 키로 저장되어, userId마다 목록 조회 결과가 캐싱됨

@Cacheable(
    cacheNames = "notifications",
    key = "#userId"
)
public List<NotificationDto> findAll(UUID userId) {
    List<Notification> notifications = notificationRepository.findAllByReceiverId(userId);
    return notificationMapper.toDto(notifications);
}

 

주요 속성

 

cacheNames	데이터를 저장할 캐시 저장소 이름
key	캐시 키 지정(기본적으로 파라미터 조합으로 많이 함)
condition	캐싱 적용 조건(메서드 실행 전에 조건에 부합하는지 평가함)
unless	캐싱 제외 조건(메서드 실행 후 결과를 캐싱할지 평가함)
sync	동기화 캐시 조회 기능 활성화 캐시 스탬피드(Cache Stampede) 현상을 방지하기 위한 속성입니다. 캐시 스탬피드: 캐시가 만료되거나 미스가 발생했을 때, 여러 스레드가 동시에 같은 데이터를 로드하려고 시도하여 일시적으로 DB 과부하가 발생할 수 있습니다. `sync = true` 옵션으로 이를 방지할 수 있습니다. 여러 스레드가 동시에 같은 키로 캐시를 조회할 때 첫 번째 스레드만 실제로 데이터를 조회하고, 나머지 스레드는 캐싱될 때까지 대기합니다.

•  

더 다양한 속성을 써보면 아래와 같습니다.

SpEL(Spring Expression Language) 문법에 따라 작성하도록 주의해야 합니다.

@Cacheable(
    cacheNames = "notifications",
    key = "#userId"
    condition= "#userId!=null"	// userId가 null이 아닌 경우에만 캐싱 적용 
    unless = "#result.getSize() == 0"	// 조회한 결과 알림 개수가 0개인 경우 캐싱 제외
)
public List<NotificationDto> findAll(UUID userId) {
    List<Notification> notifications = notificationRepository.findAllByReceiverId(userId);
    return notificationMapper.toDto(notifications);
}

---

✅  @CachePut

메서드 실행 결과를 무조건 캐시에 저장(갱신)하는 어노테이션입니다.

@Cacheable은 메서드를 실행하기 전, 캐시에 데이터가 있으면 메서드를 실행하지 않고 데이터를 반환하지만

@CachePut은 항상 메서드를 실행하는 차이가 있습니다.

 

유저별로 마이페이지를 빠르게 조회하기 위해

유저 정보 DTO를 조회하는 메서드에 @Cacheable을 적용했다고 합시다.

@Cacheable(
    cacheNames = "users",
    key = "#userId"
)
public UserDto find(UUID userId) {
	User user = userRepository.findById(userId)
	    .orElseThrow(() -> new UserNotFoundException(Map.of("userId", userId)));
    return userMapper.toDto(user);
}

 

그렇다면 프로필 이미지나 연락처를 변경한다든지 유저 정보가 업데이트 되면 어떨까요?

캐시에 있는 정보는 오래된 데이터가 되어 필요없게 되고, 갱신이 필요해집니다.

 

그럼 유저 정보가 업데이트될 때마다 캐시에서 해당 키가 업데이트되도록 @CachePut을 이용합시다.

결과로 반환되는 유저 정보가 캐시에 저장됩니다.

@CachePut(
    cacheNames = "users",
    key = "#userUpdateRequest.userId"
)
public UserDto update(UUID userId, UserUpdateRequest userUpdateRequest,
    // User 엔티티 업데이트 로직
    return userMapper.toDto(user);
}

---

✅  @CacheEvict

캐시에 저장된 데이터를 제거하는 방법입니다.

데이터가 변경될 때마다 실제 데이터와 캐시에 저장된 데이터가 불일치가 일어날 수 있으므로

적절한게 @CacheEvict를 사용하여 방지해야 합니다.

 

아까 유저별 정보를 빠르게 조회하기 위해 캐싱했었습니다.

만약 그 유저가 삭제된다면 캐시에서는 더 이상 필요없는 데이터가 되겠죠?

@CacheEvict를 통해 캐시에서 해당 엔트리를 삭제합니다.

@CacheEvict(cacheNames = "users", key = "#userId")
public void delete(UUID userId) {
    User user = userRepository.findById(userId).orElseThrow(() -> {
        log.warn("[Updating User Failed: User with id {} not found]", userId);
        return new UserNotFoundException(Map.of("userId", userId));
    });
    userRepository.delete(user);
}

 

주요 속성

cacheNames	데이터를 삭제할 캐시 저장소 이름
key	캐시 키 지정(기본적으로 파라미터 조합으로 많이 함)
allEnrites = true	특정 엔트리가 아니라 캐시 내 모든 엔트리 삭제
beforeInvocation	true이면 메서드 실행 전에 캐시에서 삭제 false이면 메서드 실행 성공 후에 삭제 true이면 메서드 실행 전에 삭제되므로 메서드 실행 중 예외가 발생해도 캐시에서는 데이터가 삭제되지만 false이면 메서드 실행 중 예외가 발생하면 캐시에서 삭제되지 않음
condition	캐시에서 제거하는 조건

---

이번 글에서는 Spring에서 로컬 캐시로 Caffeine을 설정하고,
캐시 관련 어노테이션들을 어떻게 사용하는지 기본적인 내용을 정리해보았습니다.

앞으로의 프로젝트에서 자주 캐시를 적용할 것 같아요!

 

참고자료

Spring boot 에 caffeine 캐시를 적용해보자 - 어떻게하면 일을 안 할까?

Spring Boot 에서 Cache 사용하기