Spring MyBatis 연동 설정 완전 정리 (Maven/Gradle)

Spring MyBatis 연동, 무엇을 설정해야 하나

Spring 프로젝트에 MyBatis를 붙일 때 필요한 설정은 결국 네 덩어리다. 의존성, DataSource, SqlSessionFactory, 매퍼 등록이다. 이 순서대로 잡으면 대부분 동작한다. Spring MyBatis 연동 설정이 헷갈리는 이유는 설정이 여러 파일에 흩어져 있고, 그중 하나만 빠져도 BindingException이나 mapper not found 같은 오류로 끝나기 때문이다.

아래는 XML 설정 방식(레거시·공공 SI에서 흔한 형태) 기준으로 정리한 것이다. Spring 버전과 빌드 도구(Maven/Gradle)에 따라 세부는 다를 수 있으니, 버전은 프로젝트에 맞게 조정한다.

전체 설정 요소 한눈에 보기

설정 요소	역할	주로 두는 위치
의존성	mybatis, mybatis-spring, spring-jdbc 등	pom.xml / build.gradle
DataSource	DB 연결 정보(커넥션 풀)	root-context.xml 등
SqlSessionFactory	MyBatis 핵심 객체 생성	root-context.xml 등
MapperScannerConfigurer	매퍼 인터페이스 자동 등록	root-context.xml 등
mybatis-config.xml	MyBatis 전역 설정(선택)	src/main/resources
매퍼 XML	실제 SQL 정의	resources/mappers 등

1단계. 의존성 추가 (Maven / Gradle)

1. Maven 설정

MyBatis 자체와, Spring에 붙여 주는 mybatis-spring이 둘 다 필요하다. DB 연결과 트랜잭션을 위한 spring-jdbc, 커넥션 풀, JDBC 드라이버도 함께 넣는다.

<!-- pom.xml (버전은 프로젝트에 맞게 조정) -->
<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis</artifactId>
    <version>3.5.x</version>
</dependency>
<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis-spring</artifactId>
    <version>2.x.x</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-jdbc</artifactId>
    <version>${spring.version}</version>
</dependency>
<!-- Oracle JDBC 드라이버, 커넥션 풀(HikariCP 등)도 별도 추가 -->

mybatis와 mybatis-spring은 버전 호환이 중요하다. mybatis-spring 버전이 MyBatis나 Spring 버전과 맞지 않으면 기동 시점에 에러가 나므로, 공식 호환표를 확인하고 맞춘다.

2. Gradle 설정

Gradle도 동일한 라이브러리를 선언만 다르게 한다.

// build.gradle (버전은 프로젝트에 맞게 조정)
dependencies {
    implementation 'org.mybatis:mybatis:3.5.x'
    implementation 'org.mybatis:mybatis-spring:2.x.x'
    implementation "org.springframework:spring-jdbc:${springVersion}"
    // Oracle JDBC 드라이버, 커넥션 풀 등 추가
}

드라이버는 DB에 맞춰 넣는다. Oracle은 라이선스·저장소 문제로 사내 저장소나 수동 설치가 필요한 경우가 있으니, 운영 환경 기준으로 확인한다.

2단계. DataSource 설정

DB 연결 정보를 담는 DataSource를 먼저 등록한다. 커넥션 풀은 환경에 맞는 것을 쓰되, 여기서는 형태만 본다.

<!-- root-context.xml -->
<bean id="dataSource" class="com.zaxxer.hikari.HikariDataSource" destroy-method="close">
    <property name="driverClassName" value="oracle.jdbc.OracleDriver" />
    <property name="jdbcUrl" value="jdbc:oracle:thin:@localhost:1521:ORCL" />
    <property name="username" value="scott" />
    <property name="password" value="${db.password}" />
</bean>

접속 정보, 특히 비밀번호는 소스에 직접 박지 말고 프로퍼티 파일이나 외부 설정으로 분리하는 것이 안전하다. 운영 정보는 형상관리에 올라가지 않도록 관리한다.

3단계. SqlSessionFactory 설정

1. SqlSessionFactoryBean 등록

MyBatis의 핵심 객체인 SqlSessionFactory를 만든다. DataSource를 연결하고, 매퍼 XML 위치와 (선택적으로) mybatis-config.xml을 지정한다.

<!-- root-context.xml -->
<bean id="sqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean">
    <property name="dataSource" ref="dataSource" />
    <!-- 매퍼 XML 위치 (classpath 기준) -->
    <property name="mapperLocations" value="classpath:mappers/**/*.xml" />
    <!-- MyBatis 전역 설정 파일 (선택) -->
    <property name="configLocation" value="classpath:mybatis-config.xml" />
</bean>

mapperLocations 경로가 실제 XML 위치와 다르면 SQL을 못 찾아 mapper not found가 난다. classpath: 기준 경로와 빌드 후 실제 위치(classes 아래)가 맞는지 확인한다.

2. SqlSessionTemplate (선택)

매퍼 인터페이스 방식을 쓰면 보통 직접 다루지 않지만, SqlSession을 직접 주입받아 쓰는 구조라면 SqlSessionTemplate을 등록한다.

<bean id="sqlSession" class="org.mybatis.spring.SqlSessionTemplate" destroy-method="clearCache">
    <constructor-arg ref="sqlSessionFactory" />
</bean>

최근 구조에서는 매퍼 인터페이스 + MapperScannerConfigurer 조합이 일반적이라 SqlSessionTemplate을 직접 쓸 일이 줄었다. 프로젝트 컨벤션에 맞춘다.

4단계. 매퍼 등록 (MapperScannerConfigurer)

매퍼 인터페이스를 일일이 빈으로 등록하는 대신, 패키지를 스캔해 자동 등록하는 방식이 편하다.

<!-- root-context.xml -->
<bean class="org.mybatis.spring.mapper.MapperScannerConfigurer">
    <!-- 매퍼 인터페이스가 있는 패키지 -->
    <property name="basePackage" value="com.example.**.mapper" />
    <property name="sqlSessionFactoryBeanName" value="sqlSessionFactory" />
</bean>

basePackage에 지정한 패키지의 인터페이스가 자동으로 빈이 된다. 이때 매퍼 인터페이스의 메서드 id와 XML의 <select id="...">가 일치해야 하고, XML의 namespace가 인터페이스의 풀 패키지명과 같아야 한다. 이 둘이 어긋나면 BindingException이 난다.

// 매퍼 인터페이스
package com.example.member.mapper;

public interface MemberMapper {
    MemberVO selectMember(String memberId);
}

<!-- MemberMapper.xml : namespace가 인터페이스 풀네임과 일치해야 함 -->
<mapper namespace="com.example.member.mapper.MemberMapper">
    <select id="selectMember" parameterType="string" resultType="com.example.member.vo.MemberVO">
        SELECT member_id, member_nm FROM member WHERE member_id = #{memberId}
    </select>
</mapper>

연동 후 동작 확인

설정을 마쳤으면 간단한 조회로 연결을 확인한다. 서비스나 테스트 코드에서 매퍼를 주입받아 호출해 본다.

@Autowired
private MemberMapper memberMapper;

public void test() {
    MemberVO m = memberMapper.selectMember("mem1001");
    System.out.println(m); // null이라도 예외 없이 오면 연동은 성공
}

예외 없이 호출되면 의존성·DataSource·SqlSessionFactory·매퍼 등록이 모두 맞은 것이다. 기동 로그에 DataSource 초기화나 매퍼 스캔 관련 메시지가 정상으로 찍히는지도 함께 본다.

연동 시 자주 나는 오류

• mapper not found — mapperLocations 경로와 실제 XML 위치 불일치, 또는 빌드 시 XML이 classes에 안 들어간 경우. 리소스 포함 설정을 확인한다.
• BindingException: Invalid bound statement — XML namespace가 인터페이스 풀네임과 다르거나, 메서드명과 SQL id가 안 맞는 경우.
• 버전 비호환 — mybatis-spring 버전이 MyBatis/Spring과 안 맞아 기동 실패. 호환표 확인.
• DataSource 연결 실패 — URL·계정·드라이버 오타, 또는 방화벽/포트 문제. 로컬에서 DB 접속부터 확인한다.
• 매퍼 패키지 스캔 누락 — basePackage가 실제 인터페이스 위치와 달라 빈 등록이 안 된 경우.

FAQ

Q1. mybatis와 mybatis-spring을 둘 다 넣어야 하나요?

그렇다. mybatis는 핵심 라이브러리, mybatis-spring은 Spring과 연결해 주는 모듈이다. 둘 다 필요하고 버전 호환을 맞춰야 한다.

Q2. mybatis-config.xml은 꼭 있어야 하나요?

필수는 아니다. 전역 설정(카멜케이스 매핑, typeAlias 등)이 필요할 때 쓴다. 없으면 configLocation 속성을 빼도 된다.

Q3. BindingException이 계속 납니다.

매퍼 XML의 namespace가 인터페이스 풀 패키지명과 정확히 같은지, 메서드명과 SQL의 id가 일치하는지 확인한다. 가장 흔한 원인이다.

Q4. 매퍼 XML이 빌드 결과물에 안 들어갑니다.

XML을 src/main/java 아래 둔 경우 빌드 시 제외될 수 있다. resources로 옮기거나, 빌드 설정에서 java 폴더의 xml도 리소스로 포함하도록 지정한다.

Q5. Spring Boot에서도 같은 방식인가요?

Spring Boot는 mybatis-spring-boot-starter로 대부분 자동 설정돼 더 간단하다. 위 방식은 XML 설정 기반(레거시·공공 SI) 기준이다.

정리

Spring MyBatis 연동 설정은 의존성 → DataSource → SqlSessionFactory → 매퍼 등록 순서로 잡으면 막힘없이 동작한다. 의존성은 mybatis와 mybatis-spring을 버전 호환에 맞춰 넣고, SqlSessionFactory에 DataSource와 매퍼 위치를 연결한 뒤, MapperScannerConfigurer로 인터페이스를 자동 등록한다. 연동이 안 되면 대부분 mapperLocations 경로, XML namespace, 버전 호환 세 가지에서 원인을 찾을 수 있다. Spring 버전, 빌드 도구, Boot 사용 여부에 따라 세부가 달라지므로, 운영 적용 전에는 로컬·테스트 환경에서 조회 한 건으로 연동을 먼저 확인하는 것이 안전하다.