@NaturalIdCache에 대한 보충 설명 및 사용법 공유

'25. 엔티티의 자연키 지정' 영상의 후반부에 적용한 @NaturalIdCache에 대해 추가로 학습한 내용이, 저처럼 해당 애노테이션을 처음 접한 분들에게 도움이 될 것 같아서 글을 작성합니다. 강의에서 오해가 있을 수 있는 부분, 그리고 자연키에 캐시를 적용하는 방법을 정리해 보았습니다.

강의 내용과 실제 동작의 차이점

강의에서는 “같은 트랜잭션 안에서 같은 아이디 값을 가지고 여러 번 조회 시 Persistence Context 에 캐시된 값을 꺼내오는 것 처럼. @NaturalIdCache를 적용하면 이것도 영속 컨텍스트에 캐싱이 된다.”고 말씀하셨습니다.

해당 내용에 대한 이해를 돕기 위해 Hibernate의 두 가지 캐시에 대해 간단히 짚고 넘어가겠습니다.

• 1차 캐시 (First-Level Cache): 세션(영속성 컨텍스트) 범위의 캐시입니다. 같은 트랜잭션 안에서만 유효하며, 트랜잭션이 끝나면 사라집니다. Spring Data JPA에서는 기본적으로 @Id 에 대한 조회를 1차 캐시합니다.

   

• 2차 캐시 (Second-Level Cache): 세션 팩토리 범위의 캐시로, 여러 세션에서 데이터를 공유할 수 있습니다. 적용하려면 별도의 의존성 추가 및 캐시 관련 설정(@Cache 등)이 필요합니다.

따라서, "같은 트랜잭션 안에서 캐시된 값을 꺼내온다."는 말은 세션 범위의 1차 캐시로 해석됩니다. 하지만 제가 직접 테스트해 본 결과, @NaturalIdCache는 1차 캐시가 아닌 2차 캐시와 관련이 있었으며, 1차 캐시를 적용하기 위해서는 다른 방법이 필요했습니다.

테스트를 통한 확인

자연키에 대한 1차 캐시 동작을 확인하기 위해, 강의에서 적용한 Member 엔티티의 @NaturalIdCache 를 제거하고, 자연키(Email)에 @NaturalId만 적용한 상황에서 두 가지 방식으로 테스트를 진행했습니다.

테스트1: findByEmail 메서드를 사용한 조회

Java

@Test
void NaturalIdFirstLevelCache() {
    Member member = Member.register(createMemberRegisterRequest(), createPasswordEncoder());
    memberRepository.save(member);

    entityManager.flush();
    entityManager.clear();
    System.out.println("회원 저장 및 persistence context 초기화 완료");

    // 같은 email(Natural ID)로 두 번 조회
    Member findMember1 = memberRepository.findByEmail(member.getEmail()).get();
    Member findMember2 = memberRepository.findByEmail(member.getEmail()).get();
    assertThat(findMember1).isSameAs(findMember2);
}

• Spring Data의 쿼리 메서드를 사용하여 이메일로 조회하는 findByEmail 메서드를 만들고, 한 트랜잭션에서 같은 회원을 두 번 조회했습니다. 자연키에 대한 1차 캐시가 동작한다면, SELECT 쿼리는 한 번만 실행되어야 합니다.

• 결과는 SELECT 쿼리가 두 번 실행되었습니다. 즉, 자연키에 대한 1차 캐시가 동작하지 않았습니다.

테스트2: Hibernate의 자연키 관련 API를 사용한 조회

@NaturalId를 다루는 글들을 찾아본 결과 Hibernate가 제공하는 자연키 관련 API가 있다는 것을 확인했고, 이를 적용하기 위해 커스텀 리포지토리를 구현했습니다.

Java

@Repository
@RequiredArgsConstructor
public class CustomizedMemberRepositoryImpl implements CustomizedMemberRepository {
    private final EntityManager entityManager;

    @Override
    public Optional<Member> findByNaturalId(Email naturalId) {
        return entityManager.unwrap(Session.class)
            .bySimpleNaturalId(Member.class)
            .loadOptional(naturalId);
    }
}

그리고, 테스트 1과 같은 방식으로 테스트를 진행하였습니다.

@Test
void NaturalIdApi() {
    Member member = Member.register(createMemberRegisterRequest(), createPasswordEncoder());
    memberRepository.save(member);

    entityManager.flush();
    entityManager.clear();
    System.out.println("회원 저장 및 persistence context 초기화 완료");

    Member findMember1 = memberRepository.findByNaturalId(member.getEmail()).get();
    Member findMember2 = memberRepository.findByNaturalId(member.getEmail()).get();
    assertThat(findMember1).isSameAs(findMember2);
}

• 결과는 SELECT 쿼리가 한 번만 실행되었습니다. 이를 통해 자연키에 대한 1차 캐시는 @NaturalIdCache 애노테이션과 무관하게, 전용 API를 사용해야만 동작하는 것을 확인했습니다.

@NaturalIdCache의 용도

@NaturalIdCache Javadoc에는 다음과 같은 설명이 있습니다.

Specifies that mappings from the natural id values of the annotated entity to the corresponding entity id values should be cached in the shared second-level cache.

…중략

This annotation is usually used in combination with Cache, since a round trip may only be avoided if the entity itself is also available in the cache.

대략 “natural id와 상응하는 id에 대한 매핑을 2차 캐시에 저장하는 애노테이션이고, 엔티티가 캐시되어있어야 하기 때문에 일반적으로 Cache와 함께 사용된다.”라고 해석됩니다. 즉, 1차 캐시가 아닌 2차 캐시를 위한 애노테이션입니다.

정리

2차 캐시 관련 설정 및 테스트를 마저 진행한 후 최종 정리한 내용은 다음과 같습니다.

자연키의 1차 캐시

• @NaturalIdCache 애노테이션과 관련 없습니다. 자연키에 @NaturalId만 붙이면 됩니다.

• 반드시 Hibernate Session의 bySimpleNaturalId() 같은 전용 API를 사용해야 적용됩니다.

자연키의 2차 캐시

• @Cache와 @NaturalIdCache를 함께 사용해야 동작합니다.

• @Cache만 사용 시 @Id로 조회할 때만 2차 캐시가 동작합니다.

• @NaturalIdCache만 사용 시 자연키와 ID에 대한 매핑 정보는 캐시 히트되는 걸 확인했지만, ID와 엔티티에 대한 캐시가 없어서 캐시가 적용되지 않았습니다.

   

• @Cache와 @NaturalIdCache 모두 사용 시 ID를 통한 조회와 자연키를 통한 조회 모두 2차 캐시가 적용됩니다.

   

참고 자료

• Hibernate6.6 공식 문서

• NaturalCache javadocs

• baeldung: Hibernate Natural IDs in Spring Boot

• Spring Custom Repository

글의 오류나 부족한 내용을 알고 계신 분은 코멘트를 달아주시면 감사하겠습니다.