본 문서는 레거시 Spring MVC 기반 프로젝트(first_old)를 최신 Spring Boot 4.0.7 (Java 21, Jakarta EE 10) 환경(first)으로 마이그레이션하기 위한 기술 사양, 아키텍처 변경점, 설정 매핑 및 트러블슈팅 내역을 체계적으로 정리한 마이그레이션 매뉴얼입니다.

1. AS-IS vs TO-BE 비교 아키텍처

구분	AS-IS (`first_old`)	TO-BE (`first`)	변경 및 마이그레이션 사유
Java Version	Java 8 (1.8)	Java 21 (LTS)	현대적인 Java LTS 스펙 활용 및 성능 향상
Framework	Spring Framework 3.2.18	Spring Boot 4.0.7	스프링 부트 생태계 통합 및 내장 서버/자동 설정 적용
Servlet Spec	Java EE / Servlet 2.5 (`javax.servlet.*`)	*Jakarta EE 10 (`jakarta.servlet.`)**	Java EE → Jakarta EE 네임스페이스 표준 변경 대응
View Engine & JSTL	JSTL 1.2 (`http://java.sun.com/jsp/jstl/core`)	Jakarta JSTL (`jakarta.tags.core`)	`tomcat-embed-jasper` 및 Jakarta 스펙 태그립 적용
ORM / Data Access	MyBatis 3.2.2 + egovframework `EgovAbstractMapper`	MyBatis Spring Boot Starter 4.0.1	전자정부 프레임워크 종속성 제거 및 스프링 부트 스타터 통합
Database Connection Pool	Commons DBCP 1.4	HikariCP	Spring Boot 기본 고성능 커넥션 풀 적용
SQL Logging	`log4jdbc-remix` (`0.2.7`)	`log4jdbc-log4j2` (`1.16`)	Java 21 및 최신 JDBC 드라이버 로깅 호환성 확보
설정 방식 (Config)	XML 기반 (`web.xml`, `context-*.xml`, `action-servlet.xml`)	Java Config & YAML (`application.yml`, `WebMvcConfig`)	XML 설정 완전 폐기 및 가독성/유지보수성 향상
외부/레거시 모듈	egovframework(2.7/3.5), Nexacro/Xplatform XAPI, Log4j 1.x	모두 제거 (표준 Spring Boot 사용)	불필요한 고전 라이브러리 및 벤더 종속성 제거

2. 의존성 (`pom.xml`) 정비 내역

2.1. 제거된 레거시 의존성 (AS-IS)

egovframework.rte.* (전자정부 프레임워크 런타임 모듈 전면 제거)
com.nexacro:nexacro-xapi, com.tobesoft:xplatform-xapi (레거시 UI 모듈 제거)
commons-dbcp, org.apache.tomcat:tomcat-dbcp (Commons DBCP 제거)
org.lazyluke:log4jdbc-remix, log4j:log4j:1.2.15 (구형 로깅 모듈 제거)
javax.servlet:servlet-api, javax.servlet.jsp:jsp-api, javax.servlet:jstl (javax 스펙 제거)

2.2. 신규 추가/대체된 의존성 (TO-BE)

<!-- 1. Spring Boot Web Starter -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- 2. MyBatis Spring Boot Starter (Spring Boot 4.x 호환 4.0.1) -->
<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>4.0.1</version>
</dependency>

<!-- 3. Oracle JDBC (ojdbc11) -->
<dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc11</artifactId>
    <scope>runtime</scope>
</dependency>

<!-- 4. log4jdbc-log4j2 로깅 -->
<dependency>
    <groupId>org.bgee.log4jdbc-log4j2</groupId>
    <artifactId>log4jdbc-log4j2-jdbc4.1</artifactId>
    <version>1.16</version>
</dependency>

<!-- 5. JSP 렌더링 및 Jakarta JSTL -->
<dependency>
    <groupId>org.apache.tomcat.embed</groupId>
    <artifactId>tomcat-embed-jasper</artifactId>
</dependency>
<dependency>
    <groupId>jakarta.servlet.jsp.jstl</groupId>
    <artifactId>jakarta.servlet.jsp.jstl-api</artifactId>
</dependency>
<dependency>
    <groupId>org.glassfish.web</groupId>
    <artifactId>jakarta.servlet.jsp.jstl</artifactId>
</dependency>

3. XML 설정 → Java Config / YAML 마이그레이션 매핑

3.1. `web.xml` 마이그레이션

CharacterEncodingFilter: Spring Boot의 server.servlet.encoding.charset=UTF-8 자동 설정으로 대체.
DispatcherServlet: ServletInitializer.java 및 Spring Boot 내장 톰캣 자동 서블릿 등록으로 대체.

3.2. `context-datasource.xml` & `context-mapper.xml` → `application.yml`

spring:
  datasource:
    driver-class-name: net.sf.log4jdbc.sql.jdbcapi.DriverSpy
    url: jdbc:log4jdbc:oracle:thin:@localhost:1521:xe
    username: YOUR_USERNAME
    password: YOUR_PASSWORD

mybatis:
  config-location: classpath:/config/mybatis-config.xml
  mapper-locations: classpath:/mapper/**/*_SQL.xml
  type-aliases-package: first

3.3. `action-servlet.xml` → `WebMvcConfig.java`

ViewResolver (JSP 뷰): application.yml에 spring.mvc.view.prefix=/WEB-INF/jsp/, spring.mvc.view.suffix=.jsp 설정 추가.
ArgumentResolver & Interceptor: WebMvcConfigurer 구현 클래스에서 Java 코드로 등록.

@Configuration
@EnableSpringDataWebSupport
public class WebMvcConfig implements WebMvcConfigurer {

    @Autowired
    private LoggerInterceptor loggerInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(loggerInterceptor)
                .addPathPatterns("/**");
    }

    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(new CustomMapArgumentResolver());
    }
}

4. 코드 레벨 주요 변경 사항

4.1. `javax.` → `jakarta.` 네임스페이스 일괄 변경

AS-IS: import javax.servlet.http.HttpServletRequest;
TO-BE: import jakarta.servlet.http.HttpServletRequest;

4.2. JSP JSTL 태그립 URI 변경

AS-IS (Sun URI):

<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %>

TO-BE (Jakarta URI):

<%@ taglib prefix="c" uri="jakarta.tags.core" %>
<%@ taglib prefix="fn" uri="jakarta.tags.functions" %>
<%@ taglib prefix="fmt" uri="jakarta.tags.fmt" %>

5. 주요 트러블슈팅 & 해결 방안

5.1. Pageable 파라미터 바인딩 및 음수 인덱스 처리 버그

문제: 게시판 첫 진입 시 PAGE_INDEX 파라미터가 0으로 전달되어 DAO 페이징 쿼리의 시작 번호(START)가 음수(-9)로 계산되어 SQL 에러가 발생함.
해결: AbstractDAO 내에서 pageIndex 검증 로직 추가 (if (pageIndex < 1) pageIndex = 1;), WebMvcConfig에 @EnableSpringDataWebSupport 적용.

5.2. ClassCastException 및 데이터 형변환 예외

문제: DAO 조회 결과 반환 시 ArrayList를 Map으로 타입 캐스팅을 시도하거나, Integer 타입의 객체를 (String)으로 강제 형변환 시 예외 발생.
해결: DAO 결과 반환 타입을 List<Map<String, Object>>로 정규화하고, 파라미터 추출 시 String.valueOf()를 통해 안전한 문자열 변환 적용.

5.3. log4jdbc DriverSpy 연동 에러

문제: net.sf.log4jdbc.sql.jdbcapi.DriverSpy 설정 시 log4jdbc.log4j2.properties 누락으로 인한 초기화 실패.
해결: src/main/resources/log4jdbc.log4j2.properties 파일 생성 및 log4jdbc.spylogdelegator.name=net.sf.log4jdbc.log.slf4j.Slf4jSpyLogDelegator 설정.

README.md

📘 Legacy Spring MVC (AS-IS) to Spring Boot 4.0.7 (TO-BE) 마이그레이션 가이드