Spring/Java 레거시 마이그레이션이 매주 수작업이 되는 이유#
Spring과 Java를 함께 올릴 때는 코드뿐 아니라 빌드 도구, 의존성, 설정과 런타임 동작도 확인해야 합니다. 먼저 현재 버전과 목표 버전을 기록하세요.
작업 전 안전 확인: 비밀번호·토큰 등 비밀정보와 고객 데이터는 파일, 프롬프트, 로그에서 제외합니다.
| 확인 항목 | Spring Boot 3.0 전환 시 공식 안내 | 프로젝트에서 확인할 것 |
|---|---|---|
| 준비 버전 | 최신 2.7.x로 먼저 올리도록 안내 | 현재 Boot 버전과 중간 업그레이드 가능 여부 |
| Java | Java 17 이상 필요 | 빌드·배포 환경의 JDK |
| 의존성 | Boot가 관리하지 않는 의존성의 호환 버전 확인 | 직접 지정한 라이브러리와 전이 의존성 |
| Jakarta EE | 관련 API와 패키지가 javax에서 jakarta로 변경 | 적용 대상 의존성과 import; 모든 javax가 전환 대상은 아님 |
| 설정 | 일부 설정 이름 변경·제거 | 시작 진단과 설정 파일, 런타임 동작 |
출처: Spring Boot 3.0 마이그레이션 가이드. 이 표는 3.0 가이드에 한정되며 목표 버전의 지원 상태나 다른 버전의 요구사항을 대신하지 않습니다.
Spring 마이그레이션 계획과 검증 범위#
현재·목표 버전과 의존성을 적고 컴파일 오류를 분류하면 변경 순서를 논의할 수 있습니다. 위 표는 공식 문서에 근거한 확인 항목이지 실제 프로젝트의 버전 매트릭스나 마이그레이션 결과는 아닙니다.
| Boot 3.0 전환 확인 지점 | 공식 가이드의 변경 | 검증할 영향 |
|---|---|---|
| 설정 속성 | 일부 속성 이름이 바뀌거나 제거됨 | 사용 중인 설정과 시작 시 진단 |
| 웹 경로 | Spring Framework 6.0에서 끝 슬래시 매칭의 기본값이 false로 변경 | 기존 URL과 끝 슬래시 URL의 응답 |
| 보안 | Spring Security 6.0에서 모든 dispatch type에 인가 적용 | 사용하는 서블릿 dispatch와 접근 제어 |
출처: Spring Boot 3.0 마이그레이션 가이드. 각 행은 해당 변경을 쓰는 프로젝트에서 확인할 항목이지 실측 결과가 아닙니다.
단계별로 하기: 입력 규칙 → 실행 → 검증#
- 백업과 버전 관리를 준비하고 현재 JDK, Boot, 빌드 도구, 주요 의존성과 목표 버전을 기록합니다.
- 목표 버전의 공식 가이드와 호환성을 확인합니다. Mirr Code에는 파일을 바꾸기 전에 빌드 설정과 관련 코드를 조사하고 계획을 제안해 달라고 요청할 수 있습니다.
- 안전한 환경에서 기존 빌드와 테스트 결과를 기록하고, 업그레이드 후 컴파일 오류를 의존성·import·설정 등으로 분류합니다.
- 변경을 나눠 적용하고 단계마다 컴파일과 관련 테스트를 실행합니다. 설정, 인증, 데이터 접근과 실제 실행 동작도 별도로 확인합니다.
검증: 테스트 출력과 체크리스트#
컴파일 통과만으로 런타임 호환성은 증명되지 않습니다. 실행한 명령, 버전, 결과와 미실행 검사를 기록하세요. 실제 pom.xml 또는 build.gradle의 전후 버전, 오류 목록, 빌드와 테스트 출력은 아직 확보되지 않았습니다.
주의할 점과 한계#
javax를 일괄 치환하지 말고 해당 API와 의존성을 확인하세요. 운영 DB나 외부 서비스에 영향을 주는 작업은 별도 승인과 복구 계획이 필요합니다. 이 글에서는 Java 빌드나 Spring 마이그레이션을 실행하지 않았습니다.
현재 버전과 목표 버전을 분리해 기록하기#
Java와 Spring을 동시에 올릴 때는 개발자 PC의 버전만 보면 안 됩니다. 실제 빌드가 사용하는 JDK, CI의 JDK, 실행 이미지의 JRE와 배포 컨테이너를 나눠 적으세요. 로컬 컴파일은 통과하지만 실행 환경이 이전 Java를 쓰면 다른 오류가 생길 수 있습니다. 빌드 파일의 목표 언어 버전과 실제 실행한 도구의 버전도 구분합니다. 버전 매트릭스는 원하는 값의 목록이 아니라 확인한 현재 상태와 승인된 목표, 확인하지 못한 항목을 담아야 합니다.
Spring Boot 3.0 가이드는 특정 전환의 근거입니다. 현재 프로젝트가 2.x인지 3.x인지, 목표가 어느 유지보수 버전인지에 따라 읽을 안내가 달라집니다. 이 글의 Java 17·Spring Framework 6.0 설명을 다른 모든 Boot 버전의 요구사항으로 확대하지 마세요. 목표 버전의 지원 상태와 조직이 허용하는 JDK·의존성도 별도로 확인해야 합니다. 오래된 가이드가 존재한다는 사실은 그 버전을 지금 새로 채택하라는 권고가 아닙니다.
| 매트릭스 항목 | 현재 상태의 근거 | 목표를 정할 때 검토 |
|---|---|---|
| 빌드 JDK | 실제 빌드 명령의 버전 출력과 설정 | 목표 Boot·빌드 도구의 지원 범위 |
| 런타임 Java | 승인된 실행 이미지와 배포 설정 | 컴파일 결과를 실행할 수 있는 버전 |
| Boot·Framework | parent·plugin·의존성 관리 설정 | 해당 전환의 공식 마이그레이션 안내 |
| Maven·Gradle | wrapper와 plugin 설정 | 목표 JDK와 plugin 호환성 |
| 보안·데이터 계층 | 실제 의존성 좌표와 전이 목록 | 관련 프로젝트의 별도 전환 안내 |
| 외부 연동 | 승인된 테스트 설정과 클라이언트 | TLS·직렬화·인증의 동작 확인 |
표의 칸에 추정 버전을 채우지 마세요. wrapper 파일이 있어도 누군가 시스템에 설치된 다른 빌드 도구를 실행했을 수 있습니다. 실행 기록이 없다면 설정에서 읽은 버전이라고 표시합니다. 비공개 저장소 주소, 인증 헤더와 자격 증명은 매트릭스에 넣을 필요가 없습니다. 의존성을 조사하는 명령도 저장소 접근이나 다운로드를 일으킬 수 있으므로 승인된 환경에서만 실행해야 합니다. 이 글에서는 Java 빌드를 실행하지 않았습니다.
오류 수를 줄이기 전에 원인을 묶기#
컴파일 오류가 많다고 모두 다른 결함은 아닙니다. 의존성 하나가 빠져 여러 파일에서 같은 타입을 찾지 못할 수 있습니다. 먼저 첫 오류와 반복 패턴을 읽고 JDK·의존성·import·메서드 계약으로 분류하세요. 오류 메시지를 한 줄씩 지우려고 임의의 라이브러리를 추가하면 충돌이 더 늘 수 있습니다. 변경한 의존성과 그 이유를 기록하고 같은 명령으로 다시 확인합니다. 원인별 묶음은 작업 큐이며 실제 해결 개수를 부풀리는 지표로 쓰지 않습니다.
가상의 작업 큐에는 오류 위치, 관련 의존성, 공식 근거, 변경 범위와 확인할 검사를 적을 수 있습니다. “타입 없음”이면 좌표가 바뀐 것인지 전이 의존성이 사라진 것인지 먼저 구분합니다. “메서드 없음”이면 API 변경과 잘못된 버전 선택을 나눠 봅니다. 컴파일러가 가리킨 줄만 고치지 말고 호출자의 기대 계약도 읽으세요. 같은 문자열을 일괄 치환하기 전에 변경 대상이 같은 API인지 확인해야 합니다.
오류 개수는 실행 조건에 따라 달라질 수 있습니다. 빌드가 초기에 중단되거나 표시 개수가 제한되면 숫자가 줄어도 실제 문제가 줄었다고 단정할 수 없습니다. 전체 출력과 종료 상태, 대상 모듈과 사용한 명령을 함께 기록하세요. 변경 전부터 실패하던 검사는 새 회귀와 구분합니다. 로그에 비밀 설정이나 고객 정보가 섞일 수 있으므로 공유할 때는 필요한 오류 위치와 타입만 남기는 편이 좋습니다.
javax와 jakarta를 API 단위로 구분하기#
Jakarta EE 전환은 문자열 전체를 바꾸는 작업이 아닙니다. 사용 중인 API와 의존성 좌표가 어떤 버전으로 이동하는지 확인한 뒤 관련 import를 바꿔야 합니다. Java SE에 속하는 javax 패키지까지 무조건 jakarta로 바꾸면 안 됩니다. 반대로 소스 import만 고치고 이전 Java EE 의존성이 전이 경로에 남아 있으면 충돌할 수 있습니다. 직접 의존성과 전이 의존성을 함께 조사하는 이유입니다.
예를 들어 Servlet API는 목표 환경의 컨테이너와 함께 검토해야 합니다. 라이브러리의 클래스 이름을 바꾸는 것과 실행 컨테이너가 해당 API를 제공하는지는 다른 문제입니다. JPA와 검증 API도 provider와 관련 라이브러리가 함께 맞아야 합니다. 구체적인 목표 버전의 공식 문서에서 지원 조합을 확인하세요. 이름이 비슷한 artifact를 임의로 추가하거나 여러 버전을 동시에 넣어 컴파일만 통과시키는 대응은 피합니다.
소스 외의 문자열도 대상일 수 있습니다. 설정 파일, 서비스 등록과 자동 구성 파일에 이전 클래스 이름이 남아 있으면 컴파일 이후 시작 단계에서 실패할 수 있습니다. 테스트 fixture와 예제 문서도 확인하되 수정 범위를 승인받아 나눕니다. 이 글은 특정 저장소의 모든 전환 지점을 찾아냈다는 주장이 아닙니다. AI에는 후보와 근거를 먼저 제시하도록 요청하고 사람이 실제 API와 좌표를 대조한 뒤 적용하도록 계획하세요.
설정 속성 변경을 시작 오류와 연결하기#
컴파일이 통과한 뒤에는 애플리케이션 시작과 설정 바인딩을 확인해야 합니다. 이름이 바뀌거나 제거된 속성이 있으면 기존 설정이 더 이상 같은 의미로 적용되지 않을 수 있습니다. Spring Boot 3.0 가이드는 spring-boot-properties-migrator를 사용한 진단과 임시 런타임 변환을 설명하고 전환 뒤 제거하도록 안내합니다. 이 도구를 넣었다는 사실만으로 설정 정리가 끝난 것은 아닙니다. 실제 진단과 적용 설정을 검토해야 합니다.
환경별 설정도 다릅니다. 로컬에서 사용하는 프로필과 CI·운영의 프로필이 같지 않을 수 있으므로 어느 설정으로 시작했는지 기록하세요. 비밀값은 출력하지 않고 키와 적용 여부만 확인할 수 있는 방법을 검토합니다. 진단을 보려고 민감한 관리 엔드포인트의 마스킹을 해제하거나 운영 설정 전체를 공개하면 안 됩니다. 설정 오류를 없애려고 기본값을 임의로 바꾸기 전에 기존 의도와 담당자의 요구를 확인해야 합니다.
설정 변경은 테스트에서도 검증합니다. 정상 시작뿐 아니라 필수 설정 누락, 잘못된 값과 사용하지 않아야 할 기본값을 확인할 필요가 있습니다. 가짜 설정으로 통과한 단위 테스트는 실제 환경의 비밀값·네트워크·권한을 검증하지 않습니다. 승인된 테스트 환경이 없다면 필요한 입력을 정확히 남기세요. 시작 로그 한 줄이 보였다고 인증, 데이터 접근과 모든 외부 연동이 정상이라고 보고하지 않습니다.
웹 경로와 보안의 동작 회귀 고르기#
기존 URL과 끝 슬래시 URL을 모두 사용하던 서비스라면 두 요청의 동작을 따로 확인합니다. Boot 3.0 가이드가 설명하는 Framework 6.0의 기본 매칭 변경 때문에 이전과 달라질 수 있습니다. 모든 경로를 무조건 허용하는 설정으로 덮기 전에 실제 외부 링크와 API 계약을 검토하세요. 리다이렉트, 명시적 경로와 프록시 처리는 각각 영향이 다릅니다. 실제 선택은 서비스의 요구사항과 담당자의 승인에 따라 정합니다.
보안에서는 정상 로그인만 보지 마세요. 인증하지 않은 요청, 다른 사용자 대상, 오류 dispatch와 사용하는 비동기 경로를 검토합니다. 공식 가이드의 dispatch 인가 변경은 사용 중인 서블릿 흐름과 대조해야 합니다. 오류가 난다는 이유로 인증 필터를 끄거나 모든 요청을 허용하면 전환의 목적과 무관한 취약점을 만들 수 있습니다. 기존 접근 제어의 의도를 먼저 기록하고 전후 테스트의 기대값을 독립적으로 정하세요.
세션·쿠키·CORS와 외부 인증 연동도 프로젝트가 사용하는 범위에서 확인합니다. 실제 계정과 운영 시스템으로 무단 시험하지 말고 승인된 테스트 계정과 환경을 요청하세요. 응답 상태 코드만 같다고 데이터 노출이나 권한 경계가 같다는 뜻은 아닙니다. 반환 필드와 오류 내용도 검토해야 합니다. 실행하지 못한 보안 검사는 별도 항목으로 남기고 “컴파일 통과” 보고에 포함해 숨기지 않습니다.
데이터 계층과 배치의 확인 범위#
ORM과 드라이버 버전이 바뀌면 쿼리 생성, 타입 매핑과 오류 처리도 확인할 필요가 있습니다. 실제로 사용하는 조회와 저장의 대표 조건을 고르고 기존 데이터와 새 데이터의 해석을 비교하세요. 단위 테스트에서 DB를 대체했다면 실제 쿼리 호환성은 미확인입니다. 테스트 DB가 필요하더라도 이 글의 작업을 위해 운영 DB에 연결하거나 새 인프라를 만들지는 않습니다. 데이터 소유자가 승인한 격리 환경에서 별도 검증해야 합니다.
시작할 때 실행되는 마이그레이션과 배치 작업도 주의합니다. 단순 실행 명령이 스키마나 외부 상태를 바꿀 수 있기 때문입니다. 전환 과정에서 자동 실행 범위가 달라지는지 관련 공식 안내와 설정을 읽으세요. 백업과 복구 계획은 소스 되돌리기와 별개입니다. 배치가 외부 메시지를 보냈다면 애플리케이션 버전을 낮춰도 메시지가 취소되지 않습니다. 부작용을 확인하기 전에는 실제 작업을 재시도하지 마세요.
완료 기준과 다음 담당자에게 줄 자료#
완료 기준은 목표 버전의 빌드, 승인된 시작 환경, 관련 단위·통합·보안 검사와 남은 제약으로 나눕니다. 버전 매트릭스, 변경한 의존성, 오류 분류와 실제 명령 출력을 연결해 남기세요. 오류를 줄이려고 제외한 모듈이나 건너뛴 테스트가 있다면 분명히 적어야 합니다. 전환 뒤 제거할 임시 도구와 설정도 목록으로 남깁니다. 지원 상태와 운영 배포 승인은 별도 검토입니다.
예를 들어 가상의 조사에서 빌드 설정의 목표 JDK는 확인했지만 배포 이미지의 실행 Java를 읽지 못했다면 매트릭스의 런타임 칸은 미확인입니다. 빌드 칸의 버전을 복사해 채우지 마세요. 컴파일은 통과했지만 서블릿 dispatch 인가 검사를 하지 않았다면 그 조건도 별도로 남깁니다. 이 문서에는 실제 pom.xml·build.gradle의 전후 화면, 재빌드와 동일 조건의 테스트 비교가 없으므로 전환 성공이나 소요 시간을 주장하지 않습니다.
근거: Spring Boot 3.0 공식 전환 가이드. 이 절의 구체적인 버전 요구는 해당 전환에 한정합니다. 현재 지원 버전이나 다른 Boot 버전의 요구사항을 선택하는 자료로 대신 사용하지 마세요.
의존성 충돌을 자동 추가로 해결하지 않기#
컴파일러가 타입을 찾지 못한다고 검색한 artifact를 바로 추가하지 마세요. 목표 Boot가 관리하는 의존성인지, 프로젝트가 직접 버전을 고정했는지와 다른 라이브러리가 이전 버전을 끌고 오는지 먼저 봅니다. 같은 클래스가 여러 JAR에 들어 있는 경우도 검토할 대상입니다. 직접 의존성을 늘려 오류 하나를 없애면 다른 모듈의 런타임 선택이 달라질 수 있습니다. 변경 이유와 공식 지원 조합을 확인하고 한 원인씩 적용하는 편이 검토하기 쉽습니다.
가상의 충돌 목록에는 소유 모듈, 직접 좌표, 전이 경로와 목표 버전의 근거를 적을 수 있습니다. 현재 버전과 목표 버전을 같은 칸에 섞지 않으면 어느 변경이 의도된 것인지 보입니다. 별도 프로젝트가 관리하는 Spring Cloud 같은 의존성은 그 프로젝트의 호환 안내도 필요합니다. Boot 버전 숫자와 비슷한 버전이라는 이유만으로 맞는 조합이라고 판단하지 마세요. 공식 문서가 없는 조합은 확인되지 않은 것으로 남겨야 합니다.
로그 형식 변화가 주변 도구에 미치는 영향#
애플리케이션의 기능 테스트가 통과해도 로그를 읽는 도구가 영향을 받을 수 있습니다. Boot 3.0 가이드는 기본 로그 날짜 형식의 변경을 설명합니다. 실제 프로젝트가 기본 형식을 사용하는지와 수집·파싱 규칙이 어떤 형식을 기대하는지 확인하세요. 새 형식이 보인다고 무조건 이전 형식으로 돌릴 필요는 없습니다. 운영 담당자가 선택한 계약에 맞춰 생산자와 소비자를 함께 검토해야 합니다. 로그를 조사할 때도 개인정보와 비밀값을 공개하지 않습니다.
관리 지표와 엔드포인트를 사용하는 경우에도 이름과 응답의 변화가 주변 모니터링에 영향을 줄 수 있습니다. 특정 메트릭 이름이 반드시 바뀐다고 일반화하지 말고 실제 사용한 기능과 목표 버전 안내를 대조하세요. 모니터링이 미확인이라면 애플리케이션 시작 성공을 전체 운영 준비 완료로 보고하지 않습니다. 승인된 테스트 환경에서 어떤 알림과 대시보드를 확인해야 하는지 담당자에게 인계해야 합니다. 실제 운영 알림을 무단으로 발생시키는 검사는 이 글의 범위가 아닙니다.
대규모 기계적 변경을 검토 가능한 묶음으로 나누기#
import 변경과 설정 변경, 테스트 보강을 같은 큰 diff에 모두 섞으면 원인을 찾기 어려울 수 있습니다. API 단위의 기계적 변경과 동작 검토가 필요한 수정을 나눌 수 있는지 살펴보세요. 자동 변환 도구를 사용한다면 선택한 recipe와 버전, 수정한 파일을 기록하고 결과를 직접 읽어야 합니다. 도구가 많은 파일을 바꿨다는 사실은 모든 변경이 맞다는 근거가 아닙니다. 이 글은 변환 도구를 설치하거나 실행한 기록을 제공하지 않습니다.
한 묶음마다 컴파일과 관련 검사를 확인하고 실패하면 같은 환경의 직전 상태와 비교합니다. 테스트를 통과시키기 위해 전환 대상이 아닌 javax까지 바꾸거나 보안 설정을 완화하지 마세요. 자동 생성 코드가 바뀌어야 한다면 원본 정의와 생성 규칙의 소유자를 확인해야 합니다. 생성 파일만 손으로 고치면 다음 생성에서 사라질 수 있습니다. 관련 문서나 운영 설정을 직접 수정할 권한이 없다면 필요한 변경과 검사를 구체적으로 전달하세요.
배포 전 남은 위험을 설명하기#
가상의 배포 검토에서 단위 테스트는 통과했지만 서블릿 오류 dispatch와 끝 슬래시 경로를 확인하지 않았다면, 그 두 조건을 먼저 검증할 대상으로 적을 수 있습니다. 기본 로그 형식이 바뀌었는데 수집기의 파서가 이전 형식만 읽는다면 애플리케이션 코드 밖에도 변경이 필요할 수 있습니다. 반대로 해당 기능을 쓰지 않는 프로젝트에 모든 예시를 무조건 추가할 필요는 없습니다. 실제 사용하는 경로와 버전별 변경을 연결해야 합니다.
목표 버전의 지원 상태와 배포 이미지, 설정·비밀 전달 경로도 별도 확인 대상입니다. 어떤 항목이 소스 조사이고 어떤 항목이 실행 관찰인지 표시하세요. 그래야 다음 담당자가 같은 컴파일을 반복하는 대신 남은 런타임 검사를 준비할 수 있습니다.
빌드 로그를 작업 큐로 옮길 때는 같은 원인의 반복 오류를 묶되 최초 위치와 영향을 받은 모듈은 남겨 두세요. 의존성 하나를 바꾼 뒤 여러 오류가 사라지면 그 관련성을 설명할 수 있습니다. 반대로 새로운 오류가 나타났다고 반드시 회귀인 것은 아닙니다. 앞선 실패 뒤에 가려져 있던 다음 단계일 수도 있습니다. 같은 명령과 전체 종료 상태를 비교하고 원인을 확인하기 전에는 해결 개수와 품질 개선을 숫자로 단정하지 않습니다. 로그의 표시 제한도 함께 확인하세요.
빌드 기준선: Java 17과 Spring Framework 6.0#
Spring Boot 3.0 가이드는 Boot 3.0이 Java 17 이상을 요구하고 Java 8은 더 이상 지원하지 않으며, Spring Framework 6.0도 요구한다고 설명합니다(Spring Boot 3.0 전환 가이드). 빌드 파일에서 JDK 설정, 상위 BOM, 직접 고정한 Spring 버전을 먼저 확인하세요. 기준선을 만족하지 않으면 코드 변경을 시작하지 않고, 빌드 환경 변경을 별도 단위로 승인받습니다.
Jakarta 네임스페이스 전환 전에 확인할 것#
같은 가이드는 Boot 3.0이 Jakarta EE 10에 포함된 버전의 사양을 쓰도록 올렸다고 설명합니다(Spring Boot 3.0 전환 가이드). javax 이름을 일괄 치환하기 전에 서드파티 라이브러리의 Jakarta 버전을 먼저 확인하세요.
치환 범위는 모듈 목록으로 적고, 목록 밖 파일에 같은 이름이 나오면 바꾸지 않고 기록하세요. 치환 뒤 빌드 결과와 실행 테스트 결과를 따로 남깁니다.
다음에 읽을 것#
작은 단위로 기존 동작을 보존하는 방법은 레거시 리팩토링을 참고하세요.
관련#
편집 메모 (2026-11-02): 오류 분류의 적용 범위를 보충했습니다. 컴파일 실패는 JDK·빌드 도구·의존성과 import를 나눠 조사하고, 시작 후 실패는 변경된 설정·보안·데이터 접근을 따로 확인하세요. 컴파일 오류를 없애려고 모든 javax를 일괄 치환하지 않습니다. 기존 표는 Boot 3.0 가이드의 내용이며 현재 목표 버전의 지원 보증이 아닙니다. 실제 버전 매트릭스 화면·재빌드와 전후 테스트 로그는 아직 없습니다.