VS Code 자바 Import 자동 정리 설정 및 와일드카드 오류 예방법

자바 개발자가 VS Code에서 매번 import 수동으로 지우다 현타오는 이유

코드를 고치고 기능을 추가하다 보면 어느새 파일 상단에 쓰이지 않는 import 구문이 수십 줄씩 쌓입니다. 인텔리제이(IntelliJ IDEA)를 쓸 때는 단축키 한 번으로, 혹은 저장할 때 알아서 싹 정리되던 것들이 VS Code로 넘어오면 묘하게 삐걱거립니다. import 정리가 안 된 코드는 단순히 지저분한 것을 넘어 Git 커밋 히스토리를 더럽히고 코드 리뷰 때 불필요한 논쟁을 만듭니다. 프로젝트 규모가 커질수록 이 자잘한 찌꺼기들이 빌드 속도와 정적 분석 툴(SonarQube 등)에서 경고를 뿜어내는 주범이 되기도 합니다.

 

현업에서 수많은 주니어들이 "선배, VS Code는 원래 저장할 때 import 정리 안 되나요?"라고 묻습니다. 결론부터 말하면 아주 잘 됩니다. 다만 인텔리제이처럼 처음부터 다 차려진 밥상이 아닐 뿐입니다. 설정을 제대로 맞추지 않고 대충 쓰면 와일드카드(.*)가 마음대로 들어가서 라이브러리 충돌이 나거나, 필요 없는 패키지가 그대로 남아서 배포 가공 단계까지 올라가는 고통을 겪게 됩니다.

실무에서 와일드카드 import(.*)를 방치했을 때 터지는 문제들

가장 먼저 짚고 넘어갈 점이 있습니다. 바로 import java.util.*; 같은 와일드카드 패턴입니다. VS Code의 기본 Java 확장 기능(Extension Pack for Java)은 일정 개수 이상의 클래스를 같은 패키지에서 가져오면 자동으로 와일드카드로 묶어버리는 경향이 있습니다. 이게 왜 실무에서 시한폭탄이 되는지 아십니까?

 

만약 내가 List를 쓰려고 java.util.*을 열어뒀는데, 나중에 다른 라이브러리나 다른 패키지에서 똑같이 List라는 이름의 클래스를 추가하면 그 즉시 모호성 오류(Ambiguous class resolution)가 발생하면서 빌드가 깨집니다. 로컬에서는 잘 돌다가 젠킨스(Jenkins) 배포 파이프라인에서 갑자기 빌드가 터져서 새벽에 로그를 뒤지게 만드는 주범이 바로 이 녀석입니다. 팀원들마다 import 스타일이 다르면 메인 브랜치로 머지(Merge)할 때마다 무수한 충돌(Conflict) 지옥을 맛보게 됩니다.

VS Code 자바 설정 - 생성형 ai 이미지

VS Code Java Import 자동 정리 및 최적화 핵심 설정법

이제 손을 움직여서 환경을 바꿀 차례입니다. VS Code에서 자바 개발 생산성을 인텔리제이 급으로 끌어올리려면 settings.json을 직접 건드려야 합니다. UI 메뉴에서 체크박스 몇 개 누르는 걸로는 완벽하게 제어할 수 없습니다. Ctrl + Shift + P(맥은 Cmd + Shift + P)를 누르고 **Preferences: Open User Settings (JSON)**을 선택한 뒤 아래 설정을 이식하십시오.

{
    "java.completion.importOrder": [
        "java",
        "javax",
        "jakarta",
        "org",
        "com",
        "$"
    ],
    "java.onniche.organizeImports.starThreshold": 99,
    "java.onniche.organizeImports.staticStarThreshold": 99,
    "editor.codeActionsOnSave": {
        "source.organizeImports": "explicit"
    }
}

설정 항목들이 무엇을 의미하는지 정확히 알아야 나중에 아키텍처가 바뀌어도 대응할 수 있습니다. 각 항목의 구체적인 작동 원리는 다음과 같습니다.

• java.completion.importOrder: 패키지가 상단에 정렬되는 순서를 정의합니다. 자바 표준 API(java, javax, jakarta)를 가장 위에 두고, 그다음 외부 라이브러리(org, com)를 배치합니다. 마지막 $는 static import를 어디에 둘지 결정하는 기호입니다. 이렇게 순서를 강제해야 팀원 간 커밋 충돌이 사라집니다.
• starThreshold: 99: 와일드카드(*)로 뭉개버릴 클래스 개수의 임계값입니다. 기본값이 5나 10으로 되어 있으면 한 패키지에서 클래스를 5개만 가져다 써도 자동으로 .*로 변합니다. 이걸 99처럼 현실적으로 도달하기 힘든 숫자로 올려놓아야 모든 클래스가 명시적으로 개별 import 됩니다.
• source.organizeImports: explicit: 핵심 중의 핵심입니다. 파일 복사나 코드 수정 후 Ctrl + S로 **저장하는 그 순간, 쓰이지 않는 코드를 실시간으로 감지해서 import 구문에서 즉시 삭제**해 줍니다.

Q&A: "이렇게 자동 설정을 켜두면 대규모 레거시 프로젝트에서 성능 저하가 없나요?"

많은 주니어들이나 인프라 환경이 타이트한 곳에서 자주 나오는 질문입니다. 파일 하나 저장할 때마다 백그라운드에서 구문을 다 분석하고 import를 들었다 놨다 하면 에디터가 버벅거리지 않냐는 걱정입니다. 결론부터 말하면, 2025~2026년 기준 VS Code의 랭귀지 서버(Eclipse JDT Language Server) 아키텍처는 이미 충분히 고도화되어 수천 개 클래스가 얽힌 프로젝트에서도 저장 시 딜레이가 밀리초(ms) 단위에 불과합니다.

 

다만 트레이드오프가 전혀 없는 것은 아닙니다. 메모리가 8GB 이하인 극단적인 저사양 환경이거나, 네트워크 드라이브를 통해 원격으로 소스코드를 마운트해서 개발하는 특수한 상황(WSM이나 아주 느린 가상환경)에서는 저장할 때마다 랭귀지 서버가 디스크 I/O를 유발하면서 약 0.5초에서 1초 정도 커서가 굳는 현상이 생길 수 있습니다. 하지만 일반적인 로컬 개발 환경(M 시리즈 맥북이나 16GB 이상의 PC)이라면 이로 인한 손해보다, 손으로 일일이 import 지우다가 낭비되는 개발자 인건비와 집중력 저하가 훨씬 더 큰 손실입니다.

팀 표준 정렬(Checkstyle 및 Eclipse Format) 연동하기

혼자 개발할 때는 위의 설정만으로 충분하지만, 현업은 팀 단위로 움직입니다. 누군가는 인텔리제이를 쓰고, 누군가는 이클립스를 쓰며, 나만 VS Code를 쓰고 있을 확률이 높습니다. 이때 나 혼자 import 순서를 다르게 정렬해서 푸시하면 코드 리뷰 시스템이 변경 사항으로 꽉 차서 팀장에게 한 소리 듣기 딱 좋습니다. 이를 방지하려면 프로젝트 루트에 포맷터를 심어야 합니다.

 

가장 확실한 방법은 구글 자바 스타일(Google Java Style Guide)이나 팀에서 공통으로 쓰는 eclipse-formatter.xml 파일을 프로젝트에 포함하는 것입니다. VS Code 설정에 아래 한 줄을 추가해서 프로젝트 내부의 룰셋을 바라보게 만드십시오.

{
    "java.format.settings.url": "${workspaceRoot}/.settings/eclipse-formatter.xml"
}

이렇게 지정해 두면 VS Code의 Java 확장 기능이 이클립스나 인텔리제이(Adapter 플러그인 사용 시)와 정확히 일치하는 규칙으로 import 구문을 정렬하고 최적화합니다. 내가 저장 버튼을 누를 때마다 팀의 컨벤션에 완벽하게 부합하는 정제된 코드가 만들어집니다.

결국 어떤 선택을 해야 하는가?

환경과 상황에 따라 세팅의 결을 조금씩 달리해야 합니다. 무조건 정답인 설정은 없습니다. 내 상황이 어디에 속하는지 보고 움직이십시오.

• 나 홀로 개발하거나 사이드 프로젝트를 하는 경우: 고민할 것 없이 본문에 소개해 드린 settings.json 설정을 전역(User settings)에 박아 넣으십시오. 손가락 아프게 오거나이즈 임포트 단축키를 누를 필요도 없이 저장 한 번으로 인생이 편해집니다.
• 기존 인텔리제이 중심의 끈끈한 백엔드 팀에 합류한 경우: 팀원들이 공유하는 코드 스타일 가이드 파일(.xml 또는 .editorconfig)이 있는지 먼저 확인하십시오. 그걸 받아서 java.format.settings.url로 연결하는 것이 선행되어야 커밋 로그로 원성을 사지 않습니다.
• 저사양 가상 PC나 클라우드 컨테이너 환경에서 개발하는 경우: onSave 액션이 에디터를 무겁게 만든다면 자동 저장은 끄고, 커밋 직전에 단축키 Shift + Alt + O를 눌러서 수동으로 한 번씩 털어내 주는 타협안이 정신 건강에 이롭습니다.

VSCode Format on Save, 실무에서 독이 될까 약이 될까? 15년 차 개발자의 심층 분석