요약
@MappedTypes(Set.class) 로 등록한 Custom TypeHandler 가 INSERT 에서 동작하지 않는다면, Mapper XML 의 parameterType 속성을 명시했는지부터 확인하시면 됩니다.
parameterType 이 없으면 MyBatis 는 파라미터를 Object 로 취급합니다. 그래서 런타임에 값 객체의 실제 클래스(LinkedHashSet 등) 로 TypeHandler 를 다시 찾는데, TypeHandlerRegistry 는 슈퍼클래스만 탐색할 뿐 인터페이스 계층은 따라가지 않습니다.
결국 Set 인터페이스로 등록한 핸들러는 매칭되지 않고, ObjectTypeHandler 로 폴백되어 ps.setObject(i, hashSet) 가 호출됩니다.
문제 상황
Set<PayMethod> 를 콤마 문자열로 저장하려고 Custom TypeHandler 를 작성했습니다.
@MappedTypes(Set.class)
@MappedJdbcTypes(value = JdbcType.VARCHAR, includeNullJdbcType = true)
public class PayMethodSetTypeHandler extends BaseTypeHandler<Set<PayMethod>> { ... }
Mapper XML 은 단순했습니다.
<insert id="insertUser">
INSERT INTO my_user (id, name, pay_methods)
VALUES (#{id}, #{name}, #{payMethods})
</insert>
그런데 INSERT 를 실행하자 이해하기 힘든 에러가 발생했습니다.
org.h2.jdbc.JdbcSQLDataException:
Data conversion error converting
"CAST(X'aced0005737200176a6176612e7574696c2e4c696e6b656448617368536574...' AS JAVA_OBJECT)"
에러 메시지에 보이는 X'aced0005...' 는 Java 직렬화 객체의 매직 넘버입니다. 즉 LinkedHashSet 이 통째로 직렬화된 바이트가 DB 로 전달되었다는 뜻입니다. TypeHandler 를 분명히 등록했는데, 왜 호출되지 않았을까요?
원인 분석
TypeHandler 내부에 로그를 남겨두고 다시 실행해봤습니다. 예상대로 핸들러가 단 한 번도 호출되지 않았습니다.
여기서 한 가지 가설을 세워봤습니다.
parameterType 을 생략하면 MyBatis 는 파라미터 타입을 Object 로 간주합니다. 그러면 파싱 시점에 #{payMethods} 의 javaType 을 추론할 수 없어 UnknownTypeHandler 가 선택되고, 런타임에 값 객체의 getClass() 로 다시 핸들러를 찾습니다.
이때 호출되는 TypeHandlerRegistry.getJdbcHandlerMapForSuperclass() 는 슈퍼클래스만 재귀적으로 타고 올라갑니다. LinkedHashSet → HashSet → AbstractSet → AbstractCollection → Object 어느 단계에도 Set 인터페이스는 없기 때문에, @MappedTypes(Set.class) 로 등록한 핸들러는 끝내 발견되지 않습니다.
두 방식을 나란히 비교해봤습니다
가설을 검증하기 위해 동일한 쿼리를 두 벌 준비했습니다.
A. parameterType 을 명시한 버전
<insert id="insertUser" parameterType="com.example.MyDto">
INSERT INTO my_user (id, name, pay_methods)
VALUES (#{id}, #{name}, #{payMethods})
</insert>
B. parameterType 을 생략한 버전
<insert id="insertUser">
INSERT INTO my_user (id, name, pay_methods)
VALUES (#{id}, #{name}, #{payMethods})
</insert>
TypeHandler 에는 호출 횟수를 기록할 카운터를 추가해두었습니다.
public static final AtomicInteger setNonNullParameterCount = new AtomicInteger(0);
결과는 다음과 같았습니다.
| 시나리오 |
TypeHandler 호출 |
DB 저장값 |
결과 |
| A. parameterType 명시 |
1회 |
CARD,CASH |
성공 |
| B. parameterType 생략 |
0회 |
(직렬화 바이트) |
예외 |
값 객체를 HashSet, LinkedHashSet, Collections.unmodifiableSet 으로 바꿔가며 여러 번 실행해봐도 B 는 구현체와 무관하게 동일하게 실패했습니다. 인터페이스 계층을 탐색하지 않는다는 가설과 정확히 맞아떨어지는 결과입니다.
그런데 SELECT 는 왜 멀쩡할까요?
SELECT 는 parameterType 유무와 관계없이 모두 정상 동작했습니다. 더 놀라운 건 resultType 마저 생략한 XML 도 정상 동작했다는 점입니다.
<!-- resultType / resultMap 둘 다 없음 -->
<select id="selectUser">
SELECT id, name, pay_methods AS payMethods FROM my_user WHERE id = #{id}
</select>
MyDto selectUser(long id);
실행해보면 TypeHandler 도 제대로 호출되고, MyDto 에 Set<PayMethod> 가 잘 복원됩니다. MyBatis 가 인터페이스 메서드의 리턴 타입을 폴백으로 활용하고 있기 때문입니다.
진짜 경계선: INSERT/UPDATE 가 아니라, "파라미터 바인딩 vs 결과 매핑"
여기서 중요한 비대칭이 드러납니다.
| 경로 |
인터페이스 시그니처 활용 |
parameterType / resultType 누락 시 |
파라미터 바인딩 (#{}) |
❌ 안 함 |
Object 로 폴백 → TypeHandler 매칭 실패 |
| 결과 매핑 (SELECT 리턴) |
✅ 메서드 리턴 타입으로 폴백 |
정상 동작 |
왜 이런 비대칭이 생길까요?
- 리턴 타입 경로: 런타임에
MapperMethod.execute() 가 메서드 시그니처의 리턴 타입을 확인해 selectOne / selectList / Cursor 등으로 분기하고, 결과 조립 단계에 리턴 타입 힌트를 전달합니다. 즉 실행 타임마다 메서드 정보가 다시 참조됩니다.
- 파라미터 타입 경로:
ParameterMapping 은 XML 파싱 시점에 javaType 과 TypeHandler 가 확정되어 MappedStatement 에 박혀버립니다. 이후 실행할 때 그 값을 그대로 사용할 뿐, 메서드 시그니처를 소급 반영하지 않습니다.
즉 문제가 발생하는 진짜 경계선은 "INSERT/UPDATE" 가 아니라 "파라미터 바인딩을 타는가" 입니다.
그럼 SELECT 도 위험할 수 있습니다
파라미터 바인딩은 SELECT 의 WHERE 절에서도 일어납니다. 아래처럼 커스텀 타입을 WHERE 에 넣는 순간 SELECT 에서도 동일하게 재현됩니다.
<select id="findByPayMethods" resultType="com.example.MyDto">
SELECT * FROM my_user WHERE pay_methods = #{payMethods}
</select>
MyDto findByPayMethods(Set<PayMethod> payMethods);
INSERT 와 똑같은 경로를 타기 때문에 parameterType 이 없으면 ps.setObject 폴백이 일어납니다.
실전에서 SELECT 가 잘 안 터졌던 이유는, 조회 파라미터가 보통 long id, String status 같은 기본형/원시 타입 이기 때문입니다. 이런 타입들은 MyBatis 에 기본 TypeHandler 가 이미 등록돼 있어 parameterType 없이도 아무 문제가 없습니다.
반면 INSERT/UPDATE 는 DTO 의 여러 필드를 #{} 로 한꺼번에 풀어 넣는 과정에서 커스텀 타입이 섞여 들어가기 쉬워, 이 함정에 자주 걸립니다.
한 줄로 정리하면
Custom TypeHandler 가 무시되는 조건은 "#{} 에 커스텀 타입을 바인딩하는데 parameterType 이 없을 때" 입니다.
INSERT/UPDATE/DELETE 든 SELECT 의 WHERE 절이든 동일하게 발생합니다.
다만 결과 매핑 쪽은 XML resultType 이 없어도 인터페이스 리턴 타입으로 폴백되어 안전합니다.
"Mapper Interface 에 MyDto 가 선언돼 있는데, 왜 그걸 못 읽어오나요?"
인터페이스에 void insertUser(MyDto dto) 가 분명히 있으니, MyBatis 가 그 정보를 parameterType 으로 그대로 써주면 될 것 같죠.
하지만 실제로는 그렇게 동작하지 않습니다. MyBatis 는 XML 파싱과 Mapper Interface 바인딩을 분리된 단계로 처리하기 때문입니다.
XML 파싱 시점에는 어떤 인터페이스 메서드에 연결될지 모른 채 parameterType 속성만 보고 MappedStatement 를 완성합니다. 이후 Mapper 바인딩 단계에서 메서드 시그니처는 @Param 이름 매핑과 반환 타입 처리에만 쓰일 뿐, 이미 확정된 parameterType 은 덮어쓰지 않습니다.
그래서 인터페이스에 MyDto 가 있어도, XML 에 parameterType 이 없으면 MyBatis 는 파라미터를 Object 로 취급합니다. (리턴 타입 쪽은 앞서 본 것처럼 실행 타임마다 메서드 시그니처를 다시 참조하기 때문에 XML 에 resultType 이 없어도 인터페이스 리턴 타입으로 폴백됩니다 — 파라미터 쪽만 이 폴백이 없는 것입니다.)
그럼 @Insert 어노테이션으로 쓰면요?
어노테이션 기반으로 작성하면 이야기가 달라집니다. 어노테이션 처리 단계에서는 메서드 시그니처에서 파라미터 타입을 직접 추론하므로, 같은 코드라도 TypeHandler 가 제대로 호출됩니다.
@Insert("INSERT INTO my_user (id, name, pay_methods) VALUES (#{id}, #{name}, #{payMethods})")
void insertUser(MyDto dto); // parameterType 이 MyDto 로 추론됨
즉 MyBatis 가 "메서드 시그니처를 읽지 못하는 것" 이 아니라, XML 경로에서만 그 정보를 활용하지 않는 것입니다.
| 경로 |
parameterType 결정 방법 |
| XML 매퍼 |
XML 의 parameterType 속성만 사용 (메서드 시그니처 무시) |
| 어노테이션 매퍼 |
메서드 시그니처에서 추론 |
| 혼용 시 |
XML 이 우선, 어노테이션 무시 |
그래서 이 버그는 XML 매퍼를 쓸 때만 발생합니다. 같은 로직을 @Insert 로 작성했다면 애초에 문제되지 않았을 거고요.
해결 방법
세 가지 선택지가 있습니다.
① parameterType 속성을 명시한다 — 가장 간단
<insert id="insertUser" parameterType="com.example.MyDto">
...
</insert>
② #{} 표현식에 직접 typeHandler 를 지정한다
VALUES (
#{id},
#{name},
#{payMethods, typeHandler=com.example.PayMethodSetTypeHandler}
)
③ @MappedTypes 에 구체 구현체를 모두 나열한다 — 권장하지 않음
@MappedTypes({HashSet.class, LinkedHashSet.class, ...})
새로운 구현체가 등장할 때마다 추가해야 하므로 취약합니다.
정리
Custom TypeHandler 가 "분명히 등록했는데 호출되지 않는" 증상의 흔한 원인은, MyBatis 의 TypeHandler 탐색이 인터페이스 계층을 따라가지 않는다는 점입니다. 기억할 포인트는 두 가지입니다.
- 파싱 타임 해결:
parameterType 이 있을 때. 클래스의 필드/프로퍼티 선언 타입으로 결정됩니다.
- 런타임 해결:
parameterType 이 없을 때. 값 객체의 getClass() 로 결정되며, 인터페이스는 무시됩니다.
XML 에 parameterType 한 줄을 추가하면 모든 해결 과정이 파싱 타임으로 옮겨가고, 인터페이스로 등록한 TypeHandler 도 안정적으로 호출됩니다. 혹시 비슷한 증상을 만나셨다면, 가장 먼저 이 속성을 확인해보시면 좋을 것 같습니다.