전체 메뉴

테마

Chapter 08

MyBatis 기본과 CRUD

MyBatis Mapper 인터페이스와 XML을 연결하고 resultMap, 생성 키, 안전한 파라미터 바인딩으로 사용자 CRUD를 구현합니다.

난이도
입문
예상 학습
100분
Spring Boot 기준
Spring Boot 4.1.1
JDK 기준
JDK 21
최종 검토

전체 24개 Chapter 중 Chapter 08입니다. 예제 코드는 공개 저장소 spring-boot-curriculum의 examples/ch09-mybatis-basics 폴더에서 확인할 수 있습니다.

Learning goals

오늘 배울 내용

  • MyBatis와 JdbcClient의 차이 및 SQL을 분리하는 이유 설명하기
  • Mapper 메서드와 XML namespace·id 연결하기
  • resultMap으로 데이터베이스 컬럼과 Java 필드 매핑하기
  • INSERT 뒤 생성된 id를 객체로 받고 CRUD 결과 해석하기
  • #{}와 ${}의 차이를 이해하고 안전하게 값 바인딩하기
  1. MyBatis 역할 이해
  2. 의존성과 설정
  3. Mapper와 XML 연결
  4. resultMap 매핑
  5. 생성 키와 바인딩
  6. CRUD 응답 검증
이 Chapter의 진행 흐름

SQL을 XML로 옮기고 이름으로 부릅니다

Chapter 07의 JdbcClient는 SQL을 코드 안에 문자열로 적었습니다. 쿼리가 열 개, 스무 개로 늘어나면 SQL이 자바 코드에 흩어지고, 컬럼과 필드를 잇는 코드도 반복됩니다. MyBatis는 SQL을 XML 파일로 분리하고, 인터페이스의 메서드 이름으로 그 SQL을 부르는 방식으로 이 부담을 줄입니다. 이 Chapter는 사용자 CRUD를 MyBatis로 구현하며 Mapper 인터페이스와 XML이 이어지는 규칙, resultMap, 생성된 id 받기, #{}와 ${}의 차이를 다룹니다.

이 Chapter에서 완성할 것

만드는 것 설명
UserMapper 인터페이스 구현 없이 선언만 둔 SQL 호출 창구
UserMapper.xml insert, findById, findAll, update, deleteById SQL
User 엔티티 setter가 있는 클래스 (생성된 id를 받기 위해)
UserService, UserController 201, 404, 409, 204를 결정하는 계층
테스트 15건 Mapper 8건, API 6건, 컨텍스트 1건

예제 모듈과 확인 환경

예제는 공개 저장소의 examples/ch09-mybatis-basics입니다. 모듈 번호가 Chapter 번호와 한 칸 어긋나 있지만 실행 명령마다 모듈 경로를 적었으므로 그대로 따라가면 됩니다. JDK 21과 Spring Boot 4.1.1을 기준으로 하며, 저장소 루트에서 Gradle Wrapper를 사용합니다.

실행 결과는 컨테이너에서 JAR로 직접 실행해 얻은 값이고, 오류 문구는 복사본에서 같은 실수를 일부러 만들어 얻었습니다. MyBatis Spring Boot 스타터 4.1.0 기준이며 Windows 실행은 검증하지 못했습니다.

JdbcClient의 한계와 MyBatis

Chapter 07에서 JdbcClient로 SQL을 실행해 봤습니다. 쿼리가 몇 개일 때는 충분하지만, 늘어나면 불편해지는 지점이 있습니다. 이 절에서는 그 불편함을 구체적으로 짚고, MyBatis가 어떤 방식으로 해결하는지 큰 그림을 봅니다.

쿼리가 늘어나면

JdbcClient 저장소는 SQL이 자바 문자열로 들어 있었습니다.

return jdbc.sql("SELECT id, name, email, age FROM users WHERE id = :id")
        .param("id", id)
        .query(User.class)
        .optional();
불편 설명
SQL이 자바에 섞임 긴 SQL은 문자열 이어 붙이기로 읽기 어렵습니다.
검색·점검이 어려움 DBA나 다른 개발자가 SQL만 보려면 자바 코드를 뒤져야 합니다.
매핑 반복 컬럼과 필드를 잇는 코드가 쿼리마다 반복됩니다.
동적 조건이 어려움 조건이 있을 때만 WHERE를 붙이는 SQL을 문자열 연결로 만들기 번거롭습니다.

MyBatis의 아이디어

MyBatis는 SQL Mapper입니다. SQL을 XML로 분리하고, 인터페이스의 메서드 이름으로 그 SQL을 호출합니다.

  • SQL은 XML에: SQL만 모여 있어 읽고 점검하기 쉽습니다.
  • 호출은 인터페이스로: 구현 클래스 없이 선언만 두고, 실행 시점에 MyBatis가 프록시를 만들어 줍니다.
  • 결과 매핑을 선언으로: 컬럼과 필드의 연결을 XML에 한 번 적습니다.
  • 동적 SQL: <if>, <where> 같은 태그로 조건부 SQL을 만듭니다(Chapter 09).

MyBatis가 하지 않는 일

MyBatis는 SQL을 자동으로 만들어 주지 않습니다. SQL은 개발자가 직접 쓰고, MyBatis는 그것을 실행해 결과를 객체에 담는 일을 도울 뿐입니다. 반복적인 CRUD SQL까지 자동화하려면 MyBatis-Plus를 쓰는데, 이는 Chapter 10에서 다룹니다.

JdbcClient MyBatis
SQL 위치 자바 코드 안 XML (또는 애노테이션)
호출 방식 jdbc.sql("...") 인터페이스 메서드
결과 매핑 record 이름 일치 resultMap 선언 가능
동적 SQL 직접 문자열 조립 XML 태그
SQL 자동 생성 없음 없음 (MyBatis-Plus가 보완)

어느 쪽이 더 좋은가

정답은 없고 상황에 따라 다릅니다. 쿼리가 적고 단순하면 JdbcClient로 충분하고, 쿼리가 많고 복잡하며 SQL을 한곳에서 관리하고 싶다면 MyBatis가 편합니다. 이 과정은 이후 Chapter에서도 MyBatis를 중심으로 진행합니다.

같은 조회를 두 방식으로 비교하기

JdbcClient 방식은 UserRepository 안에 SQL 문자열이 있고, MyBatis 방식은 UserMapper 인터페이스가 이름으로 UserMapper.xml의 SQL과 이어집니다. 두 방식 모두 같은 DataSource 위에서 같은 쿼리를 실행합니다. 달라지는 것은 SQL이 어디에 있고 어떻게 호출하느냐뿐입니다.

언제 어느 쪽을 고를까

상황 더 어울리는 쪽 이유
쿼리 5개 이하의 작은 서비스 JdbcClient 설정 없이 바로 사용
쿼리가 수십 개이고 SQL을 점검·튜닝해야 함 MyBatis SQL이 한곳에 모여 검토하기 쉬움
검색 조건이 자주 바뀌는 목록 조회 MyBatis 동적 SQL 태그 사용
단순 CRUD 반복 MyBatis-Plus SQL 자동 생성(Chapter 10)

자주 하는 오해

오해 사실
MyBatis가 SQL을 대신 만들어 준다 SQL은 직접 쓰고 MyBatis는 실행과 매핑만 돕는다
인터페이스에 구현 클래스를 만들어야 한다 만들지 않는다. 실행 시점에 프록시가 만들어진다
XML을 쓰면 JDBC를 몰라도 된다 연결 풀, 트랜잭션, SQL 문법은 그대로 알아야 한다

확인 문제

  1. MyBatis에서 “SQL 분리”가 주는 이점 두 가지를 말해 보세요.
  2. MyBatis는 SQL을 자동으로 만들어 주지 않는데, 그럼 MyBatis는 무엇을 해 주나요?

답: 1) SQL만 모아 읽고 점검하기 쉽고, 자바 코드에서 문자열 이어 붙이기가 사라집니다. 2) SQL 실행, 파라미터 바인딩, 결과를 객체에 담는 매핑을 해 줍니다.

직접 해 보기

  1. Chapter 07의 UserRepository에서 SQL 문자열이 몇 개인지 세어 보세요. 쿼리가 20개가 되면 어떻게 보일지 상상해 보세요.
  2. 자신이 알고 있는 프로젝트에서 SQL이 어디에 있는지(자바 코드, XML, 별도 파일) 떠올려 보세요.
  3. 위 비교 표에서 자신의 프로젝트에 가장 중요한 항목 하나를 골라 이유를 적어 보세요.

스타터와 설정 세 줄로 MyBatis 붙이기

MyBatis는 스타터 하나로 붙습니다. 하지만 SQL이 들어 있는 XML이 어디에 있는지, 클래스 이름을 어떻게 줄여 쓸지는 설정으로 알려 줘야 합니다. 이 절에서는 의존성과 설정 세 줄의 의미를 봅니다.

의존성

implementation 'org.mybatis.spring.boot:mybatis-spring-boot-starter:4.1.0'

이 스타터가 SqlSessionFactory, Mapper 스캔, Spring 연동을 자동 구성합니다. Chapter 07의 JDBC 스타터와 H2 설정은 그대로 둡니다. 데이터소스는 같고 그 위의 호출 방식만 바뀌기 때문입니다.

설정

mybatis:
  # XML Mapper 파일 위치. 인터페이스와 XML의 namespace/id가 이어져야 한다.
  mapper-locations: classpath:mapper/*.xml
  # com.jqdom.curriculum.ch09.User를 XML에서 User로 줄여 쓴다.
  type-aliases-package: com.jqdom.curriculum.ch09
  configuration:
    # created_at 컬럼을 createdAt 필드에 자동으로 연결한다.
    map-underscore-to-camel-case: true

주요 코드 설명

  • mapper-locations: SQL이 들어 있는 XML 파일을 어디서 읽을지 정합니다. classpath:mapper/*.xml은 src/main/resources/mapper 아래의 모든 XML입니다.
  • type-aliases-package: 이 패키지의 클래스는 이름만으로(User) XML에서 쓸 수 있습니다. 설정하지 않으면 XML마다 전체 이름(com.jqdom.curriculum.ch09.User)을 적어야 합니다.
  • map-underscore-to-camel-case: DB의 created_at을 자바의 createdAt으로 자동 연결합니다. DB는 밑줄 표기, 자바는 카멜 케이스 표기가 관례여서 필요한 설정입니다.
  • application.yml의 datasource, h2 설정은 Chapter 07과 같습니다.

가장 놓치기 쉬운 설정

세 설정 중 mapper-locations가 가장 놓치기 쉽습니다. 이 줄이 없으면 인터페이스는 찾지만 XML을 읽지 않아서, 메서드를 호출할 때 “SQL을 못 찾았다”는 오류가 납니다. 이 줄을 지운 복사본에서 테스트를 돌려 확인한 오류는 아래 “자주 만나는 오류와 해결 방법” 절의 오류 1에 정리했습니다.

앱이 시작하면 @Mapper 인터페이스 스캔과 mapper-locations의 XML 읽기가 함께 일어나고, XML의 namespace와 id가 인터페이스의 메서드와 맞아야 호출할 수 있습니다. 어긋나면 호출하는 순간 BindingException이 납니다.

따라 하기: 설정 하나씩 확인

  1. examples/ch09-mybatis-basics의 application.yml에서 mybatis 아래 두 설정을 확인합니다.
  2. ./gradlew :examples:ch09-mybatis-basics:test로 15건이 통과하는지 확인합니다.
  3. mapper-locations를 classpath:mappers/*.xml(없는 경로)로 바꿔 다시 실행하면 Invalid bound statement (not found)로 테스트가 대거 실패합니다. 확인 후 되돌립니다. 같은 실험 결과는 아래 “자주 만나는 오류와 해결 방법” 절의 오류 1에서 볼 수 있습니다.

설정 세 가지를 비교

설정 없으면 증상이 나타나는 시점
mapper-locations XML을 읽지 않음 메서드 호출 시 Invalid bound statement (not found)
type-aliases-package XML에서 User를 못 찾음 기동 시점 Could not resolve type alias
map-underscore-to-camel-case created_at이 createdAt에 자동으로 안 이어짐 resultMap으로 연결하지 않았다면 해당 필드가 null

같은 “설정 누락”이어도 기동 시점에 터지는 오류와 호출 시점에 터지는 오류가 있다는 점이 중요합니다. 호출 시점 오류는 테스트로 모든 쿼리를 한 번씩 실행해 봐야 발견됩니다.

자주 하는 실수

실수 증상 해결
XML을 src/main/java 아래에 둠 mapper-locations가 가리키는 클래스패스에 없음 src/main/resources/mapper에 둠
@Mapper를 빠뜨림 Mapper가 Bean으로 등록되지 않아 주입 실패 인터페이스에 @Mapper 추가
스타터 버전을 Boot와 맞추지 않음 기동 오류 호환되는 MyBatis 스타터 버전 확인(이 과정은 4.1.0)

확인 문제

  1. mapper-locations 설정을 빼면 언제 어떤 일이 생기나요?
  2. map-underscore-to-camel-case는 무엇을 알려 주는 설정인가요?

답: 1) XML을 읽지 않아, Mapper를 호출하는 시점에 오류가 납니다. 2) 컬럼명의 밑줄 표기를 자바 필드의 낙타 표기와 맞춰 매핑하라는 규칙입니다.

직접 해 보기

  1. type-aliases-package를 지우고 XML의 type="User"를 전체 이름으로 바꿔야 동작하는지 확인하세요. 확인 후 되돌립니다.
  2. XML 파일을 src/main/resources/mappers/(s가 붙은 폴더)로 옮기고 서버를 켜 보세요. 어느 시점에 어떤 오류가 나는지 관찰합니다.
  3. map-underscore-to-camel-case를 false로 바꿔도 테스트가 통과하는지 확인하고, 그 이유를 아래 “resultMap으로 컬럼을 엔티티에 담기” 절의 resultMap과 연결해 설명해 보세요.

Mapper 인터페이스와 XML 잇기

MyBatis에서 가장 중요한 규칙은 이름으로 잇는다입니다. 인터페이스의 전체 이름이 XML의 namespace, 메서드 이름이 SQL 태그의 id입니다. 이 규칙을 알면 MyBatis 오류의 절반은 읽을 수 있습니다.

Mapper 인터페이스

@Mapper
public interface UserMapper {

    /** 생성된 id가 user.id에 채워진다. 반환값은 영향받은 행 수다. */
    int insert(User user);

    User findById(@Param("id") long id);

    List<User> findAll();

    int update(User user);

    int deleteById(@Param("id") long id);

    /** 짧은 SQL은 애노테이션으로도 쓸 수 있다. 긴 SQL은 XML이 읽기 쉽다. */
    @Select("SELECT COUNT(*) FROM users")
    int count();
}

주요 코드 설명

  • @Mapper: 이 인터페이스를 MyBatis가 관리하는 Mapper로 등록합니다. 구현 클래스는 만들지 않습니다. MyBatis가 실행 시점에 프록시를 만들어 Bean으로 등록합니다(Chapter 03의 Bean처럼 주입받아 씁니다).
  • int insert(User user): 객체 하나를 받아 INSERT합니다. 반환값은 영향받은 행 수입니다.
  • @Param("id") long id: 파라미터 이름을 XML의 #{id}에 알려 줍니다. 파라미터가 하나뿐인 단순 타입도 @Param을 붙이는 편이 안전합니다.
  • @Select("SELECT COUNT(*) FROM users"): 짧은 SQL은 애노테이션으로도 쓸 수 있습니다. 긴 SQL은 XML이 읽기 쉬워서 이 예제는 XML을 기본으로 했습니다.

XML 쪽

<mapper namespace="com.jqdom.curriculum.ch09.UserMapper">

    <select id="findById" resultMap="userResultMap">
        SELECT <include refid="userColumns"/>
        FROM users
        WHERE id = #{id}
    </select>

    <select id="findAll" resultMap="userResultMap">
        SELECT <include refid="userColumns"/>
        FROM users
        ORDER BY id
    </select>

    <delete id="deleteById">
        DELETE FROM users WHERE id = #{id}
    </delete>
</mapper>

주요 코드 설명

  • <mapper namespace="...">: 인터페이스의 전체 이름(패키지 포함)과 정확히 같아야 합니다.
  • <select id="findById">: id는 메서드 이름과 같아야 합니다.
  • <select>, <insert>, <update>, <delete>: SQL 종류별 태그입니다.
  • #{id}: 파라미터를 바인딩합니다. @Param("id")로 알려 준 이름과 같습니다.
  • <sql id="userColumns">와 <include refid="userColumns"/>: 자주 쓰는 SQL 조각을 한 번 정의하고 재사용합니다.

연결 규칙 한눈에

인터페이스 쪽 XML 쪽 일치해야 하는 것
com.jqdom...UserMapper namespace 전체 이름
메서드 findById id="findById" 메서드 이름
@Param("id") #{id} 파라미터 이름
반환 타입 User resultMap/resultType 결과를 담을 타입

세 연결 중 어디가 어긋났는지에 따라 오류가 다릅니다. 인터페이스는 컴파일 시점에 검사되지만 XML은 문자열이어서 실행해 봐야 알 수 있습니다. 그래서 Mapper마다 호출하는 테스트를 두는 것이 중요합니다.

어긋난 연결 호출할 때 나오는 오류
namespace 또는 id 불일치(statement를 못 찾음) Invalid bound statement (not found)
@Param 이름과 SQL의 #{ } 이름 불일치 BindingException: Parameter 'wrongName' not found. Available parameters are [id, param1]
결과 컬럼과 필드 매핑 불일치 오류 없이 필드가 null로 남을 수 있음(아래 “resultMap으로 컬럼을 엔티티에 담기” 절에서 다룸)

두 번째 행의 메시지는 저장소와 같은 MyBatis 3.5.19에서 id/param1만 있는 파라미터 맵에 wrongName을 연결해 재현한 결과입니다.

따라 하기

  1. UserMapperTests를 실행해 findById가 kim을 돌려주는지 확인합니다.
./gradlew :examples:ch09-mybatis-basics:test --tests '*UserMapperTests*'
  1. UserMapper.xml의 <select id="findById">를 findByIdd로 한 글자 바꿔 다시 실행합니다. 메서드 이름과 id가 다르면 어떤 메시지가 나오는지 봅니다.
  2. 되돌린 뒤, 인터페이스에 메서드를 새로 추가하되 XML에는 추가하지 않고 호출해 봅니다. 컴파일은 되지만 실행 시점에 같은 오류가 납니다. “인터페이스는 컴파일 시점, XML은 실행 시점에 확인된다”는 차이를 직접 보는 실험입니다.

자주 하는 실수

실수 증상 해결
namespace에 패키지 이름을 빼고 클래스 이름만 적음 Invalid bound statement 전체 이름 사용
파라미터가 둘 이상인데 @Param을 빠뜨림 #{name}을 찾지 못해 바인딩 오류 각 파라미터에 @Param
같은 id의 태그를 XML에 중복 정의 기동 시 중복 오류 id를 유일하게

확인 문제

  1. 인터페이스 메서드를 하나 추가하고 XML을 빼먹으면 컴파일 오류가 날까요, 실행 오류가 날까요?
  2. 파라미터가 하나뿐일 때 @Param을 붙이는 편이 안전한 이유는 무엇인가요?

답: 1) 컴파일은 통과하고 호출하는 순간 Invalid bound statement 실행 오류가 납니다. 2) 이름을 명시하면 파라미터가 늘거나 컴파일 옵션이 달라져도 #{}와의 연결이 바뀌지 않기 때문입니다.

직접 해 보기

  1. UserMapper에 findByEmail(@Param("email") String email)을 추가하고 XML에 SQL을 써서 호출해 보세요.
  2. XML의 id="findById"를 일부러 findByIdd로 바꿔 어떤 테스트가 몇 건 실패하는지 확인하세요. 결과는 아래 “자주 만나는 오류와 해결 방법” 절의 오류 1과 비교합니다.
  3. @Param을 빼고 findById(long id)로 선언해도 동작하는지 확인해 보세요. 이 Chapter에서는 실행해 보지 않았으므로 직접 본 결과를 적어 보세요.

resultMap으로 컬럼을 엔티티에 담기

조회 결과의 컬럼을 객체의 필드에 어떻게 담을지는 resultMap이 정합니다. 또 MyBatis 엔티티는 record가 아니라 setter가 있는 클래스입니다. 이 절에서는 두 가지를 봅니다.

resultMap

<!-- 컬럼과 필드의 연결을 명시한다. 자동 매핑이 되는 컬럼도 적어 두면 읽는 사람이 한눈에 본다. -->
<resultMap id="userResultMap" type="User">
    <id property="id" column="id"/>
    <result property="name" column="name"/>
    <result property="email" column="email"/>
    <result property="age" column="age"/>
    <result property="createdAt" column="created_at"/>
</resultMap>

resultMap은 조회한 컬럼이 객체의 어느 필드로 들어가는지를 적은 지도입니다.

주요 코드 설명

  • <resultMap id="userResultMap" type="User">: 이 정의의 이름과, 결과를 담을 타입입니다. type="User"처럼 줄여 쓸 수 있는 것은 type-aliases-package 설정 덕분입니다.
  • <id property="id" column="id"/>: 기본 키 컬럼입니다. 행을 구분하는 기준이라 <id>로 따로 표시합니다.
  • <result property="createdAt" column="created_at"/>: DB 컬럼 created_at을 객체 필드 createdAt에 연결합니다.
  • 각 SELECT에서 resultMap="userResultMap"으로 가져다 씁니다.

map-underscore-to-camel-case를 켜면 created_at이 createdAt에 자동으로 연결됩니다. 그래도 resultMap에 적어 두면 이름이 다른 경우에도 읽는 사람이 연결을 바로 봅니다. 이 예제에서 map-underscore-to-camel-case를 false로 바꿔도 테스트가 모두 통과했습니다. resultMap이 컬럼을 명시해 두었기 때문입니다. 그래서 이 설정이 필요한 경우(resultType으로 자동 매핑할 때)는 이 Chapter에서 확인하지 못했습니다.

매핑 결과 확인

User kim = mapper.findById(1);

assertEquals("kim@example.com", kim.getEmail());
assertEquals(28, kim.getAge());
assertNotNull(kim.getCreatedAt());

createdAt까지 채워지는지 테스트가 확인합니다. Chapter 07의 조회는 이 컬럼을 가져오지 않았지만, 이번에는 <sql id="userColumns">id, name, email, age, created_at</sql>로 가져옵니다.

엔티티는 setter가 있는 클래스

public class User {

    private Long id;
    private String name;
    private String email;
    private Integer age;
    private LocalDateTime createdAt;

    public User() { }

    public User(String name, String email, Integer age) {
        this.name = name;
        this.email = email;
        this.age = age;
    }
    // getter, setter ...
}

Chapter 07까지는 record를 썼는데 여기서는 일반 클래스입니다. 이유는 INSERT 뒤에 MyBatis가 생성된 id를 객체에 채워 넣어야 하는데, record는 만든 뒤에 값을 바꿀 수 없기 때문입니다.

record setter 클래스
불변 예 아니오
생성된 id 주입 불가 가능
MyBatis 매핑 생성자 인자 이름으로 setter로
이 Chapter에서 요청·응답 DTO에 사용 엔티티에 사용

기본 생성자(public User() { })가 필요한 것도 MyBatis가 빈 객체를 만든 뒤 setter로 값을 채우기 때문입니다. 요청 DTO(UserRequest)와 응답 DTO(UserResponse)는 계속 record입니다. 계층별로 알맞은 형태를 쓰는 것이 Chapter 05에서 DTO를 나눈 이유와 이어집니다.

따라 하기

  1. UserMapperTests에서 createdAt이 채워지는지 확인하는 테스트를 실행합니다.
  2. resultMap에서 createdAt 줄을 지우고, 설정의 map-underscore-to-camel-case가 켜져 있을 때와 꺼져 있을 때 createdAt이 어떻게 달라질지 먼저 예상해 보세요. 켜져 있으면 자동 매핑이 채워 주므로 값이 들어오고, 꺼져 있으면 null입니다.
  3. 이 차이 때문에 이 예제는 설정에 의존하지 않고 resultMap에 연결을 명시합니다.

자주 하는 실수

실수 증상 해결
엔티티를 record로 만듦 생성된 id를 INSERT 후 채울 수 없음 setter가 있는 클래스 사용
기본 생성자가 없음 MyBatis가 객체를 만들지 못함 public User() { } 추가
<id> 대신 <result>로 기본 키를 적음 동작은 하지만 행 구분 기준이 불분명해져 연관 매핑에서 문제 가능 기본 키는 <id>
column과 property를 바꿔 적음 값이 null 컬럼은 DB, 프로퍼티는 자바 필드

확인 문제

  1. 요청·응답 DTO는 record인데 엔티티만 일반 클래스인 이유는 무엇인가요?
  2. resultMap을 쓰지 않아도 되는 경우는 언제인가요?

답: 1) 엔티티는 MyBatis가 INSERT 뒤 생성된 id를 객체에 채워 넣어야 해서 값을 바꿀 수 있어야 하기 때문입니다. 2) 컬럼 이름과 필드 이름이 자동 매핑 규칙으로 모두 이어지는 단순한 경우입니다.

직접 해 보기

  1. resultMap에서 age 줄을 지우면 findById의 age가 어떻게 되는지 관찰하세요. 자동 매핑 설정에 따라 결과가 달라질 수 있으니 직접 본 값을 적어 보세요.
  2. 엔티티에 public String getDisplayName()을 추가해도 매핑에 영향이 없는지 확인하세요.
  3. User를 record로 바꾸고 INSERT 후 getId()가 어떻게 되는지 생각해 보세요(바꾸지 말고 예측만).

생성된 id 받기와 #{}·${}의 차이

INSERT 뒤에는 데이터베이스가 만든 id를 알아야 하는 경우가 많습니다. 응답의 Location 헤더를 만들 때가 그렇습니다. 이 절에서는 생성된 id를 객체로 받는 방법과, MyBatis에서 가장 중요한 보안 규칙인 #{}와 ${}의 차이를 봅니다.

INSERT와 생성된 id

<insert id="insert" useGeneratedKeys="true" keyProperty="id" keyColumn="id">
    INSERT INTO users (name, email, age)
    VALUES (#{name}, #{email}, #{age})
</insert>

생성된 id는 반환값이 아니라 파라미터 객체의 id에 채워집니다. insert(user)를 부를 때 비어 있던 user.id에 H2가 만든 키가 채워지고, 메서드는 영향받은 행 수를 돌려줍니다.

주요 코드 설명

  • useGeneratedKeys="true": INSERT 후 데이터베이스가 만든 키를 읽어 오라는 옵션입니다.
  • keyProperty="id": 읽어 온 키를 객체의 id 필드에 넣습니다.
  • keyColumn="id": 키가 들어 있는 컬럼 이름입니다.
  • #{name}, #{email}, #{age}: 파라미터 객체 User의 필드 값을 바인딩합니다. schema.sql의 IDENTITY 컬럼이 id를 만듭니다. INSERT 문에 id가 없는 이유입니다.
User user = new User("choi", "choi@example.com", 30);

int affected = mapper.insert(user);   // 1
user.getId();                          // 데이터베이스가 만든 값

서비스는 INSERT 직후 created_at이 객체에 없으므로 findById로 다시 읽어 응답을 만듭니다.

public User create(UserRequest request) {
    User user = new User(request.name(), request.email(), request.age());
    mapper.insert(user);
    // INSERT 직후에는 created_at이 객체에 없으므로 다시 읽어 온다.
    return mapper.findById(user.getId());
}

useGeneratedKeys와 keyProperty를 빼면 INSERT는 성공하지만 객체에 id가 채워지지 않습니다. 오류는 INSERT가 아니라 한참 뒤 getId()에서 납니다. 실제 증상은 아래 “자주 만나는 오류와 해결 방법” 절의 오류 4에 있습니다.

#{}와 ${}

MyBatis에는 값을 SQL에 넣는 두 가지 표기가 있습니다.

표기 처리 결과
#{name} PreparedStatement의 ?로 바꾸고 값을 따로 바인딩 값이 SQL 문장으로 해석되지 않음 (안전)
${name} 문자열을 그대로 SQL에 이어 붙임 값이 SQL의 일부가 됨 (SQL 주입 위험)

Chapter 07에서 본 파라미터 바인딩이 MyBatis에서는 #{}입니다.

실험 1: #{}는 공격 문자열을 값으로만 저장한다

이름에 SQL 주입 문자열을 넣은 테스트입니다.

@Test
void hashParameterIsBoundAsValueNotSql() {
    User hostile = new User("x'); DROP TABLE users; --", "hostile@example.com", 20);
    mapper.insert(hostile);

    assertEquals("x'); DROP TABLE users; --", mapper.findById(hostile.getId()).getName());
    assertEquals(4, mapper.count());
}

DROP TABLE users가 들어 있는 이름이 그대로 저장되었고, 테이블은 남아 있으며 행 수는 초기 3건에 1건이 더해진 4건입니다. #{}가 값을 SQL이 아니라 값으로만 다뤘습니다.

실험 2: ${}로 바꾸면

VALUES (#{name}, ...)를 VALUES (${name}, ...)로 바꾸자 이름이 SQL 문장 안에 그대로 들어갔습니다.

JdbcSQLSyntaxErrorException: Syntax error in SQL statement "INSERT INTO users (name, email, age) VALUES ([*]x'); DROP TABLE users; --, ?, ?)"
Column "API" not found; SQL statement: ... VALUES (api, ?, ?)

${}는 값을 ?로 바인딩하지 않고 글자 그대로 붙입니다. 일반 이름 api는 컬럼 이름으로 해석되어 Column "API" not found가 되었고, 주입 문자열은 구문 오류로 끝났습니다. 이 실험에서는 오류로 끝났지만, 공격 문자열을 정교하게 만들면 실제로 실행될 수 있습니다. 이 실험은 그 가능성을 확인한 것이 아니라 ${}가 값을 SQL로 끼워 넣는다는 사실을 확인한 것입니다.

규칙

  • 값을 넣는 자리에는 항상 #{}를 씁니다. 사용자 입력이 들어가는 모든 곳이 해당합니다.
  • ${}는 테이블 이름, 정렬 컬럼 이름처럼 이름 자체를 바꿔야 하는 자리에만 쓰되, 입력을 그대로 넣지 않고 허용 목록 안에서 고릅니다. 이는 Chapter 09의 동적 정렬에서 다룹니다.

따라 하기

curl -i -X POST http://localhost:8080/users -H "Content-Type: application/json" \
  -d '{"name":"choi","email":"choi@example.com","age":30}'

응답이 201이고 Location: /users/4이면 성공입니다. 초기 데이터가 3건이라 첫 생성의 id는 4가 됩니다. 같은 이메일로 다시 보내면 409(DUPLICATE_EMAIL)가 나옵니다.

#{}와 ${} 선택 기준

질문 답 표기
사용자 입력이 들어가는 값인가? 예 #{}
컬럼 이름이나 정렬 방향처럼 이름 자체를 바꾸는가? 예 ${}(허용 목록에서만)
확신이 서지 않는가? - #{}를 기본으로

#{}는 이름 자리에는 쓸 수 없습니다. ORDER BY #{col}은 컬럼 이름이 아니라 문자열 값으로 정렬하려 해서 의도대로 동작하지 않습니다. 이 문제의 해법은 Chapter 09의 안전한 정렬에서 다룹니다.

자주 하는 실수

실수 증상 해결
useGeneratedKeys와 keyProperty를 빠뜨림 INSERT는 성공, 한참 뒤 getId()가 null 세 속성을 함께 지정
반환값을 id로 착각 항상 1이 나옴 id는 객체의 getId()로 읽음
INSERT 직후 객체의 createdAt을 기대 null findById로 다시 조회
${}로 값을 넣음 구문 오류 또는 SQL 주입 위험 값에는 항상 #{}

확인 문제

  1. #{}가 PreparedStatement의 ?로 바뀐다는 말은 무슨 뜻인가요?
  2. 정렬 컬럼 이름을 사용자가 고르게 하려면 어떻게 해야 안전한가요?

답: 1) 값이 SQL 문장과 분리되어 따로 전달되므로 값이 SQL의 일부로 해석되지 않는다는 뜻입니다. 2) 입력을 그대로 ${}에 넣지 않고, 허용한 컬럼 이름 목록 안에서만 고르도록 서버에서 검사합니다.

직접 해 보기

  1. insert 호출 후 user.getId()를 출력해 id가 4인지 확인하세요(초기 데이터 3건 다음).
  2. useGeneratedKeys 속성 세 개를 지운 복사본에서 getId()가 어떻게 되는지 보세요. 확인 후 되돌립니다.
  3. 정렬 컬럼을 받는 쿼리를 ${}로 만들어야 한다면 어떤 안전장치가 필요할지 적어 보세요.

없는 행과 제약 위반을 HTTP 응답으로 바꾸기

MyBatis에서 “없는 데이터”는 어떻게 나타날까요? 조회는 null, 수정·삭제는 행 수 0입니다. 그리고 UNIQUE 제약을 어기면 Spring이 번역한 예외가 올라옵니다. 이 절에서는 이 결과 신호를 읽는 법과, 서비스·컨트롤러가 이를 HTTP 응답으로 바꾸는 방법을 봅니다.

없는 행

assertNull(mapper.findById(999));
assertEquals(1, mapper.deleteById(3));
assertEquals(0, mapper.deleteById(3));

MyBatis는 “없음”을 예외가 아니라 null과 행 수 0으로 알려 주고, 서비스가 이를 Optional과 boolean으로 바꿔 컨트롤러가 404를 정합니다.

동작 대상이 있을 때 대상이 없을 때
findById User 객체 null (예외 없음)
update 1 0
deleteById 1 0

findById는 없는 id에서 예외 대신 null을 돌려줍니다. update와 deleteById는 영향받은 행 수를 돌려주므로, 0이면 그 id가 없다는 뜻입니다.

@Test
void updateReportsAffectedRows() {
    User user = new User("kim2", "kim2@example.com", 29);
    user.setId(1L);

    assertEquals(1, mapper.update(user));
    assertEquals("kim2", mapper.findById(1).getName());

    user.setId(999L);
    assertEquals(0, mapper.update(user));
}

서비스가 신호를 바꿔 준다

서비스는 null과 행 수를 Optional과 boolean으로 바꿔 컨트롤러에 넘깁니다.

public Optional<User> findById(long id) {
    return Optional.ofNullable(mapper.findById(id));
}

public Optional<User> update(long id, UserRequest request) {
    User user = new User(request.name(), request.email(), request.age());
    user.setId(id);
    // 갱신된 행이 0이면 해당 id가 없다는 뜻이다.
    return mapper.update(user) == 0 ? Optional.empty() : Optional.of(mapper.findById(id));
}

public boolean delete(long id) {
    return mapper.deleteById(id) > 0;
}
  • Optional.ofNullable: null이면 빈 Optional, 아니면 값을 감쌉니다. Chapter 04의 Optional → 404 패턴으로 이어집니다.
  • update: 갱신 행이 0이면 빈 값, 아니면 다시 읽어 최신 값을 돌려줍니다.
  • delete: 지운 행이 있으면 true입니다.

컨트롤러가 이 값을 보고 404와 204를 정합니다(아래 “서비스·컨트롤러 연결과 실행 결과” 절).

UNIQUE 위반

email에는 UNIQUE 제약이 있습니다(schema.sql). 이미 있는 이메일로 INSERT하면 데이터베이스가 거절합니다.

@Test
void uniqueViolationIsTranslatedToSpringException() {
    User duplicate = new User("other", "kim@example.com", 20);

    assertThrows(DuplicateKeyException.class, () -> mapper.insert(duplicate));
}

JDBC 드라이버가 던진 DB 고유 예외가 MyBatis-Spring 연동을 거치며 Spring의 DuplicateKeyException으로 번역되어 올라옵니다. 데이터베이스 종류와 관계없이 같은 예외로 받을 수 있다는 점이 이점입니다.

컨트롤러는 이를 409로 바꿉니다.

@ExceptionHandler(DuplicateKeyException.class)
@ResponseStatus(HttpStatus.CONFLICT)
public Map<String, String> duplicate() {
    return Map.of("code", "DUPLICATE_EMAIL", "message", "이미 사용 중인 이메일입니다");
}

Chapter 06에서 배운 @ExceptionHandler를 컨트롤러 안에 둔 형태입니다. 이 Chapter는 전역 핸들러가 아니라 컨트롤러 안에서 처리했습니다. 실제 서비스에서는 공통 핸들러로 모으는 것이 좋습니다.

입력 검증과 DB 제약은 따로 있다

Chapter 06에서 말한 입력 검증은 @Valid가 하고, 이메일 중복은 DB의 UNIQUE 제약이 막습니다. 중복은 저장된 데이터를 알아야 판단할 수 있는 업무 규칙입니다. 이 예제는 먼저 조회하는 대신 INSERT를 시도하고 DB가 거절하면 409로 바꾸는 방식입니다. 동시에 같은 이메일로 두 요청이 오더라도 DB 제약이 마지막 방어선이 되는 장점이 있습니다.

따라 하기

curl -i http://localhost:8080/users/999                                           # 404
curl -i -X DELETE http://localhost:8080/users/3                                   # 204
curl -i -X DELETE http://localhost:8080/users/3                                   # 404 (이미 삭제됨)
curl -i -X POST http://localhost:8080/users -H "Content-Type: application/json" \
  -d '{"name":"x","email":"kim@example.com","age":20}'                            # 409 (UNIQUE 위반)

결과 신호 정리

동작 반환값 의미 처리
조회 객체 또는 null null이면 없음 Optional.ofNullable
수정 행 수 0이면 대상 없음 0이면 404
삭제 행 수 0이면 대상 없음 0이면 404
삽입 행 수 + 객체의 id UNIQUE 위반이면 예외 DuplicateKeyException → 409

자주 하는 실수

실수 증상 해결
조회 결과의 null을 확인하지 않고 사용 NullPointerException 서비스에서 Optional로 감싸기
수정의 행 수를 무시하고 항상 성공 응답 없는 id를 수정해도 200 행 수가 0이면 404
DuplicateKeyException을 처리하지 않음 중복 이메일이 500으로 응답 예외 핸들러로 409 변환
중복 검사를 조회 후 삽입으로만 함 동시 요청에서 둘 다 통과할 수 있음 DB의 UNIQUE 제약을 최종 방어선으로 유지

확인 문제

  1. deleteById가 0을 돌려줄 때 서비스는 무엇을 알 수 있나요?
  2. 중복 이메일을 DB 제약이 막는데 왜 예외를 번역해야 하나요?

답: 1) 삭제할 대상이 없었다는 것입니다. 2) DB 고유 예외가 그대로 올라오면 500이 되므로, 클라이언트가 이해할 수 있는 409와 코드로 바꿔 알려 주기 위해서입니다.

직접 해 보기

  1. 존재하는 이메일로 POST해 409와 DUPLICATE_EMAIL을 확인하세요.
  2. PUT /users/999로 404를 확인하고, 서비스의 update가 왜 빈 값을 돌려주는지 코드로 따라가 보세요.
  3. 사용자 수정에서 자기 이메일을 그대로 두고 PUT하면 409가 나는지 관찰하세요. 이 Chapter의 SQL에서는 같은 행의 이메일을 다시 쓰는 UPDATE이므로 자기 자신과 충돌하지 않는지 직접 확인해 적어 보세요.

서비스·컨트롤러 연결과 실행 결과

Mapper와 XML, 서비스, 컨트롤러를 모두 봤으니 서버를 실행해 전체 흐름을 확인합니다. 이 절은 실행 결과와 테스트 15건의 구성을 정리합니다.

구조 다시 보기

요청은 UserController(201, 404, 409, 204 결정), UserService(null과 행 수를 Optional로 변환), UserMapper 인터페이스를 거쳐 namespace와 id로 이어진 UserMapper.xml의 SQL이 H2의 users 테이블에 닿는 순서로 흐릅니다. Chapter 05에서 나눈 세 계층 구조가 그대로이고, Repository 자리에 Mapper가 들어갔습니다. 저장소가 메모리에서 JdbcClient, MyBatis로 바뀌는 동안 컨트롤러 형태가 거의 변하지 않은 것이 계층 분리의 효과입니다.

실행

OS 실행 이 모듈만 빌드
Linux / macOS ./gradlew :examples:ch09-mybatis-basics:bootRun ./gradlew :examples:ch09-mybatis-basics:build
Windows gradlew.bat :examples:ch09-mybatis-basics:bootRun gradlew.bat :examples:ch09-mybatis-basics:build

JAR로 실행한 결과입니다.

GET /users/1
  -> 200 {"id":1,"name":"kim","email":"kim@example.com","age":28,"createdAt":"2026-10-17T04:38:03.043197"}

POST /users {"name":"choi","email":"choi@example.com","age":30}
  -> 201 Location: /users/4 {"id":4,"name":"choi","email":"choi@example.com","age":30,"createdAt":"2026-10-17T04:38:06.445326"}

POST /users {"name":"dup","email":"kim@example.com","age":30}
  -> 409 {"message":"이미 사용 중인 이메일입니다","code":"DUPLICATE_EMAIL"}

PUT /users/999 {"name":"nobody","email":"n@example.com","age":29}
  -> 404

DELETE /users/4
  -> 204
  • createdAt이 채워져 있습니다(resultMap이 created_at을 연결). 시각은 실행 시점의 값입니다.
  • 새로 만든 사용자의 id는 4이고 Location이 /users/4입니다. 생성된 id가 객체로 돌아온 결과입니다.
  • 중복 이메일은 409, 없는 id의 PUT은 404, 삭제 성공은 204입니다.

테스트 15건

테스트 클래스 건수 고정하는 약속
Ch09ApplicationTests 1 컨텍스트가 뜬다
UserMapperTests 8 초기 데이터, resultMap, 생성 id, null, 행 수, 제약 번역, #{} 바인딩
UserApiTests 6 201+Location, 조회·수정·삭제 흐름, 404, 409, 400, 목록

트랜잭션 롤백으로 테스트 격리

/** 각 테스트는 트랜잭션 안에서 실행되고 끝나면 롤백되어 다른 테스트에 영향을 주지 않는다. */
@SpringBootTest
@Transactional
class UserMapperTests {
    // ...
}

테스트 클래스에 @Transactional을 붙이면 각 테스트가 트랜잭션 안에서 실행되고 끝나면 롤백됩니다. 그래서 한 테스트가 만든 사용자나 지운 사용자가 다른 테스트에 영향을 주지 않고, 모든 테스트가 같은 초기 데이터 3건에서 시작합니다. Chapter 05처럼 “각자 만든 id만 쓴다”는 규율에 의존하지 않아도 됩니다. 트랜잭션은 Chapter 09에서 자세히 다룹니다.

./gradlew :examples:ch09-mybatis-basics:build

15건이 모두 통과했습니다.

따라 하기: 전체 흐름

curl http://localhost:8080/users/1
curl -i -X POST http://localhost:8080/users -H "Content-Type: application/json" \
  -d '{"name":"choi","email":"choi@example.com","age":30}'
curl -i -X PUT http://localhost:8080/users/4 -H "Content-Type: application/json" \
  -d '{"name":"choi2","email":"choi@example.com","age":31}'
curl -i -X DELETE http://localhost:8080/users/4

201, 200, 204 순서로 나오면 성공입니다. 응답의 createdAt이 채워져 있는 것은 resultMap 덕분입니다.

자주 하는 실수

실수 증상 해결
서버 재시작 후 생성한 사용자가 사라졌다고 착각 인메모리 H2의 특성 재시작하면 초기 데이터 3건으로 돌아감
테스트에 @Transactional이 없음 한 테스트의 데이터가 다음 테스트에 영향 클래스에 @Transactional
컨트롤러에서 직접 Mapper 호출 계층이 무너짐 Controller → Service → Mapper

확인 문제

  1. @Transactional 테스트가 끝나고 롤백되는 이유는 무엇인가요?
  2. Chapter 05의 컨트롤러와 이 Chapter의 컨트롤러가 거의 같은 이유는 무엇인가요?

답: 1) 테스트가 만든 데이터를 남기지 않아 다른 테스트와 격리하기 위해서입니다. 2) 계층을 나누어 저장소 구현(메모리, JdbcClient, MyBatis)이 바뀌어도 위쪽 코드가 바뀌지 않도록 했기 때문입니다.

직접 해 보기

  1. UserMapperTests에서 @Transactional을 지우고 전체 테스트를 돌려 보세요. 일부 테스트가 다른 테스트의 데이터 때문에 실패하는지 관찰합니다. 확인 후 되돌립니다.
  2. 서버를 켜고 위 요청들을 직접 보내 createdAt이 채워지는지 확인하세요.
  3. 수정(PUT) 후 createdAt이 바뀌지 않는 이유를 SQL(UPDATE 문의 SET 절)에서 찾아 설명해 보세요.

자주 만나는 오류와 해결 방법

MyBatis 오류는 대부분 “XML과 인터페이스가 이어지지 않았다”에서 나옵니다. 아래는 이 예제에서 일부러 같은 실수를 만들어 얻은 메시지입니다(MyBatis Spring Boot 스타터 4.1.0 기준). 망가뜨린 코드는 되돌렸고 저장소에는 올리지 않았습니다.

오류 1: Invalid bound statement (not found)

가장 흔한 오류입니다. 세 가지 원인으로 모두 같은 메시지를 얻었습니다.

org.apache.ibatis.binding.BindingException: Invalid bound statement (not found): com.jqdom.curriculum.ch09.UserMapper.findById
만든 실수 실패한 테스트
XML의 id="findById"를 findByIdd로 오타 15건 중 9건
mybatis.mapper-locations를 classpath:mappers/*.xml로 잘못 지정 15건 중 13건
XML namespace의 마지막 글자를 틀림(UserMappr) 15건 중 13건

메시지의 끝 UserMapper.findById는 “인터페이스의 이 메서드에 연결된 SQL을 못 찾았다”는 뜻입니다. 세 원인이 같은 메시지를 내므로 메시지만으로는 어느 것인지 알 수 없고, 아래 “따라 하기: 세 가지 원인 구분”의 표 순서대로 namespace, id, mapper-locations를 하나씩 확인해야 합니다(“Mapper 인터페이스와 XML 잇기” 절의 연결 규칙표와 같은 내용입니다).

오류 2: Could not resolve type alias ‘User’

type-aliases-package를 존재하지 않는 패키지(ch99)로 바꾸면 애플리케이션이 시작하지 못합니다. 15건이 모두 실패했습니다.

Caused by: org.apache.ibatis.type.TypeException: Could not resolve type alias 'User'.  Cause: java.lang.ClassNotFoundException: Cannot find class: User

XML에서 type="User"처럼 줄여 쓴 이름을 설정한 패키지에서 찾지 못한 것입니다. 호출 시점이 아니라 기동 시점에 터지는 점이 오류 1과 다릅니다.

오류 3: #{}를 ${}로 바꾸면

“생성된 id 받기와 #{}·${}의 차이” 절의 실험 2입니다.

JdbcSQLSyntaxErrorException: Syntax error in SQL statement "INSERT INTO users (name, email, age) VALUES ([*]x'); DROP TABLE users; --, ?, ?)"
Column "API" not found; SQL statement: ... VALUES (api, ?, ?)

입력값이 SQL 문법 오류를 내거나 컬럼 이름으로 해석된다면 ${}를 쓴 곳을 의심합니다.

오류 4: 생성된 id가 null이다

useGeneratedKeys="true" keyProperty="id" keyColumn="id"를 지우면 insert는 성공하지만 객체에 id가 채워지지 않습니다.

AssertionFailedError: expected: not <null>
NullPointerException: Cannot invoke "java.lang.Long.longValue()" because the return value of "User.getId()" is null

오류는 insert가 아니라 한참 뒤 getId()에서 납니다. 원인과 증상이 떨어져 있는 유형입니다.

오류가 터지는 시점으로 구분하기

오류가 언제 났는지로 볼 곳이 갈립니다. 기동 시점이면 type alias, XML 문법, namespace 중복처럼 설정과 XML 문법을 봅니다. 호출 시점의 Invalid bound statement는 namespace, id, mapper-locations를 봅니다. 조금 뒤 다른 곳에서 id가 null로 드러나면 useGeneratedKeys, keyProperty를 봅니다.

기동 시점 오류는 앱이 뜨지 않아 바로 알지만, 호출 시점 오류는 해당 쿼리를 실행하는 테스트가 없으면 발견되지 않습니다. 모든 Mapper 메서드를 한 번씩 호출하는 테스트가 중요한 이유입니다.

따라 하기: 세 가지 원인 구분

세 실수 모두 Invalid bound statement (not found)를 내므로 아래 순서로 하나씩 확인합니다.

순서 확인 어긋났을 때 고치는 곳
1 namespace가 인터페이스의 전체 이름과 같은가 XML 첫 줄
2 id가 메서드 이름과 같은가 해당 태그
3 mapper-locations가 XML 위치를 가리키는가 application.yml

증상별 점검표

증상 가장 먼저 볼 것
Invalid bound statement (not found) namespace, id, mapper-locations 세 가지
Could not resolve type alias type-aliases-package, 클래스 이름
입력값이 SQL 문법 오류를 냄 ${}를 쓴 곳
insert 뒤 getId()가 null useGeneratedKeys, keyProperty

직접 해 보기

  1. 복사한 저장소에서 오류 1의 세 가지를 각각 만들어 실패 건수를 직접 세어 보세요. 확인 후 되돌립니다.
  2. 오류 2에서 서버가 아예 뜨지 않는 것과 오류 1에서 호출할 때만 실패하는 것의 차이를 한 문장으로 설명해 보세요.
  3. 새 Mapper 메서드를 추가할 때마다 호출하는 테스트를 하나씩 쓰는 습관이 왜 필요한지 적어 보세요.

용어와 참고 자료

이 Chapter에 나온 용어와 참고 사이트를 모았습니다. Chapter 05와 Chapter 07에서 설명한 용어는 다시 쓰지 않습니다.

참고한 자료

MyBatis 구성

용어 설명
MyBatis SQL을 XML로 분리하고 인터페이스로 호출하는 SQL Mapper 프레임워크입니다.
SQL Mapper SQL을 직접 쓰되 실행과 결과 매핑을 도와주는 도구입니다.
mybatis-spring-boot-starter MyBatis를 Spring Boot에 붙이는 스타터입니다. 이 과정은 4.1.0을 씁니다.
mapper-locations SQL이 든 XML 파일의 위치를 알려 주는 설정입니다.
type-aliases-package 이 패키지의 클래스를 이름만으로 XML에서 쓰게 하는 설정입니다.
map-underscore-to-camel-case created_at을 createdAt으로 자동 연결하는 설정입니다.
@Mapper 인터페이스를 MyBatis Mapper로 등록하는 애노테이션입니다. 구현은 프록시입니다.
@Param 파라미터 이름을 XML의 #{}에 알려 줍니다.
@Select 짧은 SQL을 인터페이스에 직접 적는 애노테이션입니다.
namespace XML Mapper가 짝을 이루는 인터페이스의 전체 이름입니다.
id SQL 태그의 이름으로, 인터페이스 메서드 이름과 같아야 합니다.
<sql> / <include> SQL 조각을 한 번 정의하고 재사용합니다.
BindingException 인터페이스 메서드에 연결된 SQL을 찾지 못했을 때의 예외입니다.

매핑과 실행

용어 설명
resultMap 조회 결과의 컬럼을 객체 필드에 연결하는 정의입니다.
<id> / <result> resultMap 안에서 기본 키 / 일반 컬럼을 필드에 연결하는 태그입니다.
엔티티 테이블 한 행에 대응하는 객체입니다. MyBatis에서는 setter가 있는 클래스를 씁니다.
useGeneratedKeys INSERT 후 데이터베이스가 만든 키를 객체에 채워 넣는 옵션입니다.
keyProperty / keyColumn 생성된 키를 담을 필드 / 키가 든 컬럼 이름입니다.
#{} 값을 ?로 바인딩합니다. SQL 주입을 막습니다.
${} 값을 문자열 그대로 SQL에 끼워 넣습니다. 값에는 쓰지 않습니다.
영향받은 행 수 INSERT, UPDATE, DELETE가 돌려주는 바뀐 행의 개수입니다. 0이면 대상이 없다는 신호입니다.
DuplicateKeyException UNIQUE 제약 위반을 번역한 Spring의 예외입니다.
예외 번역 DB 고유 예외를 Spring의 공통 예외로 바꿔 주는 동작입니다.
@Transactional (테스트) 테스트를 트랜잭션 안에서 실행하고 끝나면 롤백해 격리합니다.

예제 코드 파일

본문에서 다룬 파일은 예제 저장소의 다음 위치에 있습니다.

대상 링크
설정 application.yml
빌드 파일 build.gradle
Mapper 인터페이스 UserMapper.java
Mapper XML UserMapper.xml
엔티티 User.java
Mapper 테스트 UserMapperTests.java
서비스 UserService.java
컨트롤러 UserController.java
API 테스트 UserApiTests.java

직접 해보기

  1. ./gradlew :examples:ch09-mybatis-basics:build로 테스트 15건이 통과하는지 확인한 뒤, 서버를 켜고 생성, 조회, 수정, 삭제 요청을 차례로 보내 201, 200, 200, 204가 나오는지 확인하세요.
  2. UserMapper에 findByEmail(@Param("email") String email)을 추가하고, XML의 namespace, id, #{email}을 직접 맞춰 쓴 뒤 호출하는 테스트까지 작성해 보세요.
  3. resultMap에서 createdAt 줄을 지우고 map-underscore-to-camel-case를 켰을 때와 껐을 때 응답의 createdAt이 어떻게 달라지는지 비교하세요. 확인 후 되돌립니다.
  4. “자주 만나는 오류와 해결 방법” 절의 오류 중 하나를 재현하고, “오류가 터지는 시점으로 구분하기”의 기준으로 기동 시점, 호출 시점, 조금 뒤 다른 곳 중 어디에 해당하는지 먼저 판단한 뒤 원래 코드로 되돌리세요.

이번 장의 정리

  • MyBatis는 SQL을 XML로 분리하고 인터페이스 메서드로 호출하는 SQL Mapper입니다. SQL을 대신 만들어 주지는 않습니다.
  • 스타터 하나로 붙고, mapper-locations, type-aliases-package, map-underscore-to-camel-case로 XML 위치와 별칭, 컬럼명 규칙을 알려 줍니다.
  • 인터페이스 전체 이름이 namespace, 메서드 이름이 id, @Param 이름이 #{}와 같아야 하며, XML의 어긋남은 실행 시점에 드러나므로 Mapper마다 테스트가 필요합니다.
  • resultMap이 컬럼과 필드를 잇고, 생성된 id를 받으려면 엔티티는 setter와 기본 생성자가 있는 클래스여야 합니다.
  • useGeneratedKeys로 생성된 id를 객체에 받고, 값에는 항상 #{}를 씁니다. ${}는 글자 그대로 이어 붙여 SQL 주입 위험이 있습니다.
  • 없는 행은 null과 행 수 0으로, UNIQUE 위반은 DuplicateKeyException으로 올라오며, 서비스와 컨트롤러가 이를 404, 204, 409로 바꿉니다.

다음 Chapter 09 동적 SQL과 트랜잭션에서는 조건에 따라 달라지는 SQL, JOIN 결과 매핑, 페이징, 트랜잭션 경계를 다룹니다.

FAQ

자주 묻는 질문

MyBatis가 SQL을 자동으로 만들어 주나요?

기본 MyBatis에서는 개발자가 SQL을 직접 작성합니다. 대신 SQL을 XML로 분리하고 Mapper 인터페이스 호출과 결과 매핑을 연결해 줍니다.

Mapper 인터페이스에 구현 클래스가 없는 이유는 무엇인가요?

시작할 때 MyBatis가 Mapper 프록시 객체를 만들고 메서드 호출을 namespace와 id가 일치하는 XML 문장으로 전달합니다.

#{}와 ${}는 어떻게 다른가요?

#{}는 값을 JDBC 파라미터로 바인딩해 SQL 문법과 분리합니다. ${}는 문자열을 SQL에 그대로 삽입하므로 사용자 입력 값에 쓰면 SQL 주입 위험이 있습니다.

생성된 id를 어떻게 받나요?

insert 문에 useGeneratedKeys와 keyProperty를 설정하고 setter가 있는 객체를 전달하면 실행 뒤 해당 필드에 생성 키가 들어갑니다.

작성·편집 ToolPado

콘텐츠 유형 Spring Boot 학습 가이드

기술 기준 Spring Boot 4.1.1 · JDK 21

마지막 검토