📌 MyBatis Mapper 완전 정복 ④ - 자주 발생하는 오류 & 실전 팁

📅 날짜

2025-04-25

---

📝 1️⃣ MyBatis에서 오류가 자주 발생하는 이유

MyBatis는 SQL을 직접 다루는 프레임워크이기 때문에,

설정 실수, 경로 오류, SQL 구문 오류 등 사소한 실수가 쉽게 발생할 수 있습니다.

하지만, 이러한 오류는 패턴화된 실수가 많아 미리 알고 대비하면 충분히 예방할 수 있습니다.

---

📝 2️⃣ Mapper 설정 관련 오류

⚠️ 1. namespace 불일치

• 원인: XML 매퍼의 namespace와 Mapper 인터페이스 경로가 다를 때 발생.
  
• 해결: 항상 패키지 경로까지 정확히 일치시켜야 합니다.
  

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

---

⚠️ 2. 매퍼 스캔 누락

• 원인: @MapperScan 또는 <mybatis-spring:scan> 설정 누락.
  
• 해결: Spring 설정 파일에서 매퍼 경로를 반드시 등록.
  

<mybatis-spring:scan base-package="com.example.app.domain.mapper"/>

---

⚠️ 3. XML 경로 설정 오류

• 원인: setMapperLocations 경로 지정 실수.
  
• 해결: 리소스 경로를 정확히 설정.
  

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

---

📝 3️⃣ SQL 작성 시 자주 발생하는 오류

⚠️ 1. 세미콜론(;) 사용

• MyBatis SQL 구문 끝에 ;을 작성하면 오류 발생.
• 해결: SQL 끝에는 세미콜론을 붙이지 않습니다.

---

⚠️ 2. 컬럼명 오타

• 원인: SQL 내 컬럼명을 잘못 입력.
• 해결: DB 스키마 기준으로 정확한 컬럼명 사용.

---

⚠️ 3. 파라미터 매핑 오류

• 오류 메시지: "Parameter 'id' not found. Available parameters are..."
  
• 원인:
  • DTO 필드명과 SQL 매핑 불일치.
  • 다중 파라미터 사용 시 @Param 누락.
• 해결:
  • DTO 필드명과 SQL의 #{} 이름을 일치.
  • 다중 파라미터 시 @Param 활용.

int deleteXml(@Param("id") int id);

---

📝 4️⃣ resultType & parameterType 오류

⚠️ 1. 경로 오류

• 원인: 패키지 전체 경로 누락.
• 해결: 항상 풀 패키지 경로를 작성.

<select id="selectAtXml" resultType="com.example.app.domain.dto.MemoDto">

---

⚠️ 2. 타입 미스매칭

• 기본형은 소문자 사용 (int, string), 객체형은 전체 경로 사용.

---

📝 5️⃣ 키 생성 관련 오류

⚠️ 1. useGeneratedKeys 설정 누락

• 오류 메시지: "Generated keys not requested"
  
• 해결: INSERT 구문에 useGeneratedKeys="true" 추가.
  

---

⚠️ 2. selectKey 동시성 문제

• 원인: SELECT MAX(id) + 1 방식은 동시성 이슈가 발생할 수 있음.
• 해결: 가능하다면 DB의 AUTO_INCREMENT 또는 시퀀스 사용 권장.

---

📝 6️⃣ 동적 SQL 오류

⚠️ 1. , 태그 오용

• <where> 태그 내부에 조건이 없으면 SQL 문법 오류 발생.
• 해결: 조건이 없을 때를 대비하여 기본 조건 설정을 고려.

---

⚠️ 2. NullPointerException

• 원인: 파라미터가 null일 때 구문에서 발생.
• 해결: 안전하게 null 체크 로직 작성.

<if test="text != null and text != ''">
    AND text = #{text}
</if>

---

📝 7️⃣ 실전 팁 모음

✅ 1. 테스트 코드로 빠르게 검증

• CRUD 기능마다 JUnit 테스트를 작성해 오류를 사전에 확인.

---

✅ 2. SQL 로그 설정

• MyBatis 실행 쿼리를 확인하기 위해 Log 설정을 활용.

<logger name="org.mybatis" level="DEBUG"/>

---

✅ 3. Mapper & XML 관리 전략

• 네이밍 컨벤션 통일:
  • 인터페이스: MemoMapper.java
  • XML: MemoMapper.xml
• 패키지 구조를 일관성 있게 유지.

---

🔥 정리 - MyBatis 오류 방지 체크리스트 ✅

• namespace, 경로 일치 확인
• 세미콜론(;) 사용 여부 점검
• parameterType, resultType 경로 검토
• 키 생성 전략 설정 확인
• 동적 SQL null 체크
• 테스트 코드로 반복 검증
• SQL 로그 활성화

---

🔗 참고 자료

• MyBatis 공식 문서
• MyBatis FAQ

---