fix: EgovFileUtil 이 VFS 초기화 실패를 debug 로 삼켜 이후 호출이 원인 불명 NPE 로 끝나던 문제 수정, 결함 API deprecated

[comghost]

수정 사유 Reason for modification

• 버그수정 Bug fixes
• 기능개선 Enhancements
• 기능추가 Adding features
• 기타 Others

수정된 소스 내용 Modified source

문제

EgovFileUtil 은 static 초기화에서 Commons VFS 매니저와 기준 디렉터리를 만드는데, 실패하면 debug 로그만 남기고
넘어갑니다. 그 뒤의 rm/cp/mv/touch/cd/pwd 호출은 전부 null 필드를 참조해 NullPointerException 으로
끝나고, 로그 레벨이 debug 가 아니면 원인을 알 길이 없습니다.

rm/cp/mv 의 실패도 debug 로만 남습니다. 예외를 던지지 않는 계약이라 호출자는 반환값(rm 의 -1)이나 파일 상태를
직접 확인해야 하는데, 운영 로그에는 아무 흔적이 없어 "복사됐다고 믿었는데 파일이 없는" 상황을 사후에 추적할 수 없습니다.

그리고 이름과 동작이 다른 API 가 있습니다.

API	실제 동작
cd/pwd	프로세스 전역 static 기준 경로를 바꾸고 읽는다. 웹 환경에서 한 요청의 cd 가 다른 모든 스레드의 상대 경로 해석 기준을 바꾼다
grep (2종)	패턴에 맞는 줄이 아니라 패턴을 기준으로 나눈 조각을 돌려준다
ls	목록을 채우지 않고 항상 빈 리스트를 돌려준다(debug 로그만 남김)

수정

항목	이전	이후
VFS 초기화 실패	debug 로그, 이후 호출은 NPE	WARN 로그, 이후 호출은 원인과 대체 경로를 담은 IllegalStateException (manager()/basefile() 가드)
rm/cp/mv 실패	debug 로그	WARN 로그(대상 경로 포함). 예외를 던지지 않는 계약과 반환값은 그대로
cd/pwd/grep×2/ls	—	@Deprecated + javadoc 에 결함 내용과 대체 경로(EgovFiles) 안내. 동작은 그대로

기존 동작을 바꾼 것은 없습니다. 초기화가 성공한 환경(정상)에서는 로그 내용만 달라지고, 실패한 환경에서는 NPE 대신
설명이 있는 예외를 받습니다.

호환성

• 공개 시그니처 변경·제거 없음. deprecated 표기는 컴파일 경고만 냅니다.
• rm 의 -1 반환, cp/mv 의 무예외 복귀는 그대로입니다.
• 초기화 실패 환경에서 NullPointerException 을 잡고 있던 코드가 있다면 이제 IllegalStateException 을 받습니다.
  둘 다 RuntimeException 입니다.

JUnit 테스트 JUnit tests

• JUnit 테스트 JUnit tests
• 수동 테스트 Manual testing

EgovFileUtilInitGuardTest 5건 신규, fdl.filehandling 모듈 전건 통과.

환경	기본 로케일(Locale)	모듈 실행 건수	결과
Windows	ko_KR	127	Tests run: 127, Failures: 0, Errors: 0, Skipped: 2
Linux (Ubuntu 22.04 / OpenJDK 17)	C.UTF-8	127	Tests run: 127, Failures: 0, Errors: 0, Skipped: 5

Skipped 는 기존 테스트의 OS 조건부 건너뛰기(플랫폼별 파일시스템 동작)이며 이 PR 과 무관합니다. 신규 5건은 두 환경 모두 실행·통과했습니다.

구분	건수	내용
초기화 실패 가드	2	매니저가 없으면 rm/touch/cp/mv 가 IllegalStateException(메시지에 원인과 EgovFiles 안내) · 기준 디렉터리가 없으면 pwd 가 같은 예외
실패 로그	2	없는 원본을 cp/mv 하면 예외 없이 돌아오고 WARN 로그가 남는다(Log4j2 캡처)
기존 동작	1	deprecated grep 은 조각을, ls 는 빈 리스트를 그대로 돌려준다

가드 테스트는 static 필드를 리플렉션으로 비웠다가 반드시 되돌리므로 다른 테스트에 영향을 주지 않습니다.

수동 확인: 현재 main(cc2b332) 위에서 fdl.filehandling 모듈 빌드·테스트가 통과함을 Windows 와 Linux 에서 확인했습니다.

테스트 브라우저 Test Browser

• Chrome
• Firefox
• Edge
• Safari
• Opera
• Internet Explorer
• 기타 Others

해당 없음 — 라이브러리 내부 수정입니다.

테스트 스크린샷 또는 캡처 영상 Test screenshots or captured video

해당 없음 — 위 JUnit 테스트 결과로 갈음합니다.

---

_{base: eGovFramework:main @ cc2b332 (2026-09-10 fetch 기준, #366~#379 머지 후) · 단일 커밋}

[jei007]

표준프레임워크에 대한 지속적인 참여에
대단히 감사드립니다.