“글을 끝내기 전에, 잊고 있던 12번째 PR이 모였습니다. 걸린 시간은 2~3시간.” 오이시스(Oisix)의 공개 기사에서 가장 인상 깊었던 문장입니다.
전자상거래 사이트 ‘Oisix’의 3세대 백엔드는 마이크로서비스 11개(API 8, BFF 2, API 테스트 러너 1)로 구성되어 있습니다. 팀은 2026년 봄에 이들을 Spring Boot 3 계열에서 4 계열로 업그레이드했으며, 동시에 후발 애플리케이션들로 고정되어 있던 표준 구성을 초기 애플리케이션들도 갖추도록 재정비했습니다. 공식 엔지니어 블로그(2026년 8월 17일)에 그 절차와 실측값이 정리되어 있습니다.
- 대상: 11개 애플리케이션 (나중에 누락된 1개를 추가하여 총 12개)
- 마이그레이션: Spring Boot 3 계열 → 4 계열. 아울러 Gradle 8 계열 → 9 계열, Jackson 3, OpenAPI Generator, 테스트 라이브러리 업데이트 등 총 14개 항목을 진행했습니다.
- Java 버전: 이번에는 21로 유지 (Java 25 대응은 다음 과제로 Issue화 완료)
- 기간: 2026년 3月中旬 ~ 6月下旬
- 본 서비스 출시: 3회 (6월 3일, 17일, 22일)
- 병합된 PR: 62개 (Renovate를 사용한 Gradle 9 업데이트나 같은 시기의 다른 대응은 제외)
- 변경 코드 라인 수: +71,773 / −52,732 (리포지토리 간 차이는 최소 +287/−107, 최대 +32,858/−30,349)
- 테스트 마이그레이션: Spock → JUnit 5. 많은 경우 리포지토리당 100클래스, 600케이스를 초과했습니다.
- 12번째 항목: 축적된 지식을 전달하여 모든 대응 PR을 완성하는 데 2~3시간이 소요되었습니다.
구성(Architecture)이 단순한 앱 하나를 선택하고 Claude Code와 진행 방식을 확정합니다. 의존성을 어디까지 올릴지, 어떤 순서로 확인할지, 막히는 부분은 무엇인지 등 모든 것을 Notion의 지식 기록으로 남깁니다. 두 번째 앱부터는 “공통 변경 사항은 유사하게 적용했고, 다른 부분만 다음과 같다”라는 차이점만을 생각하면 됩니다.
다음 앱을 착수할 때, 먼저 지식 기록(Knowledge Memo)을 Claude Code에 전달합니다. 같은 조사를 반복할 필요가 없어지고, 나중 앱일수록 빠르고 정확해졌다고 합니다. 사람이 미래를 위해 남긴 문서가 그대로 에이전트의 컨텍스트가 되었다는 점이 실무적입니다.
Gradle 9, Spring Boot 4, OpenAPI의 Submodule화, 단일 프로젝트화, 테스트 마이그레이션은 각각 독립적인 PR로 분리했습니다. 구성 변경과 버전 업그레이드를 같은 PR에 섞으면 문제 분리와 리뷰가 어렵기 때문입니다.
인간 측면의 설계 판단도 여기에 나타납니다. 초기 앱은 OpenAPI 생성 코드를 사내 Maven 리포지토리에서 참조했지만, 해당 라이브러리가 Spring Framework 7에 미지원 상태였습니다. 재게시(republish)하여 계속 따라가기보다는, 후발 표준 방식인 “Spec을 Submodule로 가져와 빌드 시 리포지토리 내에서 생성하는” 구성으로 먼저 전환한 다음, Boot 4로 올렸습니다.
Spock에서 JUnit 5로의 마이그레이션은 많은 경우 리포지토리당 100클래스, 600케이스를 넘었습니다. 라인 단위의 수작업 리뷰는 현실적이지 않습니다. 등가 변환(equivalent conversion)임을 다음 기계 검사에서 보여주고 PR 본문에 명시했습니다.
- 테스트 케이스 수가 바뀌지 않음
- JaCoCo 커버리지가 바뀌지 않음
- 실제 코드(
src/main/)에 변경이 없음 - 흔히 발생하는 누락(예: Spock의 result == expected를 그대로 Java로 가져오면 아무것도 검증하지 않는 테스트가 됨)을 grep하여 0건.
숫자가 일치하면 등가로 간주하고 OK, 차이가 있으면 원인과 견해의 타당성으로 사람이 판단합니다. — 이 방침을 사전에 팀에서 합의했으며, 판단 기준도 지식 기록에 남겼습니다. “인간의 리뷰를 생략하는 것이 아니라, 인간이 판단할 수 있는 형태로 정돈한다”는 말이 이 사례의 핵심입니다.
동일성의 주축은 API 테스트입니다. master(Boot 3)를 배포하여 GREEN 상태로 만들고, develop(Boot 4)에 동일한 테스트를 적용하여 GREEN 상태로 만듭니다. 두 가지 모두 통과하면, 어설션(assertion)의 정밀도 범위 내에서 동작이 동일하다고 간주합니다. 마이그레이션을 위한 새로운 테스트를 작성하는 대신, 같은 테스트를 양쪽에 적용하기 위해 먼저 API 테스트가 없는 앱에 테스트 케이스를 추가했습니다.
수동 결합 테스트는 화면 조작의 정상 패턴으로만 한정했습니다. 이상 징후까지 수작업으로 돌리는 비용과 이미 API 테스트가 보장하고 있는 범위를 고려한 판단입니다.
11개를 일괄 출시하지 않고, 관련성이 깊은 기능 단위로 3 그룹으로 나누어 위험도가 낮은 그룹부터 배포했습니다. 서비스 간 통신은 HTTP API를 사용하고, 계약(Contract)은 OpenAPI Spec으로 고정되어 있기 때문에, 실제 운영 환경에서 Boot 3과 4가 혼재하는 기간을 허용할 수 있었다고 설명합니다.
Spring Boot 4는 Jackson 3 기반입니다. 패키지는 com.fasterxml.jackson에서 tools.jackson으로 이동하지만, 어노테이션(annotations)만은 com.fasterxml.jackson.annotation 그대로 남아 있습니다. ObjectMapper는 불변(immutable)인 JsonMapper가 되었고, Bean을 직접 정의했던 부분은 JsonMapperBuilderCustomizer로 변경했습니다.
실질적인 문제가 컸던 것은 점진적 의존성(transitive dependency)이었습니다. OpenAPI 생성 코드가 사용하는 오래된 jackson-databind-nullable은 Jackson 2 전용이라서 모듈이 작동하지 않아, JsonNullable이 {"present": true}와 같은 내부 구조 그대로 직렬화되었습니다. 컴파일과 구동 모두 통하기 때문에 테스트를 실행해 보고 나서야 발견할 수 있었습니다. 이러한 난관(함정)을 첫 번째 애플리케이션의 기록에 남겼기 때문에, 두 번째부터는 Claude Code가 처음부터 이를 회피할 수 있었다고 합니다.
- 첫 번째 앱에서 진행 방식과 난관을 문서로 남기고, 두 번째 앱부터는 문서를 AI에게 전달하여 차이점(diff)만 작업한다.
- 구성 변경 및 버전 업그레이드, 테스트 코드 수정은 PR(Pull Request)를 분리한다.
- 동등 변환 검토는 수행 여부가 아니라, 건수/커버리지/grep 0건으로 판정한다.
- 완료는 '같은 API 테스트를 신구 환경에 적용하여 양쪽 모두 GREEN'으로 정의한다.
- 계약(OpenAPI 등)이 안정적이라면, 프레임워크 혼재 기간을 허용하여 단계적으로 출시할 수 있다.
메이저 버전 업그레이드는 불균형을 해소하는 기회가 되기도 합니다. 이 사례가 남긴 것은 올라간 11개의 애플리케이션 자체보다도, '문서화(기록)'와 '사람이 판단할 수 있는 검토 형태'라고 느낍니다.
출처