MyBatis에서 @Mapper 사용법과 주의사항 완벽 정리

MyBatis는 @Mapper 어노테이션을 사용하여 인터페이스 기반 SQL 매핑을 지원합니다. Spring Boot 환경에서 @Mapper는 SQL을 호출할 수 있는 인터페이스를 빈으로 등록해주는 중요한 어노테이션입니다. 이 글에서는 @Mapper 사용 방법, @MapperScan 설정, XML 연동 방식, 실무에서 주의할 점을 정리합니다.

1. @Mapper란?

@Mapper는 MyBatis Mapper 인터페이스를 스프링 빈으로 자동 등록해주는 어노테이션입니다. application.yml의 설정이나 XML 없이도 인터페이스만으로 동작 가능합니다.

기본 예제

@Mapper
public interface UserMapper {
    User selectUser(Long id);
    void insertUser(User user);
}

위 인터페이스는 UserMapper.xml에 정의된 SQL과 자동으로 연결됩니다. 또는 어노테이션 기반(@Select, @Insert 등)으로도 사용 가능합니다.

2. @MapperScan 사용

매퍼가 여러 개일 경우, @MapperScan으로 패키지 전체를 등록할 수 있습니다.

@SpringBootApplication
@MapperScan("com.example.mapper")
public class MyApp {
    public static void main(String[] args) {
        SpringApplication.run(MyApp.class, args);
    }
}

장점

각 인터페이스마다 @Mapper를 생략 가능
패키지 기반 자동 등록으로 유지보수 편리

3. 어노테이션 기반 SQL 사용 예

XML을 사용하지 않고 어노테이션으로 직접 SQL 작성도 가능합니다.

@Mapper
public interface UserMapper {

    @Select("SELECT * FROM users WHERE id = #{id}")
    User selectUser(Long id);

    @Insert("INSERT INTO users(name, age) VALUES(#{name}, #{age})")
    @Options(useGeneratedKeys = true, keyProperty = "id")
    void insertUser(User user);
}

4. XML 방식과의 관계

XML + @Mapper: 가장 일반적인 방식 (SQL 분리, 유지보수 ↑)
어노테이션 기반: 간단한 쿼리에 적합, 복잡한 SQL에는 부적합
주의: @Mapper 없이 등록 시 MapperNotFoundException 발생

5. Mapper 인터페이스와 XML의 매핑 규칙

namespace: 인터페이스 FQCN과 동일해야 함
id: 인터페이스 메서드명과 일치해야 함
resultType, parameterType: XML에 정확히 매핑되어야 함

예시

<mapper namespace="com.example.mapper.UserMapper">

  <select id="selectUser" resultType="User" parameterType="long">
    SELECT * FROM users WHERE id = #{id}
  </select>

</mapper>

6. 실무 주의사항

패키지 경로 실수 → XML 매핑 안됨
@Mapper 또는 @MapperScan 누락 → 빈 등록 안됨
동일한 id 중복 사용 주의
Mapper 인터페이스는 interface로 정의해야 함 (class ×)

7. 결론

@Mapper는 MyBatis에서 SQL Mapper를 간편하게 스프링에 등록할 수 있도록 해주는 핵심 어노테이션입니다. XML 방식이든 어노테이션 방식이든, 프로젝트 성격과 유지보수성을 고려해 선택하는 것이 중요하며, @MapperScan을 활용하면 대규모 프로젝트에서도 효율적인 관리가 가능합니다.

MyBatis에서 자동 생성된 PK값 조회하기 – useGeneratedKeys vs selectKey 완전 정리 (4)	2025.05.20
MyBatis 동적 SQL 완벽 가이드 – if, choose, foreach 실무 활용법 (2)	2025.05.20
MyBatis Mapper XML 완벽 이해 – resultType, parameterType, resultMap 차이 정리 (0)	2025.05.20
MyBatis 기초 가이드 – 설정부터 첫 쿼리까지 완벽 정리 (0)	2025.05.20

전지적라온시점

전지적라온시점