Json Transcoder 설계 과정

ARCUS 캐시를 위한 Json Transcoder 클래스를 설계하면서 타입 소거 개념에 대해 추가적으로 알게 된 내용이 있어서 블로그에 남겨두려고 한다.

이 클래스는 encode/decode 메서드로 직렬화/역직렬화를 진행하는데, decode의 경우에는 어떤 클래스로 디코딩을 하느냐에 대한 고민 지점이 있었다.

처음 설계할 때, decode 메서드를 오버로딩해서 Class<T>나 TypeReference<T>를 명시적으로 전달하는 메서드를 만드려고 했는데, 다음과 같은 생각이 떠올랐다:

"애초부터 transcoder 인스턴스를 제네릭 <T>로 만들면, 그 T로 TypeReference<T> 전달이 가능하지 않을까?"

 

즉, new TypeReference<T>() {}를 decode 메서드 내부에서 생성하여 타입 정보를 전달하면 굳이 메서드를 여러 개 만들지 않아도 되지 않을까 하는 생각이었다.

결론부터 말하자면, Java의 타입 소거(Type Erasure) 특성상 런타임에 제네릭 타입 정보가 손실되어 제대로 동작하지 않는다.

 

이 과정에서 알게 된 내용을 정리해보자.

TypeReference의 동작 원리

Jackson의 TypeReference는 Super Type Token 패턴을 사용하여 제네릭 타입 정보를 런타임에 보존한다.

내부 구조는 다음과 같다:

package com.fasterxml.jackson.core.type;

import java.lang.reflect.ParameterizedType;
import java.lang.reflect.Type;

public abstract class TypeReference<T> implements Comparable<TypeReference<T>>
{
    protected final Type _type;

    protected TypeReference()
    {
        Type superClass = getClass().getGenericSuperclass();
        if (superClass instanceof Class<?>) { // sanity check, should never happen
            throw new IllegalArgumentException("Internal error: TypeReference constructed without actual type information");
        }
        /* 22-Dec-2008, tatu: Not sure if this case is safe -- I suspect
         *   it is possible to make it fail?
         *   But let's deal with specific
         *   case when we know an actual use case, and thereby suitable
         *   workarounds for valid case(s) and/or error to throw
         *   on invalid one(s).
         */
        _type = ((ParameterizedType) superClass).getActualTypeArguments()[0];
    }

    public Type getType() { return _type; }

    /**
     * The only reason we define this method (and require implementation
     * of <code>Comparable</code>) is to prevent constructing a
     * reference without type information.
     */
    @Override
    public int compareTo(TypeReference<T> o) { return 0; }
    // just need an implementation, not a good one... hence ^^^
}

이 클래스의 핵심은, 익명 내부 클래스를 생성할 때 제네릭 타입 정보가 컴파일 타임에 보존된다는 것이다.

 

Java의 타입 소거 문제

Java의 제네릭은 컴파일 타임에만 존재하고 런타임에는 소거된다.

그렇기 때문에, 메서드 내부에서 new TypeReference<T>() {}를 생성하면, T는 이미 Object로 타입 소거된 상태이므로 의미가 없어진다.

정확히 예시를 들어보자면

TestTranscoder<List<Employee>> transcoder = new TestTranscoder<>();

이렇게 코드를 작성했을 때, 컴파일러는 T가 List<Employee> 라는 것을 알고 있다.

하지만 이 타입 정보는 런타임에 모두 지워지므로, 자바는 TestTranscoder가 어떤 T로 인스턴스화되었는지 런타임에는 알 수가 없다.

올바른 사용법

TypeReference<Employee> typeRef = new TypeReference<Employee>() {}; // 익명 내부 클래스 생성
Employee employee = objectMapper.readValue(json, typeRef);

잘못된 사용법

public <T> Object decode(byte[] data) {
    TypeReference<T> typeRef = new TypeReference<T>() {}; // T는 이미 소거됨
    return objectMapper.readValue(data, typeRef);
}

실제 테스트 코드로 검증

위 내용을 테스트 코드를 통해 검증해보고자 Employee, TestTranscoder 클래스를 임시로 구현하였다.

public class TestTranscoder<T> {
    
    private final ObjectMapper objectMapper;
    
    public TestTranscoder(ObjectMapper objectMapper) {
        this.objectMapper = objectMapper;
    }
    
    // 방법 1: Class 명시적 전달 (정상)
    public T decodeWithClass(byte[] data, Class<T> clazz) {
        try {
            return objectMapper.readValue(data, clazz);
        } catch (Exception e) {
            throw new RuntimeException("Decode with class failed", e);
        }
    }
    
    // 방법 2: TypeReference 명시적 전달 (정상)
    public T decodeWithTypeReference(byte[] data, TypeReference<T> typeRef) {
        try {
            return objectMapper.readValue(data, typeRef);
        } catch (Exception e) {
            throw new RuntimeException("Decode with TypeReference failed", e);
        }
    }
    
    // 방법 3: 제네릭 T로 TypeReference 생성 (타입 소거)
    public Object decodeWithGenericTypeReference(byte[] data) {
        try {
            // 이 방식은 타입 정보가 이미 손실된 상태
            TypeReference<T> typeRef = new TypeReference<T>() {};
            return objectMapper.readValue(data, typeRef);
        } catch (Exception e) {
            throw new RuntimeException("Decode with generic TypeReference failed", e);
        }
    }
    
    public byte[] encode(T object) {
        try {
            return objectMapper.writeValueAsBytes(object);
        } catch (Exception e) {
            throw new RuntimeException("Encode failed", e);
        }
    }
}

테스트 케이스

테스트는 전부 통과한다.

class TestTranscoderTest {
    
    private ObjectMapper objectMapper;
    private TestTranscoder<Employee> employeeTranscoder;
    private TestTranscoder<List<Employee>> listTranscoder;
    
    @BeforeEach
    void setUp() {
        objectMapper = new ObjectMapper();
        employeeTranscoder = new TestTranscoder<>(objectMapper);
        listTranscoder = new TestTranscoder<>(objectMapper);
    }
    
    @Test
    @DisplayName("Class를 사용한 역직렬화는 정상 동작한다")
    void testDecodeWithClass_Success() {
        // Given
        Employee original = new Employee(1L, "김직원", null);
        byte[] serialized = employeeTranscoder.encode(original);
        
        // When
        Employee decoded = employeeTranscoder.decodeWithClass(serialized, Employee.class);
        
        // Then
        assertThat(decoded).isNotNull();
        assertThat(decoded).isInstanceOf(Employee.class);
        assertThat(decoded.getId()).isEqualTo(1L);
        assertThat(decoded.getName()).isEqualTo("김직원");
    }
    
    @Test
    @DisplayName("명시적 TypeReference를 사용한 역직렬화는 정상 동작한다")
    void testDecodeWithExplicitTypeReference_Success() {
        // Given
        Employee original = new Employee(1L, "김직원", null);
        byte[] serialized = employeeTranscoder.encode(original);
        TypeReference<Employee> typeRef = new TypeReference<Employee>() {};
        
        // When
        Employee decoded = employeeTranscoder.decodeWithTypeReference(serialized, typeRef);
        
        // Then
        assertThat(decoded).isNotNull();
        assertThat(decoded).isInstanceOf(Employee.class);
        assertThat(decoded.getId()).isEqualTo(1L);
        assertThat(decoded.getName()).isEqualTo("김직원");
    }
    
    @Test
    @DisplayName("제네릭 T로 생성한 TypeReference는 타입 정보가 손실된다")
    void testDecodeWithGenericTypeReference_TypeErasure() {
        // Given
        Employee original = new Employee(1L, "김직원", null);
        byte[] serialized = employeeTranscoder.encode(original);
        
        // When
        Object decoded = employeeTranscoder.decodeWithGenericTypeReference(serialized);
        
        // Then
        assertThat(decoded).isNotNull();
        // 타입 소거로 인해 Employee가 아닌 Map으로 역직렬화됨
        assertThat(decoded).isInstanceOf(Map.class);
        assertThat(decoded).isNotInstanceOf(Employee.class);
        
        // Map으로 캐스팅해서 데이터 확인
        @SuppressWarnings("unchecked")
        Map<String, Object> map = (Map<String, Object>) decoded;
        assertThat(map.get("id")).isEqualTo(1);
        assertThat(map.get("name")).isEqualTo("김직원");
    }
    
    @Test
    @DisplayName("리스트 타입에서도 동일한 문제가 발생한다")
    void testListTypeErasure() {
        // Given
        List<Employee> originalList = List.of(
            new Employee(1L, "김직원", null),
            new Employee(2L, "박직원", null)
        );
        byte[] serialized = listTranscoder.encode(originalList);
        
        // 명시적 TypeReference 사용 (정상)
        TypeReference<List<Employee>> explicitTypeRef = new TypeReference<List<Employee>>() {};
        List<Employee> decodedWithExplicit = listTranscoder.decodeWithTypeReference(serialized, explicitTypeRef);
        
        // 제네릭 TypeReference 사용 (타입 소거)
        Object decodedWithGeneric = listTranscoder.decodeWithGenericTypeReference(serialized);
        
        // Then
        // 명시적 TypeReference는 정상 동작
        assertThat(decodedWithExplicit).hasSize(2);
        assertThat(decodedWithExplicit.get(0)).isInstanceOf(Employee.class);
        assertThat(decodedWithExplicit.get(0).getName()).isEqualTo("김직원");
        
        // 제네릭 TypeReference는 타입 정보 손실
        assertThat(decodedWithGeneric).isInstanceOf(List.class);
        @SuppressWarnings("unchecked")
        List<Object> genericList = (List<Object>) decodedWithGeneric;
        assertThat(genericList).hasSize(2);
        // 리스트 요소들이 Map으로 역직렬화됨
        assertThat(genericList.get(0)).isInstanceOf(Map.class);
        assertThat(genericList.get(0)).isNotInstanceOf(Employee.class);
    }
    
    @Test
    @DisplayName("타입 소거된 객체를 Employee로 캐스팅하면 ClassCastException이 발생한다")
    void testClassCastException() {
        // Given
        Employee original = new Employee(1L, "김직원", null);
        byte[] serialized = employeeTranscoder.encode(original);
        
        // When
        Object decoded = employeeTranscoder.decodeWithGenericTypeReference(serialized);
        
        // Then
        assertThrows(ClassCastException.class, () -> {
            Employee employee = (Employee) decoded;
        });
    }
    
    @Test
    @DisplayName("중첩된 객체에서도 타입 정보 손실이 발생한다")
    void testNestedObjectTypeErasure() {
        // Given
        Employee manager = new Employee(1L, "김매니저", null);
        Employee employee = new Employee(2L, "박직원", manager);
        byte[] serialized = employeeTranscoder.encode(employee);
        
        // When - 제네릭 TypeReference 사용
        Object decoded = employeeTranscoder.decodeWithGenericTypeReference(serialized);
        
        // Then
        assertThat(decoded).isInstanceOf(Map.class);
        @SuppressWarnings("unchecked")
        Map<String, Object> empMap = (Map<String, Object>) decoded;
        
        // 중첩된 manager 객체도 Map으로 역직렬화됨
        Object managerObj = empMap.get("manager");
        assertThat(managerObj).isInstanceOf(Map.class);
        assertThat(managerObj).isNotInstanceOf(Employee.class);
        
        @SuppressWarnings("unchecked")
        Map<String, Object> managerMap = (Map<String, Object>) managerObj;
        assertThat(managerMap.get("name")).isEqualTo("김매니저");
    }
}

테스트 결과

1. 타입 소거 확인: decodeWithGenericTypeReference() 메서드는 Employee 객체가 아닌 LinkedHashMap으로 역직렬화된다.
2. 런타임 오류 발생: 타입 소거된 객체를 Employee로 캐스팅하려 하면 ClassCastException이 발생한다.
3. 중첩 타입 문제: 리스트나 중첩된 객체에서도 동일한 문제가 발생하여, 모든 객체가 Map으로 변환된다.
4. 명시적 전달의 필요성: Class<T>나 TypeReference<T>를 명시적으로 전달하는 방식만이 올바른 타입 정보를 보존할 수 있다.

레퍼런스

- https://docs.oracle.com/javase/tutorial/java/generics/erasure.html

- https://stackoverflow.com/questions/6846244/jackson-and-generic-type-reference