이클립스에서 MyBatis XML 회색으로 나올 때, 진짜 해결 방법은 이거다

실무에서 마주친 MyBatis XML 회색 현상, 대체 왜 이러는 걸까?

최근 회사 프로젝트에서 새로운 기능을 추가하기 위해 user-mapper.xml 파일을 열었는데, 뭔가 이상했다. 분명 쿼리는 제대로 작성했는데 XML 코드 전체가 회색으로 표시되는 것이다. 이클립스에서 흔히 볼 수 있는 회색 톤 = ‘해석 못함’이란 건 익히 알고 있었기에, 혹시 설정이 잘못됐나 싶어서 확인해봤다.

결론부터 말하자면, 이 문제는 **MyBatis XML 파일이 제대로 등록되지 않았거나**, **Mapper 인터페이스와 연결이 안 되어 있을 때 발생하는 전형적인 사례**다. 이번 실무노트에서는 이클립스에서 MyBatis 매퍼 XML이 회색으로 나올 때의 원인과 그 해결 과정을 단계별로 정리해 본다.

문제 상황 요약: MyBatis XML이 전부 회색

증상

• MyBatis XML 파일(.xml)을 열면 전체 쿼리가 회색으로 표시됨
• 자동 완성(IntelliSense) 미작동
• Mapper 인터페이스에서 XML 매핑 메서드 인식 못함 (빨간 줄 없음)

실제로 겪었던 코드 예시

<mapper namespace="com.project.user.UserMapper">

    <select id="selectUser" resultType="com.project.user.UserVO">
        SELECT * FROM user WHERE id = #{id}
    </select>

</mapper>

정상적인 코드인데도 회색으로 표시되고, Mapper 인터페이스에서 이 쿼리를 못 읽는 현상이 발생했다.

해결 방법 1: Mapper XML과 인터페이스 연결 확인

1단계: namespace와 인터페이스 이름 일치 여부 확인

<mapper namespace="..."> 부분이 **해당 인터페이스의 FQCN(전체 경로)**와 일치해야 한다.

// Mapper 인터페이스
package com.project.user;

public interface UserMapper {
    UserVO selectUser(String id);
}

<mapper namespace="com.project.user.UserMapper"> ← 이게 정확히 일치해야 함

하나라도 틀리면 이클립스가 연결 못 하고 전부 회색으로 나온다.

2단계: resources 경로에 위치 확인

보통 src/main/resources에 매퍼 파일이 있어야 하고, 빌드 시 resource로 복사되는지도 확인해야 한다. IDE가 인식을 못 하는 경우는 대부분 resources 폴더 외부에 mapper가 있을 때 발생한다.

올바른 구조 예시:

src/
├─ main/
│  ├─ java/
│  │  └─ com/project/user/UserMapper.java
│  └─ resources/
│     └─ mapper/
│        └─ user-mapper.xml

해결 방법 2: 이클립스에서 MyBatis 플러그인 연동 확인

1단계: 이클립스에 MyBatis 플러그인 설치 여부 확인

MyBatis를 제대로 인식시키려면 MyBatis Plugin for Eclipse 또는 MyBatis Plugin for Spring Tools Suite가 설치되어 있어야 한다. 아래처럼 설치한다:

• Help → Eclipse Marketplace
• "mybatis" 검색
• MyBatis Plugin 설치

설치 후엔 **이클립스를 재시작**해야 반영된다.

2단계: Mapper 설정을 프로젝트에 등록

혹시나 Maven/Gradle 프로젝트라면 다음 설정들이 제대로 되어 있는지 확인한다.

@Mapper
public interface UserMapper {
    UserVO selectUser(String id);
}

@Configuration
@MapperScan(basePackages = "com.project.user")
public class MyBatisConfig {
    // SqlSessionFactory 설정 등
}

이게 빠지면 매퍼 인터페이스는 등록되지만 XML과 연결이 안 되어서 전부 회색으로 나올 수 있다.

해결 방법 3: IDE 캐시 강제 재빌드

다 해봤는데도 회색이면, **이클립스 캐시 문제**일 수 있다. 아래 순서대로 초기화 작업을 한다.

1. 프로젝트 우클릭 → Refresh
2. Project → Clean
3. 이클립스 종료 후 .metadata 캐시 삭제

혹은 이클립스를 아예 재설치하고, STS(Spring Tools Suite) 환경을 쓰면 해결되는 경우도 많다.

보너스: application.xml 또는 application.yml 설정 확인

스프링 부트 기반일 경우, mybatis.mapper-locations 설정이 누락돼 있어도 매퍼 인식을 못 한다.

mybatis:
  mapper-locations: classpath:mapper/**/*.xml

해당 설정이 누락되어 있으면 애플리케이션은 구동돼도 IDE는 쿼리 인식을 못 하기도 한다.

결론: 회색이라고 무시하면 안 된다

이클립스에서 MyBatis XML이 회색으로 나오는 건 단순한 IDE 문제처럼 보일 수 있지만, 사실은 **매우 실무적인 설정 실수**다. IDE와 프로젝트가 연결돼 있지 않거나, 매퍼 구조가 꼬이면 정상 작동하지 않게 된다. 이번 실무노트를 통해 다음에 비슷한 상황이 오더라도 빠르게 원인을 짚어내고 해결할 수 있기를 바란다.