📌 MyBatis Mapper 완전 정복 ② - XML 매퍼 활용법

📅 날짜

2025-04-25

---

📝 1️⃣ XML 매퍼란?

MyBatis에서 XML 매퍼는 SQL을 외부 파일(XML)로 분리하여 작성하는 방식으로,

복잡한 SQL, 동적 쿼리, 유지보수가 필요한 프로젝트에서 필수적으로 사용됩니다.

🔹 어노테이션 방식과 XML 방식 비교

구분	어노테이션 방식	XML 매퍼 방식
간단한 CRUD	적합	가능
복잡한 SQL	제한적	우수
동적 SQL	불가능	지원
유지보수	어려움	유리
설정 파일	최소화	별도 XML 필요
가독성	코드와 혼합	SQL 분리로 명확

💡 Tip:

어노테이션 방식은 단순 작업에,

XML 매퍼는 확장성과 유지보수를 고려한 복잡한 작업에 적합합니다.

---

📝 2️⃣ XML 매퍼 기본 구조

<mapper namespace="com.example.app.domain.mapper.MemoMapper">

    <insert id="insertXml" parameterType="MemoDto">
        INSERT INTO tbl_memo (id, text) VALUES (#{id}, #{text})
    </insert>

    <select id="selectAtXml" parameterType="int" resultType="MemoDto">
        SELECT * FROM tbl_memo WHERE id = #{id}
    </select>

</mapper>

✅ 주요 속성 설명

속성	설명
namespace	Mapper 인터페이스와 연결 (패키지명 포함)
id	인터페이스 메서드명과 매핑
parameterType	전달 파라미터 타입(기본형: int, 참조형: 전체 경로)
resultType	반환 타입 (DTO 클래스 전체 경로 or Map 등)

⚠️ 주의:

parameterType, resultType은 정확한 경로와 타입을 지정해야 오류를 방지할 수 있습니다.

---

📝 3️⃣ XML 기반 CRUD 예제 + 키 생성 처리

<insert id="insertXml" parameterType="MemoDto">
    <selectKey keyProperty="id" order="AFTER" resultType="int">
        SELECT MAX(id) + 1 FROM tbl_memo
    </selectKey>
    INSERT INTO tbl_memo (id, text) VALUES (#{id}, #{text})
</insert>

• selectKey를 활용하여 커스텀 키 생성.
• 또는 DB의 AUTO_INCREMENT를 사용하는 경우 useGeneratedKeys="true" 옵션 사용.

💡 키 생성 전략은 다음 편에서 더 자세히 다룹니다!

---

📝 4️⃣ 동적 SQL & 재사용성

🔹 동적 SQL 예제

<select id="selectDynamic" parameterType="Map" resultType="MemoDto">
    SELECT * FROM tbl_memo
    <where>
        <if test="text != null">
            AND text = #{text}
        </if>
        <if test="writer != null">
            AND writer = #{writer}
        </if>
    </where>
</select>

✅ 태그 자동 처리

• 조건이 없으면 WHERE 절 생략
• 첫 번째 AND/OR 자동 제거

---

🔹 SQL 재사용 예시

<sql id="memoColumns">
    id, text, writer, createAt
</sql>

<select id="selectWithColumns" resultType="MemoDto">
    SELECT <include refid="memoColumns"/> FROM tbl_memo
</select>

---

📝 5️⃣ 설정 방법 & Mapper 연결

• SqlSessionFactory 설정

sessionFactory.setMapperLocations(
    new PathMatchingResourcePatternResolver().getResources("classpath:/mappers/*.xml")
);

• 인터페이스 연결 규칙
  • namespace ➔ Mapper 인터페이스 경로와 일치
  • 메서드명 = XML의 id 속성값과 일치

예시:

public interface MemoMapper {
    int insertXml(MemoDto dto);  // ➔ XML의 id="insertXml"
}

---

📝 6️⃣ 테스트 코드 예시

@Test
void testInsertXml() {
    MemoDto dto = new MemoDto(null, "XML Insert Test", "user@domain.com", LocalDateTime.now(), null);
    int result = memoMapper.insertXml(dto);
    assertEquals(1, result);
}

---

⚠️ 자주 발생하는 오류

1. XML 매퍼 경로 인식 실패
   • setMapperLocations 설정 누락
2. resultType, parameterType 경로 오류
   • 패키지명 포함 전체 경로 확인
3. SQL 끝에 세미콜론(;) 작성
4. 파라미터 매핑 오류
   • 예: "Parameter 'id' not found"
   • 해결: 파라미터 명칭 일치 여부 확인 또는 @Param 사용

---

🔥 정리

• XML 매퍼는 대규모 프로젝트에서 가독성, 유지보수성, 확장성을 보장합니다.
• 동적 SQL과 SQL 재사용 기능을 적극 활용하여 효율적인 개발이 가능합니다.
• 설정과 경로 지정에 주의하여 오류를 사전에 방지해야 합니다.

---

🔗 참고 자료

• MyBatis 공식 문서
• 동적 SQL 가이드

---