Backend/Java

Java 17 마이그레이션의 최대 적: InaccessibleObjectException 완벽 타파 및 해결 가이드

미니임 2026. 3. 4. 23:32

 

자바 생태계는 빠르게 진화하고 있습니다. 특히 무료 장기 지원(LTS) 버전인 Java 8이나 11에서 Java 17, 혹은 그 이상으로 마이그레이션하는 것은 현대적인 백엔드 시스템을 구축하기 위한 필수적인 단계가 되었습니다. 문법적인 개선이나 가비지 컬렉터(GC)의 성능 향상 등 얻을 수 있는 이점이 막대하기 때문입니다.

하지만 컴파일 에러를 모두 잡고 호기롭게 애플리케이션을 구동하는 순간, 런타임 환경에서 붉은색 로그와 함께 시스템을 멈춰 세우는 불청객을 만나게 됩니다.

Plaintext
 
java.lang.reflect.InaccessibleObjectException: Unable to make field private final byte[] java.lang.String.value accessible: module java.base does not "opens java.lang" to unnamed module @...

애플리케이션의 뼈대를 이루는 스프링 부트(Spring Boot), 하이버네이트(Hibernate), 혹은 내부적으로 깊게 사용 중인 JSON 직렬화 라이브러리(Gson, Jackson) 등에서 주로 터져 나오는 이 에러는 왜 발생하는 것일까요? 오늘은 이 예외의 근본적인 원인을 깊이 파헤치고, 현업에서 이를 우아하게 해결하는 방법을 알아보겠습니다.

핵심 개념 설명 (Deep Dive): 왜 내 객체에 접근할 수 없다는 걸까?

이 에러를 이해하려면 Java 9부터 도입된 JPMS(Java Platform Module System), 일명 직소 프로젝트(Project Jigsaw)를 이해해야 합니다.

과거 Java 8 시절까지의 자바는 내부 API에 대한 접근 통제가 다소 느슨했습니다. 리플렉션(Reflection)의 setAccessible(true) 메서드만 호출하면, JDK 내부의 숨겨진 private 필드나 메서드에도 강제로 접근하여 값을 읽고 쓸 수 있었습니다. 이는 수많은 라이브러리가 "마법" 같은 기능을 구현하는 원동력이 되었지만, 동시에 JVM의 보안과 업그레이드 안정성을 크게 훼손하는 양날의 검이었습니다.

Java 9에서는 모듈이라는 새로운 단위를 도입하여, 모듈이 명시적으로 exports 하거나 opens 하지 않은 패키지에는 외부에서 접근할 수 없도록 **강력한 캡슐화(Strong Encapsulation)**를 적용했습니다. Java 16부터는 이 제한이 기본적으로 활성화(--illegal-access=deny)되었고, Java 17은 이를 더욱 엄격하게 강제합니다.

🏢 사내 보안 시스템으로 이해하는 캡슐화 비유 (Analogy)

  • Java 8 시대 (오픈 플랜 오피스): 회사에 칸막이가 없습니다. 개발팀 직원이든 영업팀 직원이든, 원한다면 언제든 CEO의 책상 서랍(private 필드)을 열어 기밀 문서를 볼 수 있었습니다 (setAccessible(true)).
  • Java 17 시대 (부서별 보안 출입증): 이제 각 부서는 벽으로 분리된 모듈이 되었습니다. CEO(JDK 내부 java.base 모듈)는 명시적으로 "개발팀에게 내 서랍 접근을 허용한다(opens)"라고 결재하지 않는 이상, 어떤 출입증(리플렉션)을 대더라도 문이 열리지 않습니다. 무단 침입을 시도하면 보안 시스템이 경고를 울리는데, 이것이 바로 InaccessibleObjectException입니다.

풍부한 실전 예제 (Hands-on)

실제 이커머스 비즈니스 로직에서 마주칠 수 있는 상황을 가정해 보겠습니다. 구형 버전의 라이브러리나 자체 제작한 'Deep Copy(깊은 복사)' 유틸리티 클래스가 객체의 상태를 복사하기 위해 리플렉션을 과도하게 사용하고 있다고 상상해 봅시다.

1. 문제 상황 발생 (안티 패턴)

아래 코드는 주문 정보를 복사하기 위해 리플렉션으로 모든 필드에 접근하는 구형 유틸리티의 핵심 로직입니다.

Java
 
import java.lang.reflect.Field;
import java.time.LocalDateTime;

public class LegacyDeepCopyUtils {
    
    // 객체의 모든 필드를 스캔하여 복사하는 레거시 메서드
    public static <T> T cloneObject(T original) throws Exception {
        Class<?> clazz = original.getClass();
        T clone = (T) clazz.getDeclaredConstructor().newInstance();

        for (Field field : clazz.getDeclaredFields()) {
            // 경고: Java 17에서는 여기서 InaccessibleObjectException이 발생할 수 있습니다!
            // 특히 original이 JDK 내부 클래스(예: java.time 내부 필드 등)를 포함할 때 치명적입니다.
            field.setAccessible(true); 
            field.set(clone, field.get(original));
        }
        return clone;
    }
}

// 비즈니스 도메인
class Order {
    private String orderId;
    private LocalDateTime orderTime;
    // 생성자, Getter, Setter 생략
}

이 코드는 Java 8에서는 완벽하게 동작하지만, Java 17 환경에서 String의 내부 value 바이트 배열이나 LocalDateTime의 내부 필드에 접근하려 할 때 예외를 던집니다.

2. 트러블슈팅(Troubleshooting)과 즉각적인 우회 방법 (JVM Args)

운영 환경 배포가 코앞인데 라이브러리를 모두 업데이트할 시간이 없다면, JVM 실행 인자를 통해 "예외적인 접근 권한"을 부여할 수 있습니다.

에러 로그를 자세히 살펴보면 힌트가 있습니다.

module java.base does not "opens java.lang" to unnamed module...

이 말은 java.base 모듈이 java.lang 패키지를 열어주지 않았다는 뜻입니다. 애플리케이션 실행 시 아래 옵션을 추가합니다.

Bash
 
# java.base 모듈의 java.lang 패키지를 모든 이름 없는 모듈(우리의 앱/라이브러리)에 개방합니다.
java --add-opens java.base/java.lang=ALL-UNNAMED \
     --add-opens java.base/java.time=ALL-UNNAMED \
     -jar my-ecommerce-app.jar
  • 형식: --add-opens <제공하는_모듈>/<열어줄_패키지>=<접근할_모듈>
  • ALL-UNNAMED는 클래스패스에 있는 모듈화되지 않은 모든 코드(대부분의 레거시 앱)를 의미합니다.

3. 근본적인 해결책 (Best Practice)

--add-opens는 진통제일 뿐입니다. 근본적인 해결을 위해서는 리플렉션을 통한 강제 접근을 제거해야 합니다.

  1. 라이브러리 버전 업그레이드: Gson, Jackson, Spring, Hibernate 등은 이미 오래전에 Java 17 모듈 시스템에 대응하는 업데이트를 완료했습니다. 종속성 버전을 최신으로 올리는 것이 가장 안전합니다.
  2. 비즈니스 로직 리팩토링: 리플렉션 대신 복사 생성자나 표준적인 매핑 라이브러리(MapStruct 등), 또는 Java 14부터 도입된 record를 활용하여 불변 객체를 생성하는 방식으로 설계를 변경합니다.
Java
 
// Java 17 환경에 맞게 리팩토링된 최신 도메인 설계
// record를 사용하면 불변성이 보장되어 깊은 복사 자체가 필요 없어지는 경우가 많습니다.
public record OrderDto(String orderId, LocalDateTime orderTime) {
    // 필요한 경우 복사 팩토리 메서드 제공
    public OrderDto withNewTime(LocalDateTime newTime) {
        return new OrderDto(this.orderId, newTime);
    }
}

장단점 및 고려사항 (Trade-offs)

기술 부채를 관리하는 관점에서 두 가지 해결책을 비교해 보겠습니다. 이를 단순한 수식으로 표현하자면, 기술 부채에 따른 리스크($R$)는 레거시 의존성의 수($L$)에 비례하고, 다음 JDK 업그레이드까지 남은 시간($T$)에 반비례합니다. 여기에 JVM 플래그 사용 시 부과되는 기술적 페널티($C_{flag}$)를 곱할 수 있습니다.

$$R = \frac{L}{T} \times C_{flag}$$
해결 방식 장점 (Pros) 단점 및 한계 (Cons) 추천 상황
--add-opens 옵션 추가 코드를 수정할 필요가 없음. 적용이 매우 빠름. 기술 부채의 증가. 보안 취약점 노출. 향후 Java 버전에서 이 옵션 자체가 막힐 위험 존재. 메이저 업그레이드 직전 핫픽스가 필요할 때, 서드파티 라이브러리의 패치가 아직 없을 때.
라이브러리 업그레이드 & 리팩토링 장기적인 안정성 확보. JDK 보안 모델 준수. 최신 기능 활용 가능. 의존성 간의 충돌 해결 등 리소스 소모가 큼. 회귀 테스트(Regression Test) 필수. 마이그레이션 프로젝트의 초기 단계, 시스템의 코어 로직을 다룰 때.

결론 및 요약

Java 17의 InaccessibleObjectException은 단순한 버그가 아니라, 자바 생태계가 안정성과 보안을 위해 나아가고 있는 방향성을 보여주는 명확한 이정표입니다. JVM이 걸어둔 빗장을 --add-opens라는 마스터키로 계속 열고 다닐 수는 없습니다.

마이그레이션을 진행 중이라면, 이 예외를 단순히 '해결해야 할 에러'로 보지 말고 우리 시스템 내에 숨어있는 '과도한 리플렉션 의존성'을 찾아내는 건강 검진으로 활용하시길 바랍니다.

반응형