트러블슈팅 및 설정 개선 노트 (2025-09-12)

1. Git: .gitignore가 적용되지 않는 문제 해결

문제 상황

.gitignore 파일에 특정 파일이나 폴더(예: .idea, target)를 추가했음에도 불구하고, Git이 계속해서 해당 파일들을 추적(tracking)하고 commit 대상에 포함시키는 문제가 발생했습니다.

원인

.gitignore를 설정하기 전에 이미 git add . 명령으로 해당 파일들이 Git의 추적 대상(staging area)에 포함되었기 때문입니다.

해결 방법

Git이 추적하고 있는 파일들의 캐시(cache)를 삭제하고, .gitignore가 적용된 상태로 다시 추가하는 과정이 필요합니다.

# 1. Git이 현재 추적하고 있는 모든 파일의 캐시를 삭제합니다.
# (실제 파일은 그대로 남아있고, Git의 관리 목록에서만 빠집니다.)
git rm -r --cached .

# 2. .gitignore가 적용된 상태로 모든 파일을 다시 추가합니다.
git add .

# 3. 변경사항을 커밋합니다.
git commit -m "Fix: .gitignore 파일 추적 문제 해결"

# 4. 원격 저장소에 푸시합니다.
git push origin <브랜치이름>

---

2. Eclipse 개발 환경 문제 해결

2-1. XML 파일 인식 불가 문제

• 문제 상황: Eclipse에서 MyBatis Mapper XML 파일이나 pom.xml 등이 일반 텍스트 파일로 인식되어, 자동 완성이나 문법 검사 기능이 동작하지 않았습니다.
• 해결 방법: Eclipse Marketplace에서 "Eclipse Web Developer Tools" 나 "Spring Tools" 와 같은 웹/스프링 개발에 필요한 핵심 플러그인을 설치하여 해결했습니다.

2-2. Lombok 적용 불가 문제

• 문제 상황: pom.xml에 Lombok 의존성을 추가했음에도, 이클립스에서 @Getter, @Setter 등의 어노테이션을 인식하지 못하고 에러를 표시했습니다.
• 원인: Lombok은 Maven 의존성 추가 외에, IDE 자체에 별도의 설치 과정이 필요합니다.
• 해결 방법:
  1. 다운로드한 lombok.jar 파일을 실행 (java -jar lombok.jar).
  2. Lombok 설치 프로그램이 뜨면, Specify Location... 버튼을 눌러 현재 사용 중인 eclipse.exe 파일의 경로를 지정해 주고 Install 버튼을 클릭하여 설치를 완료했습니다.

---

3. Spring & MyBatis 설정 개선

3-1. Mapper XML 경로를 application.properties에서 관리하기

MyBatis가 Mapper XML 파일을 찾을 수 있도록 경로를 지정하는 setMapperLocations 설정을 SpringConfig.java에 추가하고, 경로 값은 application.properties 파일에서 유연하게 관리하도록 개선했습니다.

SpringConfig.java

@Bean
public SqlSessionFactoryBean sqlSessionFactory(DataSource dataSource, ApplicationContext context) throws Exception {
    SqlSessionFactoryBean factory = new SqlSessionFactoryBean();
    factory.setDataSource(dataSource);
    
    // application.properties에 정의된 mybatis.mapper-locations 값을 읽어와 Mapper XML 경로로 사용
    factory.setMapperLocations(context.getResources(env.getProperty("mybatis.mapper-locations")));

    // ... 기타 설정 ...
    return factory;
}

application.properties

# MyBatis Mapper XML 파일들의 위치
mybatis.mapper-locations=classpath:/mapper/**/*.xml

[중요!] @MapperScan과의 차이점
@MapperScan은 Java로 작성된 Mapper 인터페이스를 찾는 역할이고, setMapperLocations는 XML 파일을 찾는 역할입니다. 두 가지를 분리해서 사용하는 경우, 두 설정 모두 필요합니다.

3-2. Type Alias 패키지 설정

XML 파일에서 VO나 DTO 클래스를 사용할 때, 긴 전체 경로 대신 짧은 클래스 이름만 사용할 수 있도록 application.properties에 type-aliases-package를 설정했습니다.

application.properties

# VO/DTO 클래스들이 모여있는 패키지 경로 (이 경로 아래 모든 클래스가 대상이 됨)
mybatis.type-aliases-package=lx.edu.levelup.feature

적용 예시:

<insert id="insertDB" parameterType="lx.edu.levelup.feature.user.domain.UserVO">

<insert id="insertDB" parameterType="UserVO">

[주의!] @MapperScan과의 중복 가능성
@MapperScan(basePackages = "...") 어노테이션 역시 지정된 패키지 안에서 Type Alias를 자동으로 등록하는 기능이 있습니다. 만약 @MapperScan의 경로와 type-aliases-package 경로가 겹친다면, 별칭이 중복으로 등록되어 오류가 발생할 수 있습니다. 가급적 @MapperScan을 사용하거나, type-aliases-package를 사용하거나 한 가지 방식으로 통일하는 것이 좋습니다.