MyBatis typeAliases 패키지 등록, 별칭을 못 찾을 때 확인할 설정

MyBatis Mapper XML을 작성하다 보면 resultType="memberDto"처럼 짧은 별칭을 썼는데 “별칭을 찾을 수 없다”는 오류가 나는 경우가 있다. 이때 DTO 클래스가 실제로 존재하는지부터 다시 만드는 것보다, MyBatis가 그 패키지를 스캔하도록 등록됐는지를 먼저 확인해야 한다.

typeAliases는 긴 패키지명을 매번 쓰지 않기 위한 편의 기능이지만, 설정 위치가 Spring Boot인지 XML 기반 Spring MVC인지에 따라 확인 지점이 달라진다. 특히 오래된 공공 프로젝트에서는 MyBatis 설정 파일, SqlSessionFactory Bean, Mapper XML이 나뉘어 있어 한 군데만 바꿔도 적용되지 않는 일이 흔하다.

핵심 정리: typeAliases는 DTO·VO의 긴 전체 클래스명을 짧은 별칭으로 바꾸는 기능이다. 패키지 등록, 클래스 위치, @Alias 이름, 실제로 로딩되는 SqlSessionFactory 설정을 순서대로 확인한다.

확인 순서: resultType 오타 확인 → DTO 실제 패키지 확인 → typeAliasesPackage 등록 확인 → @Alias 이름 확인 → 설정 파일 로딩 여부 확인 → 서버 재기동 후 Mapper XML 확인.

typeAliases가 필요한 이유

MyBatis Mapper XML에서 resultType이나 parameterType에 클래스 전체 경로를 매번 쓰면 설정이 길어지고 패키지 이동 때 수정 범위도 커진다. 예를 들어 com.example.project.member.dto.MemberDto 대신 memberDto처럼 짧게 적기 위해 typeAliases를 사용한다.

다만 별칭은 Java의 import처럼 자동으로 인식되지 않는다. MyBatis에 대상 패키지 또는 개별 클래스를 명시적으로 알려야 한다. 프로젝트 안에 DTO가 있어도 MyBatis 설정에 등록되지 않았다면 Mapper XML에서 별칭으로 사용할 수 없다.

전체 클래스명과 별칭의 차이

작성 방식	예시	특징
전체 클래스명	com.example.member.dto.MemberDto	설정 없이 바로 쓸 수 있지만 XML이 길어진다.
기본 별칭	memberDto	패키지 스캔 후 클래스명 기반으로 사용할 수 있다.
@Alias 지정	member	팀이 원하는 짧고 일관된 이름을 정할 수 있다.

처음 오류를 해결할 때는 resultType을 잠시 전체 클래스명으로 바꿔 보는 방법도 있다. 전체 클래스명으로는 동작하고 별칭만 실패한다면 SQL이나 resultMap 문제가 아니라 typeAliases 등록 범위 문제로 좁힐 수 있다.

Spring Boot에서 typeAliasesPackage 등록하기

Spring Boot와 MyBatis Starter를 사용한다면 설정 파일에 패키지 경로를 적는 방식이 가장 단순하다. DTO가 여러 하위 패키지에 있다면 공통 상위 패키지를 지정할 수 있다.

# application.yml
mybatis:
  mapper-locations: classpath:/mapper/**/*.xml
  type-aliases-package: com.example.project.**.dto

properties 형식이라면 아래처럼 작성한다.

mybatis.mapper-locations=classpath:/mapper/**/*.xml
mybatis.type-aliases-package=com.example.project.member.dto

설정 키가 맞아도 애플리케이션이 다른 profile을 읽고 있으면 반영되지 않는다. local, dev, prod 설정 파일을 나누는 프로젝트라면 실제 실행 profile과 해당 파일의 값을 먼저 확인한다. Mapper XML 위치까지 함께 점검해야 한다면 전자정부프레임워크의 Spring·MyBatis 구조를 기준으로 설정 계층을 나눠 보면 좋다.

패키지 경로는 실제 소스 구조와 일치해야 한다

com.example.project.dto로 등록했는데 실제 클래스가 com.example.project.member.vo 아래에 있다면 별칭은 등록되지 않는다. “상위 패키지를 넣었으니 모두 잡힐 것”이라고 가정하지 말고, 사용 중인 MyBatis 버전과 설정 방식에서 와일드카드가 어떻게 적용되는지 확인한다.

패키지 리팩터링 뒤에는 특히 이 문제가 잘 생긴다. Java 코드는 IDE import가 자동으로 고쳐 주지만, application.yml, XML Bean 설정, Mapper XML의 별칭은 자동으로 따라가지 않는다.

XML 기반 Spring MVC에서 등록하는 방법

전자정부프레임워크나 레거시 Spring MVC 프로젝트에서는 SqlSessionFactoryBean에 typeAliasesPackage를 넣는 방식이 흔하다. 중요한 점은 이 Bean이 실제 Mapper가 사용하는 SqlSessionFactory인지 확인하는 것이다.

<bean id="sqlSessionFactory"
      class="org.mybatis.spring.SqlSessionFactoryBean">
    <property name="dataSource" ref="dataSource" />
    <property name="typeAliasesPackage"
              value="com.example.project.member.dto" />
    <property name="mapperLocations"
              value="classpath:/mapper/**/*.xml" />
</bean>

프로젝트에 데이터소스가 두 개이거나 SqlSessionFactory가 여러 개라면, 한쪽 Bean만 수정하고 다른 쪽 Mapper를 실행하는 상황도 생긴다. 오류가 난 Mapper가 어떤 Factory에 연결되는지부터 따라가야 한다. 설정 파일 구조가 헷갈릴 때는 MyBatis Mapper 연동 흐름처럼 Mapper와 SqlSessionFactory가 만나는 지점부터 분리해서 읽는 습관이 중요하다.

mybatis-config.xml에 직접 등록하는 경우

Spring 설정과 별개로 mybatis-config.xml을 사용하는 프로젝트라면 aliases 섹션에서 패키지를 등록할 수 있다.

<configuration>
  <typeAliases>
    <package name="com.example.project.member.dto" />
  </typeAliases>
</configuration>

하지만 SqlSessionFactory Bean이 mybatis-config.xml을 실제로 읽지 않는다면 이 설정은 동작하지 않는다. 파일만 존재한다고 적용되는 것이 아니라, configLocation이 해당 파일을 가리키는지까지 확인해야 한다. 이 지점은 Oracle ORA-00904 오류처럼 보이는 SQL 문제와 구분해야 한다. 별칭을 못 찾는 오류는 DB까지 SQL이 전달되기 전의 설정 문제다.

@Alias를 사용할 때 기준

패키지 등록만 하면 보통 클래스 이름을 기준으로 별칭을 쓸 수 있다. 그러나 DTO 이름이 길거나 같은 이름의 클래스가 여러 패키지에 있다면 @Alias로 명시적인 이름을 정하는 편이 안전하다.

import org.apache.ibatis.type.Alias;

@Alias("member")
public class MemberDto {
    private Long memberId;
    private String memberName;
}

이후 Mapper XML에서는 resultType="member"라고 적을 수 있다. 다만 @Alias가 붙어 있어도 그 클래스를 포함하는 패키지가 스캔 대상이 아니면 인식되지 않는다. @Alias는 이름을 정하는 기능이고, 스캔 설정을 대신하지 않는다.

별칭 이름은 팀 규칙으로 고정한다

• DTO와 VO의 접미사를 유지할지 정한다. memberDto, boardVo처럼 클래스명과 맞추면 검색이 쉽다.
• 짧은 단어 충돌을 피한다. member, user, common 같은 범용 이름은 다른 모듈과 겹칠 수 있다.
• resultType과 parameterType에 같은 규칙을 쓴다. 화면마다 표기가 다르면 Mapper 유지보수가 어려워진다.
• DB 테이블명과 혼동하지 않는다. alias는 Java 타입 이름이지 테이블 별칭이 아니다.

별칭을 찾지 못할 때 확인 순서

1. resultType 문자열부터 확인한다

가장 단순한 원인은 철자 차이다. memberDTO와 memberDto는 다르다. 대소문자와 @Alias에 적은 이름을 정확히 맞춘다. XML 자동완성이 없는 환경에서는 복사 후 공백이 섞이는 경우도 있으니 오류 메시지의 alias 값을 그대로 비교한다.

2. 전체 클래스명으로 원인을 분리한다

<select id="selectMember"
        resultType="com.example.project.member.dto.MemberDto">
    SELECT MEMBER_ID, MEMBER_NAME
    FROM MEMBER
    WHERE MEMBER_ID = #{memberId}
</select>

이 상태에서 조회가 된다면 resultMap이나 컬럼명 문제가 아니라 별칭 등록 문제다. 반대로 전체 클래스명도 실패한다면 DTO 패키지, 빌드 산출물, ClassLoader, Mapper XML 문법까지 범위를 넓혀 확인한다.

3. 실제로 읽는 설정 파일을 확인한다

설정 파일을 고쳤는데 변화가 없다면 서버가 다른 설정 파일을 읽는 경우가 많다. Spring Boot는 active profile, 레거시 프로젝트는 contextConfigLocation과 Bean import 경로를 확인한다. 서버 재기동 없이 클래스나 XML만 교체하면 오래된 설정이 남는 경우도 있다.

4. 중복 별칭을 의심한다

서로 다른 패키지에 같은 클래스명이나 같은 @Alias가 있으면 어떤 타입을 써야 할지 모호해질 수 있다. 공통 모듈과 업무 모듈에 모두 UserDto가 있는 구조라면 별칭을 명시적으로 다르게 정하는 편이 낫다.

실무 팁

• 실무 팁 1: 신규 프로젝트에서는 DTO 패키지 구조와 별칭 규칙을 초기에 문서화한다. Mapper가 늘어난 뒤 정리하면 영향 범위가 커진다.
• 실무 팁 2: 오류가 나면 전체 클래스명으로 먼저 분리 진단한다. 이 한 번의 확인으로 SQL 문제와 typeAliases 문제를 빠르게 나눌 수 있다.
• 실무 팁 3: 설정을 바꾼 뒤에는 반드시 서버를 재기동하고 실제 Mapper 한 건을 호출한다. 컴파일 성공만으로 설정 반영을 판단하지 않는다.
• 실무 팁 4: typeAliases를 줄이기 위한 별칭이 오히려 너무 추상적이면 유지보수성이 나빠진다. 읽는 사람이 DTO를 바로 떠올릴 수 있는 이름을 선택한다.

자주 묻는 질문

• Q. typeAliases를 쓰지 않아도 MyBatis는 동작하나요? A. 동작합니다. resultType에 전체 클래스명을 쓰면 됩니다. typeAliases는 XML을 간결하게 만드는 편의 기능입니다.
• Q. @Alias만 붙이면 별칭이 자동 등록되나요? A. 아닙니다. 해당 클래스 또는 패키지가 MyBatis 스캔 대상이어야 합니다.
• Q. resultType과 resultMap에서 모두 별칭을 쓸 수 있나요? A. 가능합니다. 다만 resultMap id와 Java 타입 alias는 서로 다른 이름 공간이므로 혼동하지 않아야 합니다.
• Q. typeAliasesPackage에는 여러 패키지를 넣을 수 있나요? A. 설정 방식과 버전에 따라 구분자를 지원하지만, 무작정 넓게 잡기보다 DTO·VO 패키지 구조를 명확히 두는 편이 안전합니다.
• Q. 설정을 바꿨는데 alias 오류가 계속 납니다. A. 실제 실행 profile, configLocation, 사용 중인 SqlSessionFactory, 서버 재기동 여부를 순서대로 확인해야 합니다.
• Q. 별칭 이름은 대소문자를 구분하나요? A. 구현과 설정에 따라 혼동될 수 있으므로 @Alias에 적은 표기와 Mapper XML 표기를 완전히 같게 쓰는 팀 규칙을 권장합니다.

정리

MyBatis typeAliases 문제는 DTO가 없어서 생기는 경우보다 설정 범위가 실제 클래스 위치와 맞지 않아서 생기는 경우가 많다. 먼저 전체 클래스명으로 Mapper를 한 번 통과시켜 문제 범위를 좁히고, 그다음 typeAliasesPackage, @Alias, 실제 SqlSessionFactory 설정을 확인하면 된다.

별칭은 XML을 짧게 만드는 작은 기능이지만, 프로젝트가 커질수록 설정 규칙의 일관성이 중요해진다. 패키지 구조와 별칭 규칙을 함께 관리하면 Mapper XML을 읽고 수정하는 시간이 확실히 줄어든다.

별칭 오류는 SQL 오류가 아니라, MyBatis가 어떤 Java 타입을 읽을 수 있는지에 대한 설정 오류부터 확인하는 문제다.