MyBatis

MyBatis는 Java Object와 SQL 문 사이의 자동 매핑을 지원하는 Persistence Framework다. 핵심은 SQL을 Java 코드 밖의 별도 파일(Mapper XML)로 분리하고, Java 객체와 SQL 파라미터/결과 사이의 매핑 작업을 대신 처리하는 것이다.^[1] Spring과 함께 쓸 때는 MyBatis 관련 Bean을 Spring Container에 등록하고, Spring의 트랜잭션 기능을 함께 쓰면 Spring Transaction의 @Transactional 기반으로 트랜잭션을 처리할 수 있다.^[1:1] 이를 Spring Framework Core의 PSA/DI 사례로 보고 JPA·MyBatis 어느 쪽을 쓰든 @Transactional이 동일하게 트랜잭션을 관리한다고 연결하는 것은 이 page의 해석이다.

MyBatis vs JPA/Hibernate

• MyBatis는 Hibernate/JPA처럼 새 ORM 패러다임을 깊게 익혀야 하는 부담이 상대적으로 적다. 개발자가 익숙한 SQL을 그대로 사용하면서 JDBC 반복 작업을 줄인다.^[2]
• JDBC의 기능을 대부분 제공하면서 복잡한 JDBC 코드를 걷어내고 소스 코드를 간결하게 유지한다. 수동 파라미터 설정이나 ResultSet 객체 매핑 코드를 줄여 준다.^[3]
• SQL과 프로그래밍 코드의 분리: SQL이 바뀌어도 Java 코드 수정·재컴파일이 불필요하다. SQL 작성·관리·검토를 DBA 등 다른 역할과 분리할 수 있고, SQL을 명시적으로 관리하므로 쿼리 튜닝이 비교적 쉽다.^[4]

MyBatis 3 주요 컴포넌트

flowchart TB
  Config["SqlSessionFactoryBuilder
→ Configuration (XML/Annotation)"]
  Factory["SqlSessionFactory
→ SqlSession 생성"]
  Session["SqlSession
→ SQL 실행 + 매핑"]
  Mapper["Mapper Interface
→ type-safe SQL 호출"]
  DB["Database"]
  Config --> Factory --> Session
  Session --> Mapper
  Mapper --> DB

Mapper Interface와 namespace 매핑

Mapper Interface는 XML mapper의 namespace와 인터페이스 FQCN(Fully Qualified Class Name)이 일치하고, 메서드명과 SQL id가 일치하면 자동 매핑된다.^[6]

// Mapper Interface
public interface BoardMapper {
    BoardDto findById(int id);  // → XML: <select id="findById" resultType="BoardDto">
}

// 호출
BoardDto board = sqlSession.getMapper(BoardMapper.class).findById(1);

Mapper Interface를 XML mapper와 연결하려면 다음 규칙을 맞춰야 한다.

• XML 없이 Annotation으로도 SQL을 정의할 수 있다(@Select, @Insert, @Update, @Delete).
• Mapper Interface를 쓰면 sqlSession.selectOne("namespace.id", param) 같은 문자열 기반 호출보다 오타를 줄일 수 있고, IDE의 code assist(자동완성)를 활용하기 쉽다. 문자열 기반 호출에서는 오타가 런타임 버그로 이어지기 쉽다.^[6:1]

MyBatis-Spring 연동

MyBatis-Spring은 Spring 애플리케이션과 MyBatis 3 사이를 연결하는 역할을 한다.^[7] 핵심 Bean은 다음과 같다.

다음 Java Config 예시(@MapperScan 포함)는 원문에 없는 이 page의 보충 예시이며, 원문은 XML bean 등록과 <mybatis-spring:scan>을 사용한다.^[9:2]

@Configuration
@MapperScan("com.example.mapper")
public class MyBatisConfig {
    @Bean
    public SqlSessionFactoryBean sqlSessionFactory(DataSource dataSource) throws Exception {
        SqlSessionFactoryBean factory = new SqlSessionFactoryBean();
        factory.setDataSource(dataSource);
        factory.setMapperLocations(new PathMatchingResourcePatternResolver()
            .getResources("classpath:mapper/**/*.xml"));
        return factory;
    }
}

공식 문서 기준 최소 연동 모델은 다음과 같다.

• MyBatis-Spring을 쓰려면 Spring application context에 SqlSessionFactory와 적어도 하나의 mapper interface가 필요하다.^[10]
• SqlSessionFactoryBean은 Spring의 DataSource를 받아 SqlSessionFactory를 만들고, mapper interface는 Spring Bean으로 주입되어 호출된다.^[10:1]
• Spring transaction이 진행 중이면 세션은 해당 transaction 완료 시 함께 commit 또는 rollback되며, 예외는 Spring DataAccessException으로 번역된다.^[10:2] 즉 mapper가 별도의 JDBC transaction을 새로 시작하는 것이 아니라 Spring transaction lifecycle에 참여한다.

실패 모드

• Mapper Interface의 namespace·메서드명이 XML의 namespace/id와 불일치해 BindingException이 발생하는 경우.
• SqlSession을 Spring 트랜잭션과 연동하지 않고 직접 생성해 트랜잭션이 묶이지 않는 경우.
• 동적 SQL을 문자열 연결로 작성해 SQL Injection 위험이나 가독성 저하를 일으키는 경우 — <if>, <choose>, <foreach> 같은 동적 SQL 태그 사용이 권장된다.
• Mapper XML에 resultType을 잘못 지정해 매핑이 실패하는 경우.
• N+1 쿼리 문제를 인지하지 못하고 대량 조회 시마다 개별 쿼리가 나가는 경우 — join 또는 배치 fetch 검토가 필요하다.

JPA와의 선택 기준

복잡한 통계 쿼리, DB 벤더 특화 기능, 다중 JOIN이 많은 도메인에서는 MyBatis가 단순·유리하고, 단순 CRUD·도메인 중심 설계에서는 JPA의 객체-관계 매핑 이점이 크다고 판단한다. 이 선택 기준 자체는 이 페이지가 위 특징 비교를 근거로 종합한 해석이며, source가 직접 제시하는 결론은 아니다.

관련

• Spring Framework Core — MyBatis-Spring이 PSA/DI 위에서 동작.
• Spring Transaction — MyBatis/JPA 관계없이 @Transactional로 동일한 트랜잭션 관리(PSA 적용 사례).

출처

테스트 질문

• MyBatis가 JPA/Hibernate와 다른 점과, 어떤 상황에서 MyBatis가 더 적합한가?
• Mapper Interface의 namespace·메서드명 매핑 규칙은 무엇이며, 이 규칙이 문자열 기반 호출의 어떤 위험을 줄이는가?
• MyBatis-Spring 연동의 핵심 Bean(SqlSessionFactoryBean, SqlSessionTemplate) 역할은?
• "SQL과 프로그래밍 코드의 분리"가 쿼리 튜닝·DBA 역할 분리에 어떻게 기여하는가?