런타임 디렉터리 선택: Java / Spring Boot에서 파일 저장 위치 결정

%23 런타임 디렉터리 선택: Java / Spring Boot에서 파일 저장 위치 결정

요약

이 문서는 애플리케이션 실행 시 파일을 저장할 신뢰할 수 있는 "기본 디렉터리(base directory)"를 선택하는 방법을 정리합니다. 예: logs와 같은 런타임 폴더 옆에 web-client 폴더를 생성하는 경우를 다루며, IDE/패키지(JAR)/서비스 환경별 주의점과 Spring Boot에 적합한 권장 전략을 제공합니다.

문제 정의

애플리케이션이 로컬 디렉터리에 파일을 저장해야 할 때, 어느 위치에 디렉터리를 만들지 결정하는 것은 중요합니다:

• IDE에서 실행하면 클래스 파일이 target/classes 아래에 존재합니다.
• JAR로 패키징해 실행하면 코드가 JAR 내부에 있고, 로그 등 런타임 산출물은 보통 JAR 파일과 같은 디렉터리에 생성됩니다.
• systemd 같은 서비스로 등록하면 프로세스의 작업 디렉터리(working directory)가 JAR 위치와 다를 수 있습니다.

목표: web-client 폴더가 예측 가능한 위치(예: 패키지된 JAR 옆, logs와 동일한 위치)에 생성되도록 결정하는 방법을 찾습니다.

선택지와 장단점

1. System.getProperty("user.dir") (프로세스 작업 디렉터리)
   • 장점: 간단하며 현재 작업 디렉터리를 반영합니다.
   • 단점: 프로세스를 어떻게 시작했는지에 따라 달라집니다. 서비스 매니저가 다른 작업 디렉터리를 지정할 수 있어 JAR 위치를 보장하지 않습니다.
2. ProtectionDomain / codeSource로 JAR/클래스 위치 결정
   • 예: MyClass.class.getProtectionDomain().getCodeSource().getLocation()
   • 장점: JAR로 실행될 때 JAR 파일 URL을 반환하므로 JAR의 부모 폴더를 기준으로 삼을 수 있습니다.
   • 단점: IDE에서 실행하면 target/classes를 가리킬 수 있고, 보안 관리자나 특수한 클래스로더 구성에서 null이 될 수 있습니다.
3. Spring Boot의 ApplicationHome
   • org.springframework.boot.system.ApplicationHome은 Spring Boot 애플리케이션에서 실행 위치(또는 JAR 위치)를 안정적으로 해결합니다.
   • 장점: 이 목적을 위해 설계되었고 JAR/폭발된(exploded) 형태 모두를 적절히 처리합니다.
   • 단점: Spring Boot 의존성이 필요하며, 비-Spring 환경에서는 사용할 수 없습니다.
4. 설정 기반 경로 (properties / environment)
   • 장점: 가장 명시적이고 제어 가능함 (예: app.base-dir=/opt/myapp/data). 운영 환경에서 권장됩니다.
   • 단점: 운영팀이 값을 설정해야 하며 로컬 개발에서는 번거로울 수 있습니다.
5. ClassLoader 리소스 위치 또는 ServletContext
   • WAR 배포 환경에서는 ServletContext.getRealPath()가 도움이 될 수 있으나 JAR 환경에서는 신뢰하기 어렵습니다.

권장 전략

IDE에서 실행하거나 JAR/서비스로 패키징해 실행하는 경우를 모두 고려할 때, 다음 계층화된 접근을 권장합니다:

1. 설정 값(app.base-dir)을 우선 사용합니다(우선순위 높음). 예: application.properties 또는 환경 변수 APP_BASE_DIR.
2. 설정이 없으면 Spring Boot가 사용 중인 경우 ApplicationHome을 사용해 JAR 또는 클래스가 위치한 디렉터리를 찾아 그 아래 web-client 같은 하위 폴더를 생성합니다.
3. ApplicationHome을 사용할 수 없거나 실패하면 ProtectionDomain/codeSource를 시도합니다.
4. 위 방법들이 모두 실패하면 user.dir로 폴백합니다.

이 방식은 서비스 환경에서 예측 가능한 동작을 제공하면서 개발 환경에서의 편의성도 보장합니다.

구현 주의사항 (Java / Spring Boot)

• 디렉터리 생성에는 항상 java.nio.file.Path와 Files.createDirectories(...)를 사용하세요.
• 경로 구분자는 하드코딩된 /나 \\ 대신 File.separator 또는 Path API를 사용하세요.
• IOException 등을 적절히 처리하고 어떤 폴백을 사용했는지 로그로 남기세요.
• 프로덕션 환경에서는 설정으로 베이스 디렉터리를 주입하는 방법을 권장합니다.

예시 구현 (Spring Boot 친화적)

import java.nio.file.Path;
import java.nio.file.Paths;
import java.nio.file.Files;
import java.io.File;
import org.springframework.boot.system.ApplicationHome;
import lombok.extern.slf4j.Slf4j;

@Slf4j
public final class BaseDirResolver {
    private static final String DEFAULT_FOLDER = "web-client";

    public static Path resolveBaseDir(String configuredBaseDir) {
        if (configuredBaseDir != null && !configuredBaseDir.isBlank()) {
            return Paths.get(configuredBaseDir).toAbsolutePath();
        }

        // 1) ApplicationHome 시도 (Spring Boot)
        try {
            ApplicationHome home = new ApplicationHome(BaseDirResolver.class);
            File dir = home.getDir();
            if (dir != null) {
                return dir.toPath().resolve(DEFAULT_FOLDER).toAbsolutePath();
            }
        } catch (Throwable t) {
            log.debug("ApplicationHome 사용 불가, 폴백 진행", t);
        }

        // 2) ProtectionDomain / codeSource 시도
        try {
            java.net.URL codeLocation = BaseDirResolver.class.getProtectionDomain().getCodeSource().getLocation();
            Path codePath = Paths.get(codeLocation.toURI());
            Path parent = codePath.getParent();
            if (parent != null) {
                return parent.resolve(DEFAULT_FOLDER).toAbsolutePath();
            }
        } catch (Throwable t) {
            log.debug("codeSource 조회 실패, 폴백", t);
        }

        // 3) user.dir 폴백
        return Paths.get(System.getProperty("user.dir")).resolve(DEFAULT_FOLDER).toAbsolutePath();
    }

    public static Path ensureBaseDir(Path baseDir) throws java.io.IOException {
        Files.createDirectories(baseDir);
        return baseDir;
    }
}

사용 방법 (Spring Boot 서비스)

• 운영 환경에서는 application.properties 또는 환경 변수에 app.base-dir를 설정하는 것을 권장합니다.
• 설정이 없으면 이 구현은 JAR이 위치한 디렉터리 옆에 web-client를 생성하므로 보통 logs가 생성되는 위치와 동일해집니다.

systemd / 서비스 고려사항

• systemd 유닛은 WorkingDirectory를 설정할 수 있는데, user.dir에 의존하는 경우 이를 명시해야 합니다.
• JAR 위치를 기준으로 삼으면 WorkingDirectory 설정과 무관하게 JAR의 부모 디렉터리를 찾아 사용하므로 더 안정적입니다.

예시 systemd 스니펫:

[Service]
User=appuser
ExecStart=/usr/bin/java -jar /opt/myapp/myapp.jar
WorkingDirectory=/opt/myapp
Restart=on-failure

테스트 및 검증

• 단위 테스트: 세 가지(설정, ApplicationHome, codeSource/user.dir) 경로를 모의(mock)하거나 시뮬레이션해 반환값을 검증합니다.
• 통합 테스트: 패키징된 JAR을 로컬에서 실행해 JAR 옆에 web-client가 생성되는지 확인합니다.
• 서비스 테스트: 실제 서버에 배포해 systemd로 시작 후 logs와 web-client가 동일 위치에 생성되는지 확인합니다.

보안 및 권한

• 프로세스가 선택한 베이스 디렉터리에 쓰기 권한이 있는지 확인하세요.
• 불필요하게 전체 권한(모두 쓰기)으로 디렉터리를 생성하지 마세요.
• 업로드 파일명은 경로 탐색(path traversal) 공격을 방지하도록 검증하세요.

마이그레이션 / 배포 체크리스트

• 운영팀이 명시적 경로를 선호하면 application-*.properties에 app.base-dir를 추가하세요.
• JAR 위치에 의존한다면 서비스 매니저가 JAR을 의도한 디렉터리에 두도록 문서화하세요.
• 운영자용 문서에 디렉터리 결정 방식을 명시하세요.

결론

설정 우선 접근(먼저 app.base-dir 확인), 그 다음 ApplicationHome(또는 codeSource), 마지막으로 user.dir 폴백을 사용하는 것이 가장 예측 가능하고 실무에 적합합니다. 이는 프로덕션(JAR/서비스)에서는 일관성을 보장하고 개발(IDE) 환경에서는 편의성을 제공합니다.

---

참고: 이 노트는 최근 LocalFileUtils.getBaseDir 변경 사항과 런타임 logs 옆에 web-client를 생성해야 하는 요구사항을 바탕으로 작성되었습니다.