JBoss에 EgovFramework 배포 시 spring-modules-validation 충돌 오류 완벽 해결 가이드

AI 생성 이미지: JBoss에 EgovFramework 배포 시 spring-modules-validation 충돌 오류 완벽 해결 가이드

레거시 전자정부프레임워크를 JBoss나 WildFly에 올릴 때, 로컬에서는 문제없던 기능이 운영 환경에서 ClassLoader 관련 예외로 배포가 실패하는 일이 자주 발생합니다. 이 문서는 JBoss에 EgovFramework 배포 시 spring-modules-validation 충돌 오류 완벽 해결 가이드를 목표로, 원인 분석과 실무에서 바로 적용 가능한 대응 방법을 단계별로 정리합니다.

핵심은 구형 Validation 라이브러리(spring-modules-validation:0.9)와 JBoss가 제공하는 javax.validation 모듈, 그리고 공통 로깅류(commons-logging) 간의 충돌을 적절히 정리하는 것입니다. 아래에서 pom.xml 의존성 관리와 jboss-deployment-structure.xml 설정을 통해 문제를 해결합니다.

📚 목차

• 1. 발생 환경과 대표 증상 정리
• 2. 근본 원인: JBoss ClassLoader vs 구형 Validation 라이브러리
• 3. 해결 1단계: pom.xml에서 의존성 정리
• 4. 해결 2단계: jboss-deployment-structure.xml 설정
• 5. 실무 체크리스트 & FAQ
• 6. 마무리: 의존성 관리이 곧 안정화

---

1. 💻 발생 환경과 대표 증상 정리

전형적으로 문제가 발생하는 환경과 흔한 증상을 짚어보겠습니다.

• 프레임워크: EgovFramework(전자정부프레임워크)
• WAS: JBoss 또는 WildFly 계열
• 빌드 도구: Maven 기반의 pom.xml
• 주요 라이브러리: spring-modules-validation:0.9, commons-logging 등

1-1. 흔히 보는 오류 메시지 예시

운영 로그에 보이는 전형적인 예외는 다음과 같습니다.

Caused by: java.lang.NoClassDefFoundError: org/springmodules/validation/commons/DefaultBeanValidator
    at ...
Caused by: java.lang.ClassCastException: 
    org.hibernate.validator.engine.ConstraintValidatorFactoryImpl 
    cannot be cast to javax.validation.ConstraintValidatorFactory
    at ...
        

클래스가 존재함에도 NoClassDefFoundError가 발생하거나, 같은 타입 간에 ClassCastException이 나는 경우는 거의 대부분 ClassLoader의 분리로 인한 충돌 패턴입니다. 이 문서 전체에서 다루는 해결책은 JBoss에 EgovFramework 배포 시 spring-modules-validation 충돌 오류 완벽 해결 가이드의 실무 지침을 따르는 것입니다.

---

2. 🧩 근본 원인: 구형 Validation 라이브러리 vs JBoss 모듈 시스템

EgovFramework 기반 프로젝트는 오래된 Spring 모듈과 함께 배포되는 경우가 많습니다. 특히 spring-modules-validation:0.9 같은 구형 라이브러리는 JBoss의 모듈화된 클래스 로딩과 충돌하기 쉽습니다.

의존성	역할	문제 포인트
egovframework.rte.ptl.mvc	EgovFramework의 MVC 및 포틀릿 기능	내부에서 commons-logging 등 공통 라이브러리를 포함
org.springmodules:spring-modules-validation:0.9	Spring 기반의 폼 유효성 검증	JBoss/WildFly 내장 Validation 모듈과 버전·클래스 충돌
javax.validation (JBoss 내장)	Bean Validation API 및 구현 제공(예: Hibernate Validator)	애플리케이션이 가져온 Validation 라이브러리와 로더 충돌 가능

요약: 서로 다른 소스에서 동일한 타입이 로드되면, ClassLoader 분리 때문에 타입 호환성이 깨집니다. 이로 인해 JBoss에 EgovFramework 배포 시 spring-modules-validation 충돌 오류가 발생하는 근본 원인이 됩니다.

---

3. 🔧 해결 1단계: pom.xml에서 의존성 정리

먼저 빌드 단계에서 불필요하거나 충돌을 유발하는 라이브러리를 제거합니다. 핵심은 문제의 출처를 명확히 하고 필요한 것만 명시적으로 포함시키는 것입니다.

3-1. Egov MVC 모듈 의존성에서 충돌 라이브러리 Exclude

egovframework.rte.ptl.mvc 의존성에서 commons-logging과 spring-modules-validation을 제외하여 애플리케이션 패키지에 중복 추가되는 것을 방지합니다.

<dependency>
    <groupId>egovframework.rte</groupId>
    <artifactId>egovframework.rte.ptl.mvc</artifactId>
    <version>${egovframework.rte.version}</version>
    <exclusions>
        <exclusion>
            <groupId>commons-logging</groupId>
            <artifactId>commons-logging</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.springmodules</groupId>
            <artifactId>spring-modules-validation</artifactId>
        </exclusion>
    </exclusions>
</dependency>
        

3-2. 필요한 경우, Validation 라이브러리 별도 명시

Validation 기능이 필수라면 한 가지 구현으로 통일해 관리하세요. 가능하면 JSR-303/JSR-380(Hibernate Validator 등)으로 전환하는 것이 장기적으로 안정적입니다.

<dependency>
    <groupId>org.springmodules</groupId>
    <artifactId>spring-modules-validation</artifactId>
    <version>0.9</version>
    <scope>compile</scope>
</dependency>
        

TIP. 즉시 교체가 어렵다면 버전과 스코프를 명확히 지정해 충돌 범위를 좁히고, 단계별로 JSR 기반 구현으로 마이그레이션하세요.

---

4. 🧱 해결 2단계: jboss-deployment-structure.xml로 서버 모듈 조정

JBoss는 자체 모듈 로딩 규칙이 있어 애플리케이션이 서버 내장 모듈과 충돌할 수 있습니다. 이 경우 서버 모듈을 명시적으로 제외해 애플리케이션이 사용하는 라이브러리를 우선하도록 설정합니다.

4-1. javax.validation.api 서버 모듈 제외

JBoss가 제공하는 javax.validation 모듈을 제외하면, 애플리케이션에 번들된 Validation 구현이 정상적으로 동작할 가능성이 높습니다. 아래 설정을 WEB-INF 또는 EAR의 META-INF에 추가하세요.

<jboss-deployment-structure>
    <deployment>
        <exclusions>
            <module name="javax.validation.api" />
        </exclusions>
    </deployment>
</jboss-deployment-structure>
        

다만 서버 모듈을 무조건 제거하는 것이 항상 정답은 아닙니다. 애플리케이션이 JBoss 내장 Validation을 전제로 작성되었다면, 오히려 애플리케이션 쪽 라이브러리를 제거하는 편이 안전합니다. 로그와 클래스 버전을 확인해 판단하세요.

주의. 설정 적용 후 배포 로그에서 어떤 클래스가 어떤 모듈에서 로드되는지 다시 확인하세요. 잘못된 제외는 다른 런타임 오류를 유발할 수 있습니다.

---

5. ✅ 실무 체크리스트 & 자주 하는 질문(FAQ)

5-1. 배포 전 체크리스트

1. pom.xml에서 중복/구형 Validation 라이브러리 확인
   spring-modules-validation, hibernate-validator, javax.validation 관련 의존성을 중복 포함하지 않도록 점검합니다.
2. 서버 내장 모듈과 충돌 여부 확인
   JBoss 모듈 목록을 확인하여 애플리케이션과 동일한 라이브러리가 서버에 있는지 파악하고, 필요 시 jboss-deployment-structure.xml로 조정합니다.
3. 로컬(내장 Tomcat)과 JBoss 환경 차이 인지
   내장 톰캣에서는 평면 클래스패스에서 동작하지만, JBoss는 모듈 단위로 로딩합니다. 환경 차이를 항상 염두에 두세요.

5-2. FAQ

Q1. 로컬에서는 정상인데 운영 JBoss에서만 오류가 납니다.

A1. 로컬 개발 서버는 단일 클래스패스에서 모든 라이브러리를 로딩합니다. 반면 JBoss는 모듈 기반이라 동일 클래스라도 서로 다른 로더에서 로드되면 ClassCastException과 같은 문제가 발생할 수 있습니다.

Q2. spring-modules-validation을 완전히 제거해도 되나요?

A2. 해당 라이브러리를 사용하는 Validator 코드가 없다면 제거해도 좋습니다. 하지만 기존에 광범위하게 사용 중이라면 대체수단(JSR-303/JSR-380)으로의 전환 계획을 세우고 점진적으로 교체하세요.

Q3. commons-logging 제외는 필수인가요?

A3. 프로젝트에서 SLF4J/Logback 등으로 통합된 로깅을 사용한다면, 중복된 commons-logging은 로그 혼선과 예기치 못한 동작을 초래할 수 있어 제외하는 것이 안전합니다.

---

6. 🚀 마무리: 의존성 관리이 곧 안정화

요약하면, JBoss에 EgovFramework 배포 시 spring-modules-validation 충돌 오류는 서버의 모듈 시스템과 구형 Validation 라이브러리 간의 로딩 충돌에서 기인합니다. 문제 해결의 골자는 두 가지입니다.

• pom.xml에서 중복·불필요 라이브러리 제거 및 명시적 관리
• jboss-deployment-structure.xml로 서버 내장 모듈 조정
• 가능하면 Validation 스택을 JSR 표준 계열로 통일

이 가이드라인을 따르면 JBoss에 EgovFramework 배포 시 spring-modules-validation 충돌 오류 완벽 해결 가이드를 기반으로 운영 배포 안정성을 크게 개선할 수 있습니다. 의존성을 체계적으로 관리하는 것이 곧 불필요한 긴급 대응을 줄이는 가장 실용적인 방법입니다.

© 2025 칼퇴하는 개발자. 모든 권리 보유.

함께 보면 좋은 엔터프라이즈 사례

• SRE 관점에서의 SLA 예측과 자동복구 회로설계 실전 가이드
• 비용 최적화: 클라우드 스팟·권한 기반 자동스케일링 실전 절감법
• 실무자용 인프라 IaC 정책으로 컴플라이언스 자동화와 증적관리

🚀 이 주제, 우리 서비스에 어떻게 적용할까요?

JBoss에 EgovFramework 배포 시 spring-modules-validation 충돌 오류 완벽 해결 가이드를 실제 서비스와 조직에 녹여보고 싶다면, 현재 아키텍처와 운영 방식을 한 번 점검해 보는 것부터 시작해 보세요. 팀 위키나 기술 블로그, 사내 스터디 주제로도 아주 좋습니다.

이 글이 도움이 됐다면, 비슷한 엔터프라이즈 사례 글들도 함께 살펴보면서 우리 조직에 맞는 운영 상용구를 정의해 보세요.

AI 생성 이미지: JBoss에 EgovFramework 배포 시 spring-modules-validation 충돌 오류 완벽 해결 가이드