가이드 문서 업로드
This commit is contained in:
USER
@@ -0,0 +1,158 @@
|
|||||||
|
# 📘 Legacy Spring MVC (AS-IS) to Spring Boot 4.0.7 (TO-BE) 마이그레이션 가이드
|
||||||
|
|
||||||
|
본 문서는 레거시 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)
|
||||||
|
```xml
|
||||||
|
<!-- 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`
|
||||||
|
```yaml
|
||||||
|
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 코드로 등록.
|
||||||
|
```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)**:
|
||||||
|
```jsp
|
||||||
|
<%@ 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)**:
|
||||||
|
```jsp
|
||||||
|
<%@ 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` 설정.
|
||||||
Reference in New Issue
Block a user