Tuesday, December 11, 2018

JPA 프록시 객체 직렬화 오류(ByteBuddyInterceptor) 심층 분석 및 해결
  /   1 comment   

Spring Boot와 JPA(Java Persistence API)를 사용하여 애플리케이션을 개발하다 보면, 때때로 얘기치 못한 예외를 마주하게 됩니다. 그중에서도 개발자들을 당황하게 만드는 대표적인 오류가 바로 com.fasterxml.jackson.databind.exc.InvalidDefinitionException: No serializer found for class org.hibernate.proxy.pojo.bytebuddy.ByteBuddyInterceptor 입니다. 이 오류는 일반적으로 잘 동작하던 API가 특정 조건에서 갑자기 발생하며, 그 원인이 직관적으로 드러나지 않아 해결에 어려움을 겪는 경우가 많습니다. 특히, 지연 로딩(Lazy Loading)과 관련된 엔티티를 JSON으로 변환하여 클라이언트에게 응답으로 전달하는 과정에서 빈번하게 발생합니다.

이 글에서는 해당 오류가 발생하는 근본적인 원인을 JPA의 동작 방식, 특히 Hibernate의 프록시 객체와 지연 로딩 메커니즘을 중심으로 심도 있게 파헤쳐 보고, 단순히 오류를 회피하는 임시방편이 아닌, 애플리케이션의 아키텍처를 견고하게 만드는 근본적인 해결책까지 단계별로 제시하고자 합니다. 이 글을 끝까지 읽으시면, 단순히 에러 하나를 해결하는 것을 넘어 JPA의 핵심 동작 원리에 대한 깊은 이해를 얻게 될 것입니다.

오류 메시지 다시 보기: 문제의 본질은 무엇인가?

먼저 우리가 마주한 오류 메시지를 자세히 분석해 봅시다. 전체 오류 로그는 보통 다음과 같은 형태로 나타납니다.


com.fasterxml.jackson.databind.exc.InvalidDefinitionException: No serializer found for class org.hibernate.proxy.pojo.bytebuddy.ByteBuddyInterceptor and no properties discovered to create BeanSerializer (to disable, configure SerializationFeature.FAIL_ON_EMPTY_BEANS) (through reference chain: com.example.myapp.domain.Order["member"]->com.example.myapp.domain.Member_$$_jvsteda_2["hibernateLazyInitializer"])

이 메시지를 분해해 보면 몇 가지 중요한 키워드를 발견할 수 있습니다.

  • No serializer found for class...: Jackson 라이브러리가 특정 클래스를 JSON 형식으로 직렬화(변환)하는 방법을 찾지 못했다는 의미입니다.
  • org.hibernate.proxy.pojo.bytebuddy.ByteBuddyInterceptor: 문제가 발생한 클래스의 이름입니다. 여기서 proxy, bytebuddy, interceptor라는 단어에 주목해야 합니다. 이는 실제 엔티티 객체가 아닌, Hibernate가 동적으로 생성한 프록시 객체의 내부 구성 요소임을 암시합니다.
  • hibernateLazyInitializer: 오류가 발생한 참조 체인(reference chain)의 마지막 부분입니다. 프록시 객체가 가지고 있는, 지연 로딩을 처리하기 위한 초기화 핸들러입니다.
  • configure SerializationFeature.FAIL_ON_EMPTY_BEANS: Jackson의 설정 옵션을 변경하여 이 문제를 비활성화할 수 있다는 힌트를 제공합니다.

종합해 보면, 이 오류의 핵심은 "JPA의 구현체인 Hibernate가 지연 로딩을 위해 생성한 프록시 객체를 Jackson이 이해하지 못해 JSON으로 변환하지 못하는 문제"라고 정의할 수 있습니다. 즉, 이 문제를 해결하려면 JPA의 지연 로딩과 프록시 객체가 무엇인지, 그리고 Jackson의 직렬화 과정과 어떻게 충돌하는지를 정확히 이해해야 합니다.

1단계: 급한 불 끄기 - 임시 해결책과 그 한계

근본적인 원인을 파악하기 전에, 오류 메시지에서 제안하는 방법이나 커뮤니티에서 흔히 공유되는 빠른 해결책들을 먼저 살펴보겠습니다. 이 방법들은 당장의 오류를 해결해 줄 수는 있지만, 근본적인 문제를 감추는 부작용이 있을 수 있으므로 신중하게 사용해야 합니다.

방법 1: `FAIL_ON_EMPTY_BEANS` 옵션 비활성화

오류 메시지가 친절하게 알려준 방법입니다. application.properties 또는 application.yml 파일에 다음과 같은 설정을 추가합니다.

application.properties


spring.jackson.serialization.fail-on-empty-beans=false

application.yml


spring:
  jackson:
    serialization:
      fail-on-empty-beans: false

이 설정은 Jackson이 직렬화할 속성이 없는 빈(Bean) 객체를 만났을 때 예외를 발생시키지 않도록 만듭니다. 이 설정을 적용하면 ByteBuddyInterceptor 같이 Jackson이 이해할 수 없는 객체는 그냥 빈 JSON 객체({})로 처리하고 넘어가게 됩니다. 실제로 응답 JSON을 확인해 보면 "hibernateLazyInitializer": {} 와 같은 필드가 포함된 것을 볼 수 있습니다.

  • 장점: 설정 한 줄로 즉시 오류를 해결할 수 있습니다. 매우 간단합니다.
  • 단점:
    • 근본 원인을 해결하는 것이 아니라 문제를 덮는 방식입니다.
    • API 응답에 hibernateLazyInitializer와 같은 불필요하고 내부적인 정보가 노출됩니다. 이는 API 소비자에게 혼란을 주고, 내부 구현에 대한 정보를 외부에 드러내는 좋지 않은 설계입니다.
    • 정말로 비어있어서는 안 되는 객체가 실수로 비어있는 경우에도 오류가 발생하지 않아 버그를 인지하기 어려워질 수 있습니다.

방법 2: `@JsonIgnoreProperties` 어노테이션 사용

첫 번째 방법의 단점을 보완하기 위해, 문제가 되는 hibernateLazyInitializer 필드를 직렬화 과정에서 명시적으로 무시하도록 설정할 수 있습니다. 엔티티 클래스 상단에 @JsonIgnoreProperties 어노테이션을 추가합니다.


import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import javax.persistence.Entity;
// ... 다른 import

@Entity
@JsonIgnoreProperties({"hibernateLazyInitializer"})
public class Member {
    // ... 필드 정의
}

이 방법은 `FAIL_ON_EMPTY_BEANS` 옵션을 끄는 것보다 좀 더 표적화된 해결책입니다. 불필요한 필드가 응답 JSON에 포함되는 것을 막아줍니다.

  • 장점: API 응답이 깔끔해집니다. 특정 필드만 무시하므로 다른 빈 객체 관련 오류는 정상적으로 감지할 수 있습니다.
  • 단점:
    • 이 어노테이션을 지연 로딩을 사용하는 모든 엔티티 클래스에 반복적으로 추가해야 하는 번거로움이 있습니다.
    • 여전히 프록시 객체 문제를 근본적으로 해결하는 것은 아닙니다. 이는 Jackson에게 "이 이상한 필드는 그냥 못 본 척해줘"라고 말하는 것과 같습니다.
    • 프레젠테이션 계층(JSON 변환)에 관련된 어노테이션이 도메인 모델(엔티티)에 직접적으로 침투하는 설계상의 문제를 야기합니다. 도메인 모델은 특정 기술에 종속되지 않고 순수하게 유지하는 것이 이상적입니다.

위 두 가지 방법은 빠르게 문제를 해결해야 할 때 유용할 수 있지만, 장기적으로는 더 나은 해결책을 적용하는 것이 바람직합니다. 이제부터 왜 이런 문제가 발생하는지 그 근본 원리를 파헤쳐 보겠습니다.

2단계: 원인 파헤치기 - 지연 로딩과 프록시 객체의 비밀

오류의 근본 원인을 이해하기 위한 핵심 키워드는 지연 로딩(Lazy Loading)과 프록시(Proxy)입니다.

JPA의 영속성 컨텍스트와 로딩 전략

JPA는 엔티티의 상태를 관리하는 논리적인 공간인 영속성 컨텍스트(Persistence Context)를 사용합니다. 엔티티 매니저를 통해 조회된 엔티티는 이 영속성 컨텍스트에 의해 관리됩니다.

데이터베이스에서 데이터를 조회할 때, JPA는 두 가지 전략을 사용합니다.

  1. 즉시 로딩 (Eager Loading): 연관된 엔티티까지 한 번에 모두 조회하여 메모리에 올리는 방식입니다. 예를 들어, Order 엔티티를 조회할 때 연관된 Member 엔티티도 즉시 함께 조회합니다. @ManyToOne(fetch = FetchType.EAGER) 와 같이 설정합니다.
  2. 지연 로딩 (Lazy Loading): 특정 엔티티를 조회할 때 연관된 엔티티는 실제로 사용되기 전까지 데이터베이스에서 조회하지 않는 방식입니다. Order를 조회하면, order.getMember() 메소드를 호출하는 시점에 비로소 Member를 조회하는 SELECT 쿼리가 실행됩니다. @ManyToOne, @OneToMany 등의 연관관계 매핑에서 기본값은 보통 지연 로딩입니다(@ManyToOne, @OneToOne은 EAGER가 기본값, @OneToMany, @ManyToMany는 LAZY가 기본값).

지연 로딩은 불필요한 데이터베이스 조회를 최소화하여 애플리케이션의 성능을 최적화하는 매우 중요한 기능입니다. 예를 들어, 주문 목록만 필요한데 주문마다 회원 정보를 매번 같이 조회한다면 심각한 성능 저하(특히 N+1 문제)를 유발할 수 있습니다.

지연 로딩의 구현체: 프록시 객체

그렇다면 JPA(Hibernate)는 어떻게 지연 로딩을 구현할까요? 바로 여기에 프록시 객체가 등장합니다.

지연 로딩이 설정된 엔티티를 조회할 때, Hibernate는 실제 엔티티 객체 대신 '가짜' 객체를 생성하여 반환합니다. 이 가짜 객체가 바로 프록시 객체입니다. 이 프록시는 실제 엔티티 클래스를 상속받아 만들어지므로, 겉보기에는 실제 객체와 똑같이 사용할 수 있습니다.

이 프록시 객체는 내부에 다음과 같은 정보를 가지고 있습니다.

  • 실제 엔티티의 ID 값: 어떤 데이터를 가져와야 하는지 식별하기 위해 ID는 미리 알고 있습니다.
  • 타겟(Target) 객체 참조: 실제 엔티티 객체를 가리키는 참조 변수입니다. 초기에는 null 상태입니다.
  • 초기화 핸들러 (Handler): 바로 오류 메시지에서 본 hibernateLazyInitializer 같은 것입니다. 이 핸들러가 실제 데이터가 필요한 시점에 데이터베이스에 접근하여 데이터를 가져오고, 타겟 객체를 생성하여 채워 넣는 역할을 합니다.

동작 흐름은 다음과 같습니다.

  1. 클라이언트 코드가 order.getMember()를 호출합니다. 이 때 반환된 것은 실제 Member 객체가 아니라, Member의 프록시 객체입니다.
  2. 이 프록시 객체의 name 필드를 얻기 위해 memberProxy.getName()을 호출합니다.
  3. 프록시 객체는 자신이 아직 초기화되지 않았음을 확인하고, 내부의 초기화 핸들러를 작동시킵니다.
  4. 초기화 핸들러는 영속성 컨텍스트에 실제 Member 객체를 요청합니다.
  5. 영속성 컨텍스트는 데이터베이스에 SELECT * FROM member WHERE id = ? 쿼리를 날려 실제 데이터를 가져옵니다.
  6. 가져온 데이터로 실제 Member 객체를 생성하고, 프록시 객체의 타겟 참조 변수에 연결합니다.
  7. 프록시 객체는 이제 실제 Member 객체에게 getName() 호출을 위임하여 실제 이름을 반환합니다.
  8. 이후 같은 프록시 객체에 대한 모든 메소드 호출은 바로 실제 객체에게 위임됩니다.

오류 메시지에 등장하는 ByteBuddy는 바로 이러한 프록시 객체를 동적으로 생성하기 위해 Hibernate가 사용하는 라이브러리입니다. (과거에는 CGLIB를 주로 사용했습니다.) ByteBuddyInterceptor는 프록시의 메소드 호출을 가로채서 위와 같은 초기화 로직을 수행하는 핵심적인 역할을 하는 클래스입니다.

Jackson 직렬화와의 충돌

이제 문제의 본질이 명확해졌습니다.

컨트롤러가 클라이언트에게 엔티티 객체를 반환하면, Spring MVC는 내부적으로 Jackson 라이브러리를 사용해 이 객체를 JSON 문자열로 변환합니다. 그런데 컨트롤러가 받은 객체가 초기화되지 않은 프록시 객체라면 어떤 일이 벌어질까요?

Jackson은 리플렉션을 사용해 객체의 모든 필드나 getter 메소드를 분석하여 JSON의 key-value 쌍으로 변환하려고 합니다. 그런데 이 프록시 객체는 실제 데이터 필드(name, email 등)는 모두 `null`이고, 대신 target이나 hibernateLazyInitializer와 같은 내부 필드를 가지고 있습니다. Jackson은 이 hibernateLazyInitializer가 뭔지, 그리고 그 안에 있는 ByteBuddyInterceptor가 뭔지 전혀 알지 못합니다. 이 객체들은 일반적인 데이터 객체(POJO)가 아니며, JSON으로 어떻게 표현해야 할지에 대한 규칙(Serializer)이 정의되어 있지 않습니다.

결국 Jackson은 "ByteBuddyInterceptor 클래스를 어떻게 직렬화해야 할지 모르겠습니다!" 라며 `No serializer found` 예외를 던지는 것입니다.

3단계: 원인 재현 및 심화 - `findById` vs `getReferenceById` (`getOne`)

많은 개발자들이 "잘 되던 코드를 조금 바꿨을 뿐인데 갑자기 오류가 난다"고 말합니다. 이 "조금 바꾼" 코드 중 대표적인 사례가 `JpaRepository`의 메소드를 변경하는 것입니다. 특히 `findById`를 `getOne` (혹은 최신 버전의 `getReferenceById`)으로 변경했을 때 이 문제가 발생하기 쉽습니다.


// 예제 엔티티
@Entity
public class Order {
    @Id @GeneratedValue
    private Long id;

    private String orderName;

    @ManyToOne(fetch = FetchType.LAZY) // 지연 로딩 설정
    @JoinColumn(name = "member_id")
    private Member member;
    // ... getters
}

@Entity
public class Member {
    @Id @GeneratedValue
    private Long id;

    private String name;
    // ... getters
}

`findById(ID id)`의 동작

이 메소드는 데이터베이스에서 ID에 해당하는 엔티티를 즉시 조회합니다. 결과적으로 실제 엔티티 객체를 반환합니다. 만약 해당 ID의 데이터가 없으면 `Optional.empty()`를 반환합니다.


@GetMapping("/orders/{id}")
public Order findOrder(@PathVariable Long id) {
    // DB에 SELECT 쿼리를 즉시 실행하여 실제 Order 객체를 가져온다.
    // Order 객체 안의 'member' 필드는 프록시 객체 상태이다.
    Order order = orderRepository.findById(id).orElseThrow(EntityNotFoundException::new);
    
    // 만약 여기서 order.getMember().getName()을 호출하지 않으면
    // 'member'는 프록시인 채로 Jackson에게 전달된다.
    
    return order; // Jackson이 직렬화를 시도
}

위 코드에서 `orderRepository.findById(id)`는 `Order` 테이블에 SELECT 쿼리를 날려 실제 `Order` 객체를 만듭니다. 하지만 `order` 객체 내부의 `member` 필드는 `FetchType.LAZY`이므로, 이 시점에서는 실제 `Member` 객체가 아닌 **프록시 `Member` 객체**가 들어 있습니다. 이 `order` 객체가 Jackson에게 전달되면, Jackson은 `order`의 필드들을 직렬화하다가 `member` 필드를 만나고, 이 프록시 객체를 직렬화하려다 위에서 설명한 `ByteBuddyInterceptor` 오류를 만나게 됩니다.

`getReferenceById(ID id)` (구: `getOne(ID id)`)의 동작

이 메소드는 `findById`와 근본적으로 다르게 동작합니다. `getOne`은 JPA 2.5부터 deprecated되었고 `getReferenceById`를 사용해야 합니다. 둘의 동작은 거의 동일합니다.

이 메소드는 데이터베이스에 접근하지 않습니다. 대신, 해당 ID를 가진 엔티티의 프록시 객체를 생성하여 반환합니다. 실제 데이터가 필요한 시점 (ID 외의 다른 필드에 접근할 때)이 되어서야 비로소 `SELECT` 쿼리를 실행합니다. 이는 연관관계뿐만 아니라, 다른 엔티티와 관계를 맺기 위한 참조만 필요할 때 매우 효율적입니다.


// Member를 직접 조회하지 않고, 다른 엔티티에 연관관계만 설정하고 싶을 때 유용
Member memberReference = memberRepository.getReferenceById(memberId);
newOrder.setMember(memberReference); // DB 접근 없이 프록시로 관계 설정
orderRepository.save(newOrder);

만약 이 메소드를 단순히 엔티티 조회용으로 사용하면 어떻게 될까요?


@GetMapping("/members/{id}")
public Member findMember(@PathVariable Long id) {
    // DB에 쿼리하지 않고, ID만 가진 텅 빈 프록시 Member 객체를 반환.
    Member memberProxy = memberRepository.getReferenceById(id);
    return memberProxy; // 초기화되지 않은 프록시를 Jackson에게 그대로 전달
}

이 코드는 거의 100% 확률로 `No serializer found` 오류를 발생시킵니다. `findById`를 사용했을 때와 달리, 반환되는 객체 자체가 처음부터 초기화되지 않은 프록시이기 때문입니다.

결론적으로, 이 오류는 초기화되지 않은 프록시 객체를 Jackson과 같은 직렬화 라이브러리에 그대로 전달할 때 발생하며, `getReferenceById`를 사용하거나, `findById`로 조회한 엔티티의 지연 로딩된 연관 필드에 접근하지 않고 반환할 때 주로 나타납니다.

4단계: 근본적인 해결책 - 견고한 API 설계를 향하여

이제 우리는 문제의 원인을 완벽하게 이해했습니다. 이를 바탕으로 더 이상 임시방편이 아닌, 아키텍처 관점에서의 올바른 해결책들을 살펴보겠습니다.

해결책 1: DTO(Data Transfer Object) 패턴 도입 (가장 강력 추천)

엔티티를 API의 응답 스펙으로 직접 사용하는 것은 여러 가지 문제를 야기합니다.

  • 결합(Coupling): 뷰(프레젠테이션 계층)와 도메인 모델이 강하게 결합됩니다. 엔티티의 필드 하나를 변경하면 API 스펙이 변경되어 클라이언트에 영향을 줍니다.
  • 보안: 엔티티의 모든 필드가 의도치 않게 외부에 노출될 수 있습니다. 예를 들어, 사용자의 비밀번호 필드까지 JSON에 포함될 수 있습니다.
  • 직렬화 문제: 지금까지 살펴본 프록시 직렬화 문제, 양방향 연관관계에서의 무한 루프 문제 등이 발생합니다.

DTO(데이터 전송 객체) 패턴은 이러한 문제들을 해결하기 위한 가장 확실하고 표준적인 방법입니다. DTO는 계층 간 데이터 교환을 위해 사용하는, 순수한 데이터만 담고 있는 객체입니다.

구현 순서:

  1. DTO 클래스 정의: API 응답 스펙에 맞는 필드만 가진 별도의 클래스를 만듭니다. 
    
// Order 정보를 담을 DTO
@Getter // Jackson은 getter나 필드를 통해 직렬화하므로 getter 필요
public class OrderResponseDto {
    private Long orderId;
    private String orderName;
    private MemberResponseDto member; // 연관된 정보도 DTO로

    public OrderResponseDto(Order order) {
        this.orderId = order.getId();
        this.orderName = order.getOrderName();
        // ★★★ 중요: 여기서 실제 getMember()를 호출하여 프록시를 초기화한다.
        this.member = new MemberResponseDto(order.getMember());
    }
}

// Member 정보를 담을 DTO
@Getter
public class MemberResponseDto {
    private Long memberId;
    private String name;

    public MemberResponseDto(Member member) {
        this.memberId = member.getId();
        this.name = member.getName(); // ★★★ 실제 getName()을 호출
    }
}
  2. 서비스/컨트롤러 로직 수정: 엔티티를 조회한 후, DTO로 변환하여 반환합니다. 
    
@RestController
@RequiredArgsConstructor
public class OrderController {
    
    private final OrderRepository orderRepository;

    @GetMapping("/api/orders/{id}")
    public OrderResponseDto findOrderAsDto(@PathVariable Long id) {
        Order order = orderRepository.findById(id)
            .orElseThrow(() -> new EntityNotFoundException("주문을 찾을 수 없습니다."));

        // 엔티티를 직접 반환하는 대신, DTO로 변환하여 반환
        return new OrderResponseDto(order);
    }
}

DTO 패턴의 장점:

  • 완벽한 직렬화 문제 해결: DTO 생성자나 팩토리 메소드 안에서 엔티티의 getter(`order.getMember()`, `member.getName()`)를 호출하는 순간, Hibernate는 지연 로딩된 프록시를 초기화합니다. Jackson에게 전달되는 것은 실제 데이터로 채워진 DTO 객체이므로 프록시 관련 문제가 원천적으로 발생하지 않습니다.
  • 관심사의 분리 (Separation of Concerns): 도메인 모델(엔티티)과 API 스펙(DTO)이 명확하게 분리됩니다. 엔티티 내부 구조 변경이 API에 직접적인 영향을 주지 않습니다.
  • API 스펙 제어: API를 통해 노출할 데이터만 선택적으로 DTO에 담을 수 있어 보안성이 향상되고, 클라이언트가 필요한 데이터만 전송하여 효율적입니다.
  • 순환 참조 방지: 양방향 연관관계가 있는 엔티티(e.g., `Order` <-> `Member`)를 직접 반환하면 Jackson이 직렬화 과정에서 무한 루프에 빠질 수 있습니다. DTO를 사용하면 필요한 단방향 정보만 담아 이 문제를 쉽게 해결할 수 있습니다.

DTO 변환 로직이 반복적이라면 MapStruct나 ModelMapper 같은 라이브러리를 사용하여 보일러플레이트 코드를 줄일 수도 있습니다.

해결책 2: Jackson Hibernate5 Module 사용

만약 DTO를 사용하는 것이 과도한 작업이라고 판단되거나, 특정 이유로 엔티티를 직접 반환해야 하는 경우, Jackson이 Hibernate의 프록시 객체를 이해하도록 만들 수 있습니다. `jackson-datatype-hibernate5` 모듈이 바로 이 역할을 합니다.

구현 순서:

  1. 의존성 추가 (build.gradle) 
    
implementation 'com.fasterxml.jackson.datatype:jackson-datatype-hibernate5'
  2. 모듈 등록 (Spring Boot에서는 Bean으로 등록) 
    
import com.fasterxml.jackson.datatype.hibernate5.Hibernate5Module;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class JacksonConfig {

    @Bean
    public Hibernate5Module hibernate5Module() {
        Hibernate5Module hibernate5Module = new Hibernate5Module();
        // 이 옵션을 true로 설정하면, Jackson이 지연 로딩된 필드에 접근할 때
        // 강제로 초기화하여 데이터를 가져온다. (주의 필요)
        // hibernate5Module.configure(Hibernate5Module.Feature.FORCE_LAZY_LOADING, true);
        return hibernate5Module;
    }
}
    Spring Boot는 클래스패스에 `jackson-datatype-hibernate5`가 있으면 자동으로 이 모듈을 `ObjectMapper`에 등록해주므로, 별도의 `@Configuration` 설정 없이 의존성 추가만으로 동작하는 경우가 많습니다.

이 모듈은 Jackson이 `hibernateLazyInitializer` 같은 필드를 만나면 무시하고, 지연 로딩된 프록시 객체를 null로 처리하거나 (기본 동작), `FORCE_LAZY_LOADING` 옵션을 켜면 해당 프록시를 강제로 초기화하여 실제 데이터를 JSON에 포함시키는 기능을 제공합니다.

장점:

  • DTO를 만들 필요 없이, 기존 코드를 거의 수정하지 않고 문제를 해결할 수 있습니다.

단점 및 주의사항:

  • N+1 문제 유발 가능성: `FORCE_LAZY_LOADING = true` 옵션은 매우 위험할 수 있습니다. 예를 들어, 100개의 `Order` 리스트를 조회하고 각 `Order`마다 연관된 `Member`가 있다면, 이 옵션 때문에 `Order` 목록 조회 쿼리 1번 + 각 `Order`의 `Member`를 초기화하기 위한 쿼리 100번, 총 101번의 쿼리가 발생할 수 있습니다. 이는 OSIV(Open Session In View) 설정과 맞물려 심각한 성능 저하를 일으킵니다.
  • DTO의 다른 장점 부재: 엔티티와 뷰의 결합, 보안 문제 등은 여전히 해결되지 않습니다.

따라서 이 방법은 프로젝트의 구조와 상황을 잘 이해하고 신중하게 사용해야 합니다.

해결책 3: 필요한 데이터만 명시적으로 조회 (Fetch Join 또는 EntityGraph)

컨트롤러에서 엔티티를 반환하기 전에, 필요한 연관 엔티티를 명시적으로 함께 조회하여 프록시가 아닌 실제 객체로 채워 넣는 방법입니다. 이는 N+1 문제를 해결하는 데에도 효과적입니다.

방법 A: Fetch Join 사용 (JPQL)

JPQL 쿼리 작성 시 `JOIN FETCH` 키워드를 사용하여 연관된 엔티티를 즉시 함께 로딩하도록 지정합니다.


// OrderRepository.java
public interface OrderRepository extends JpaRepository<Order, Long> {

    @Query("SELECT o FROM Order o JOIN FETCH o.member WHERE o.id = :id")
    Optional<Order> findOrderWithMemberById(@Param("id") Long id);
}

// Controller
@GetMapping("/api/orders/{id}")
public Order findOrder(@PathVariable Long id) {
    // findById 대신 fetch join 쿼리 메소드 사용
    // 이 시점에 Order와 Member가 모두 실제 객체로 로딩된다.
    Order order = orderRepository.findOrderWithMemberById(id)
        .orElseThrow(EntityNotFoundException::new);
    
    // 프록시가 없으므로 직렬화가 문제 없이 성공한다.
    return order;
}

이렇게 하면, 처음부터 프록시가 아닌 실제 `Member` 객체가 `Order`에 담기므로 직렬화 문제가 발생하지 않습니다.

방법 B: `@EntityGraph` 사용

JPQL을 작성하지 않고, 어노테이션으로 로딩할 연관 필드를 지정하는 더 세련된 방법입니다.


// OrderRepository.java
public interface OrderRepository extends JpaRepository<Order, Long> {
    
    // "member" 필드를 함께 그래프 탐색에 포함하여 EAGER 로딩하도록 지정
    @EntityGraph(attributePaths = {"member"})
    @Override
    Optional<Order> findById(Long id);
}

// Controller는 변경 없음. 그냥 findById 호출하면 된다.
@GetMapping("/api/orders/{id}")
public Order findOrder(@PathVariable Long id) {
    Order order = orderRepository.findById(id)
        .orElseThrow(EntityNotFoundException::new);
    return order;
}

이 방법은 DTO를 사용하지 않고 엔티티를 반환하면서도 프록시 문제와 N+1 문제를 동시에 해결할 수 있는 좋은 대안입니다. 하지만 여전히 엔티티와 뷰가 결합되는 문제는 남아 있습니다.

결론: 최적의 선택과 종합적인 가이드라인

No serializer found for class org.hibernate.proxy.pojo.bytebuddy.ByteBuddyInterceptor 오류는 JPA의 핵심 기능인 지연 로딩과 프록시 메커니즘에 대한 이해 부족에서 비롯되는 경우가 대부분입니다. 이 오류를 마주쳤을 때, 단순히 설정을 변경하여 오류를 억제하기보다는 그 근본 원인을 이해하고 애플리케이션의 설계 원칙에 맞는 해결책을 선택하는 것이 중요합니다.

상황별 권장 해결책 요약:

  1. 가장 이상적인 해결책 (Best Practice): DTO 패턴 사용
    • 이유: 관심사 분리, API 스펙의 안정성, 보안성, 직렬화 문제의 원천 봉쇄 등 소프트웨어 공학적으로 가장 올바른 접근법입니다.
    • 언제 사용: 모든 외부 공개 API. 특히 복잡한 도메인 모델을 다루는 애플리케이션이라면 필수적으로 고려해야 합니다.
  2. 차선책 (Pragmatic Choice): Fetch Join 또는 @EntityGraph
    • 이유: DTO를 만들 오버헤드가 부담스럽고, 엔티티 구조와 API 스펙이 거의 동일한 단순한 CRUD 애플리케이션에서 실용적인 대안입니다. 성능 최적화(N+1 방지)와 직렬화 문제를 동시에 해결할 수 있습니다.
    • 주의: 엔티티-뷰 결합 문제는 감수해야 합니다.
  3. 빠른 해결책 (Quick Fix): Jackson Hibernate5 Module
    • 이유: 기존 코드를 거의 건드리지 않고 빠르게 문제를 해결하고 싶을 때 사용합니다. 내부적으로 사용하는 관리자용 API 등에 제한적으로 적용해볼 수 있습니다.
    • 위험: `FORCE_LAZY_LOADING` 옵션은 성능에 치명적인 영향을 줄 수 있으므로 반드시 그 동작을 이해하고 사용해야 합니다.
  4. 권장하지 않는 방법 (Anti-Pattern): `fail-on-empty-beans=false`
    • 이유: 문제를 해결하는 것이 아니라 숨기는 것에 가깝습니다. API 응답에 불필요한 내부 구현이 노출되는 부작용이 있습니다.
    • 사용 시나리오: 다른 해결책을 적용하기 전, 아주 급하게 문제를 임시로 회피해야 할 때만 극히 제한적으로 사용하고, 반드시 추후 리팩토링 계획을 세워야 합니다.

결국 이 오류는 우리에게 JPA의 동작 방식을 더 깊이 공부하고, 더 나은 애플리케이션 아키텍처를 고민하게 만드는 좋은 기회입니다. DTO 패턴을 기본으로 채택하고, 필요에 따라 Fetch Join/EntityGraph를 활용하여 성능을 최적화하는 전략을 취한다면, 견고하고 유지보수하기 쉬우며 성능 좋은 애플리케이션을 만들어 나갈 수 있을 것입니다.


1 comment:

  1. AnonymousJuly 29, 2020 at 10:46:00 PM GMT+9

    덕분에 문제 해결했습니다. 감사합니다!

    ReplyDelete