문제 상황
Inquiry(문의) 도메인 관련 기능을 개발 중,
InquiryMapper를 DI로 주입하려고 하자 다음과 같은 런타임 에러가 발생했다.
원인 분석
- InquiryMapper.java에 분명히 @Mapper 애노테이션을 붙였고,
- Mapper XML의 namespace도 정확하게 일치했다.
- application.properties의 mybatis.type-aliases-package 설정도
도메인 패키지별로 꼼꼼히 등록했다
그런데도 InquiryMapper가 Bean으로 등록되지 않아 DI가 실패했다!
해결 과정
1. 설정 파일 확인
- @Mapper 누락, type-aliases-package, XML 경로, 파일명, 오타 등
여러 설정을 점검했으나 모두 이상 없었음.
2. Application 클래스에서 @MapperScan 범위 문제 발견!
- @SpringBootApplication 위에이렇게 user.repository만 매퍼 스캔하고 있었음!
- @MapperScan("com.example.board.user.repository")
- inquiry.repository는 스캔 대상에서 완전히 빠져 있었던 것!
3. 해결 방법 적용
- @MapperScan에 inquiry.repository도 함께 스캔하도록 상위 패키지 한 번에 스캔하도록 설정
4. 정상 동작 확인
- 설정 수정 후 InquiryMapper가 Bean으로 정상 등록되어
InquiryService에서 의존성 주입이 잘 되는 것을 확인!
느낀 점 & 정리
- @MapperScan의 범위를 좁게 잡으면,
새로 만든 매퍼가 Bean으로 등록되지 않을 수 있다! - 실무/팀 프로젝트에서는
최상위 패키지 단위로 한 번에 스캔하는 게 관리에 훨씬 유리함 - 또, type-aliases-package도 마찬가지로
하위 패키지까지 넓게 등록하는 습관이 장기적으로 안전하다 - 런타임 DI 에러가 나오면
패키지 스캔 범위부터 반드시 확인하자!
결론
MyBatis에서 매퍼가 Bean으로 등록되지 않는 문제는
대부분 스캔 범위(@MapperScan)에서 빠져 있는 경우다.
새로운 도메인/매퍼를 만들 때는
패키지 구조와 스캔 범위를 반드시 점검하는 습관을 들이자!
'Archive > 예전 TIL' 카테고리의 다른 글
| [트러블슈팅] FK 무결성 오류와 로그인 미구현 상태에서 user_id 입력 문제 (0) | 2025.07.02 |
|---|---|
| [트러블슈팅] @Controller vs @RestController, 404 에러 & 정상 동작 차이 (0) | 2025.06.28 |
| JPA: N+1 문제란? (0) | 2025.05.16 |
| JPA 쿼리를 활용한 성능 개선 (0) | 2025.02.18 |
| ADMIN 권한 검증 시 에러 문제 (0) | 2025.02.11 |