🦅
MyBatis & SQL 매퍼 치트시트

XML 매퍼 문법, 동적 SQL 태그, ResultMap 연관관계 매핑 및 실무 최적화 레퍼런스
#mybatis#sql#java#spring#mapper#database#xml#crud#orm최종 업데이트: 2026-09-26
MyBatis & SQL 매퍼 치트시트 핵심 명령어 및 실전 가이드

XML 매퍼 문법, 동적 SQL 태그, ResultMap 연관관계 매핑 및 실무 최적화 레퍼런스
## 1. XML 매퍼 기본 선언 & 구조 (Mapper DTD)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" 
  "http://mybatis.org/dtd/mybatis-3-mapper.dtd">

<!-- namespace: 연결할 매퍼 인터페이스의 풀 패키지 경로 -->
<mapper namespace="com.example.project.mapper.UserMapper">
  <!-- 태그의 id는 Java 매퍼 인터페이스의 메서드 이름과 1:1 일치해야 함 -->
  <select id="findById" parameterType="long" resultType="com.example.project.dto.UserDto">
    SELECT id, username, email, created_at
    FROM users
    WHERE id = #{id}
  </select>
</mapper>
```

## 2. 기본 CRUD 구문 (SELECT, INSERT, UPDATE, DELETE)
```xml
<!-- 1. SELECT: 단일/다중 행 조회 -->
<select id="findByEmail" parameterType="string" resultType="UserDto">
  SELECT id, username, email, status FROM users WHERE email = #{email}
</select>

<!-- 2. INSERT: 자동 증가(Auto-Increment) PK 키 채번 (useGeneratedKeys) -->
<insert id="insertUser" parameterType="UserDto" useGeneratedKeys="true" keyProperty="id">
  INSERT INTO users (username, email, password, status, created_at)
  VALUES (#{username}, #{email}, #{password}, 'ACTIVE', NOW())
</insert>

<!-- Oracle 시퀀스 기반 PK 사전/사후 채번 (selectKey) -->
<insert id="insertUserOracle" parameterType="UserDto">
  <selectKey keyProperty="id" resultType="long" order="BEFORE">
    SELECT seq_users.NEXTVAL FROM dual
  </selectKey>
  INSERT INTO users (id, username, email) VALUES (#{id}, #{username}, #{email})
</insert>

<!-- 3. UPDATE: 수정 -->
<update id="updateLoginTime" parameterType="long">
  UPDATE users SET last_login_at = NOW() WHERE id = #{id}
</update>

<!-- 4. DELETE: 삭제 -->
<delete id="deleteById" parameterType="long">
  DELETE FROM users WHERE id = #{id}
</delete>
```

## 3. 파라미터 바인딩 (`#` vs `$`)
```xml
<!-- #{param}: PreparedStatement 파라미터 치환 (?) -->
<!-- 값에 자동으로 따옴표가 붙으며 SQL Injection을 완벽 차단 (기본적으로 반드시 사용) -->
SELECT * FROM users WHERE username = #{username}

<!-- ${param}: 문자열 직접 치환 (Statement 방식) -->
<!-- SQL Injection 취약점이 발생할 수 있으므로 테이블명/컬럼명 동적 변경 시에만 제한적 사용 -->
SELECT * FROM ${tableName} ORDER BY ${sortColumn} ${sortDirection}

<!-- 다중 파라미터 매핑 (@Param 어노테이션 활용) -->
<!-- Java: List<User> search(@Param("name") String name, @Param("role") String role); -->
SELECT * FROM users 
WHERE username = #{name} AND role = #{role}

<!-- NULL 파라미터 허용 (해당 컬럼의 JDBC 타입 명시 권장) -->
INSERT INTO users (username, phone) 
VALUES (#{username}, #{phone, jdbcType=VARCHAR})
```

## 4. 동적 SQL: 조건 분기 (`if`, `choose`)
```xml
<!-- 1. <if> 태그: 단일 조건 분기 -->
<select id="searchUsers" parameterType="UserSearchDto" resultType="UserDto">
  SELECT * FROM users
  WHERE 1 = 1
  <if test="keyword != null and keyword != ''">
    AND (username LIKE CONCAT('%', #{keyword}, '%') OR email LIKE CONCAT('%', #{keyword}, '%'))
  </if>
  <!-- 문자열 비교 주의: 단일 문자 'Y' 비교 시 char 형변환 에러 방지 -->
  <if test='status == "ACTIVE"'>
    AND status = 'ACTIVE'
  </if>
</select>

<!-- 2. <choose>, <when>, <otherwise>: 다중 조건 분기 (if-else if-else) -->
<select id="findUsersOrdered" resultType="UserDto">
  SELECT * FROM users
  ORDER BY 
  <choose>
    <when test="sortBy == 'name'">username ASC</when>
    <when test="sortBy == 'date'">created_at DESC</when>
    <when test="sortBy == 'views'">view_count DESC</when>
    <otherwise>id DESC</otherwise>
  </choose>
</select>
```

## 5. 동적 SQL: 구문 정리 (`where`, `set`, `trim`)
```xml
<!-- 1. <where> 태그: 1=1 제거, 맨 앞의 불필요한 AND/OR 자동 제거, 하위 조건 없으면 WHERE 자체 생략 -->
<select id="findActiveUsers" resultType="UserDto">
  SELECT * FROM users
  <where>
    <if test="status != null">AND status = #{status}</if>
    <if test="minAge != null">AND age >= #{minAge}</if>
  </where>
</select>

<!-- 2. <set> 태그: UPDATE 시 마지막 콤마(,) 자동 제거 및 SET 키워드 삽입 -->
<update id="updateSelective" parameterType="UserDto">
  UPDATE users
  <set>
    <if test="username != null">username = #{username},</if>
    <if test="email != null">email = #{email},</if>
    <if test="status != null">status = #{status},</if>
  </set>
  WHERE id = #{id}
</update>

<!-- 3. <trim> 태그: 커스텀 접두/접미사 제어 -->
<trim prefix="WHERE" prefixOverrides="AND |OR ">
  <if test="email != null">AND email = #{email}</if>
</trim>
```

## 6. 동적 SQL: 컬렉션 반복 (`foreach`)
```xml
<!-- 1. IN 절 다중 조회 (List/Array 파라미터) -->
<!-- Java: List<User> findByIds(@Param("idList") List<Long> idList); -->
SELECT * FROM users
WHERE id IN
<foreach item="id" collection="idList" open="(" separator="," close=")">
  #{id}
</foreach>
<!-- 출력 예시: WHERE id IN (1, 2, 5, 8) -->

<!-- 2. 다중 행 일괄 삽입 (Bulk INSERT / MySQL) -->
INSERT INTO users (username, email, role) VALUES
<foreach item="item" collection="list" separator=",">
  (#{item.username}, #{item.email}, #{item.role})
</foreach>

<!-- 3. Map 키-값 순회 -->
<foreach collection="filterMap" index="key" item="val" separator="AND">
  ${key} = #{val}
</foreach>
```

## 7. 결과 매핑 (ResultMap & CamelCase)
```xml
<!-- 1. DB 컬럼과 Java 객체 필드명이 다를 때의 매핑 정의 -->
<resultMap id="UserDetailResultMap" type="UserDetailDto">
  <id property="userId" column="user_id" />
  <result property="userName" column="user_nm" />
  <result property="userEmail" column="email_addr" />
  <result property="registeredAt" column="reg_dt" />
</resultMap>

<select id="getDetail" resultMap="UserDetailResultMap">
  SELECT user_id, user_nm, email_addr, reg_dt FROM users WHERE user_id = #{id}
</select>

<!-- 팁: Spring Boot 설정에서 map-underscore-to-camel-case: true 시 -->
<!-- user_name -> userName 자동 변환되므로 단순 필드는 ResultMap 불필요 -->
```

## 8. 연관 관계 매핑 (1:1 association, 1:N collection)
```xml
<!-- 1:1 관계 (주문 -> 주문자 정보: association) & 1:N 관계 (주문 -> 주문 상품 목록: collection) -->
<resultMap id="OrderWithItemsMap" type="OrderDto">
  <id property="orderId" column="order_id" />
  <result property="orderDate" column="order_date" />

  <!-- 1:1 연관 매핑 -->
  <association property="buyer" javaType="UserDto">
    <id property="id" column="buyer_id" />
    <result property="username" column="buyer_name" />
  </association>

  <!-- 1:N 컬렉션 매핑 -->
  <collection property="items" ofType="OrderItemDto">
    <id property="orderItemId" column="order_item_id" />
    <result property="productName" column="product_name" />
    <result property="quantity" column="quantity" />
    <result property="price" column="price" />
  </collection>
</resultMap>

<select id="findOrderFullDetail" resultMap="OrderWithItemsMap">
  SELECT o.order_id, o.order_date,
         u.id as buyer_id, u.username as buyer_name,
         i.order_item_id, i.product_name, i.quantity, i.price
  FROM orders o
  JOIN users u ON o.user_id = u.id
  JOIN order_items i ON o.order_id = i.order_id
  WHERE o.order_id = #{orderId}
</select>
```

## 9. SQL 조각 모듈화 & 재사용 (`sql`, `include`, `bind`)
```xml
<!-- 1. <sql> 공통 컬럼 조각 정의 -->
<sql id="commonUserColumns">
  u.id, u.username, u.email, u.status, u.created_at
</sql>

<!-- 2. <include> 조각 삽입 -->
<select id="findAll" resultType="UserDto">
  SELECT <include refid="commonUserColumns" />
  FROM users u
  WHERE u.status = 'ACTIVE'
</select>

<!-- 3. <bind> 변수 생성 (LIKE 검색어 전처리) -->
<select id="findByKeyword" resultType="UserDto">
  <bind name="pattern" value="'%' + keyword + '%'" />
  SELECT * FROM users
  WHERE username LIKE #{pattern} OR email LIKE #{pattern}
</select>
```

## 10. 특수 문자 처리 (CDATA) & 페이징
```xml
<!-- 부등호(<, >, <=, >=) 및 특수문자 XML 파싱 방지 (CDATA 필수 사용) -->
<select id="findBetweenDates" resultType="LogDto">
  SELECT * FROM access_logs
  <![CDATA[
  WHERE log_time >= #{startDate}
    AND log_time <  #{endDate}
    AND response_status >= 400
  ]]>
</select>

<!-- 주요 DB 페이징 쿼리 패턴 -->
<!-- MySQL / MariaDB -->
SELECT * FROM users ORDER BY id DESC LIMIT #{pageSize} OFFSET #{offset};

<!-- Oracle 12c+ -->
SELECT * FROM users ORDER BY id DESC 
OFFSET #{offset} ROWS FETCH NEXT #{pageSize} ROWS ONLY;
```

## 11. Spring Boot 설정 & 실무 권장 옵션
```yaml
# application.yml 실무 추천 설정
mybatis:
  mapper-locations: classpath:mapper/**/*.xml
  type-aliases-package: com.example.project.dto, com.example.project.entity
  configuration:
    # 카멜 케이스 자동 매핑 (user_id -> userId)
    map-underscore-to-camel-case: true
    # null 파라미터 삽입 시 에러 방지 (기본 NULL 허용)
    jdbc-type-for-null: 'NULL'
    # SQL 쿼리 실행 타임아웃 (초 단위)
    default-statement-timeout: 25
    # 지연 로딩 활성화
    lazy-loading-enabled: true
    # 쿼리 캐시 사용 여부
    cache-enabled: false

# MyBatis 실행 쿼리 파라미터 바인딩 로그 출력
logging:
  level:
    com.example.project.mapper: DEBUG
```
💬
MyBatis & SQL 매퍼 치트시트

의견 및 질문

댓글 수정

댓글 삭제
