[Spring Cloud Gateway][업그레이드] property smoke test와 classpath diff를 끝낸 뒤 route 정의 소스와 transitive dependency mismatch를 어떤 순서로 다시 기록하나

IT 리서치 노트

[Spring Cloud Gateway][업그레이드] property smoke test와 classpath diff를 끝낸 뒤 route 정의 소스와 transitive dependency mismatch를 어떤 순서로 다시 기록하나

Spring Cloud Gateway 업그레이드에서는 verifier와 BOM 정렬을 끝냈는데도 route branch만 깨지는 순간이 온다. 2026년 8월 9일 기준 Spring 공식 문서를 다시 보면 compatibility verification, externalized configuration, Gateway route predicate와 configuration surface는 서로 다른 층이다. 이 글은 property smoke test와 classpath diff를 끝낸 뒤 route 정의 소스와 transitive dependency mismatch를 어떤 순서로 다시 기록하는 편이 빠른지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 property smoke test와 classpath diff를 끝냈다면 다음 질문은 '어느 route 정의 소스가 실패했는가'와 '어느 transitive dependency가 runtime 조합을 흔들었는가'를 분리하는 것이다. route source mismatch는 PropertySource와 configuration surface를 먼저 적고, transitive mismatch는 dependency tree와 starter 조합을 먼저 적는 편이 빠르다. 이때 어떤 메뉴를 열고, 어떤 필드를 확인하고, 어떤 결과 로그를 저장할지까지 같이 적어야 다음 실행이 짧다.

즉 같은 Gateway 실패라도 route 값이 어디서 왔는지의 문제와 classpath가 어떻게 달라졌는지의 문제는 다른 runbook이어야 한다. 앞단 분기는 property smoke test와 classpath diff 글이 다뤘고, 이번 글은 그 뒤에 남는 더 좁은 기록 단위를 정리한다.

2. 어디서 실제로 막히는가

실무에서 흔한 문제는 세 가지다. 첫째, route locator smoke test가 깨졌는데도 dependency tree만 다시 본다. 둘째, 반대로 classpath drift로 전체 Gateway bean 조합이 흔들리는데 PropertySource만 의심한다. 셋째, YAML, 환경 변수, Config Server, Java DSL, discovery locator 중 어떤 route source에서 값이 왔는지 기록하지 않는다.

Spring Cloud 레퍼런스는 compatibility verification을 별도 단계로 두고, Spring Boot externalized configuration 문서는 PropertySource 계층을 설명한다. Spring Cloud Gateway 문서는 Route Predicate Factories와 configuration surface를 따로 정리한다. 이 셋을 같이 읽으면 verifier 이후 triage는 '버전이 맞느냐'보다 'route 정의는 어디서 왔고, runtime classpath는 어떻게 달라졌느냐'로 바뀌어야 한다.

• 증상: Gateway smoke test 실패가 route source 문제인지 classpath 문제인지 분리되지 않는다.
• 실패: dependency tree와 PropertySource를 같은 메모에 섞는다.
• 막힘: YAML/Java DSL/discovery locator 중 실제 route source를 적지 않는다.
• 누락: transitive dependency suspect와 failed test 이름을 함께 남기지 않는다.

질문	먼저 볼 곳	짧은 해석
어떤 route가 안 떴나	route 정의 소스와 PropertySource	설정 소스 mismatch branch를 연다
왜 bean 조합이 흔들리나	transitive dependency tree	classpath drift branch를 연다
profile마다 결과가 다른가	externalized config order	PropertySource order를 먼저 적는다

3. 실무에서 적용하는 순서

점검 순서는 다섯 단계가 가장 빠르다. 먼저 failed test 이름과 실패한 route 이름을 적는다. 두 번째로 route 정의가 YAML, 환경 변수, Config import, Java DSL, discovery locator 중 어디에서 왔는지 기록한다. 세 번째로 active profile과 PropertySource order를 저장한다. 네 번째로 dependency tree에서 suspect transitive dependency를 고르고 classpath diff artifact를 붙인다. 마지막으로 route source branch와 transitive branch를 별개 smoke test로 유지한다.

1. failed test와 route 이름을 먼저 적는다.
2. route 정의 소스를 한 줄로 명시한다.
3. PropertySource order와 active profile을 남긴다.
4. suspect transitive dependency와 classpath diff를 붙인다.
5. route source branch와 transitive branch를 별도 smoke test로 둔다.

실제 점검에서는 Gateway 설정 파일을 열고, Config import 경로를 확인하고, active profile 값을 입력하고, smoke test를 다시 실행하고, dependencyInsight 결과 파일을 저장한 뒤, failed route 이름과 오류 로그와 응답 상태를 같은 표에 붙이는 편이 좋다. 콘솔이나 CI 아티팩트 화면에서 어떤 파일과 어떤 경로를 봤는지까지 기록하면 route source branch와 classpath branch가 다시 섞이지 않는다.

이 순서를 지키면 재현이 짧아진다. route source mismatch라면 설정 소스와 profile 조합을 줄이는 쪽으로 가고, transitive dependency mismatch라면 starter 조합과 dependency tree를 줄이는 쪽으로 바로 갈 수 있기 때문이다. 특히 Gateway는 route predicate/filter 조합이 많은 만큼 test 이름과 route source를 빼먹지 않는 편이 중요하다.

route_branch:
failed_route=inventory-api
route_source=config-server
active_profile=prod
property_source_order=config-server,env,prod-yaml,base-yaml

classpath_branch:
suspect_transitive_dependency=reactor-netty-http
dependency_tree_artifact=build/reports/deps/gateway-tree.txt
manual_pin_present=false

이 메모가 있으면 다음 업그레이드에서도 verifier와 BOM 뒤에 무엇을 다시 적어야 하는지가 분명해진다. 같은 Gateway 실패라도 기록 단위를 더 좁게 가져갈 수 있다.

4. 공식 문서와 예시 화면으로 확인하기

첫 공식 화면은 Spring Cloud 레퍼런스의 compatibility verification 구간이다. verifier가 업그레이드 첫 관문이라는 점은 여전히 유효하지만, 그 다음 분기가 남아 있다는 점을 먼저 상기해야 한다.

Spring Cloud 레퍼런스는 compatibility verification을 별도 단계로 다룬다.

이미 verifier와 BOM을 통과한 상태라면 이제 질문은 달라진다. 왜 Gateway route branch만 깨지는지, 그리고 그 증거를 어떤 레이어로 다시 적을지로 넘어가야 한다.

두 번째 자료는 Spring Boot externalized configuration 문서다. route 정의가 깨질 때는 dependency graph뿐 아니라 어떤 PropertySource가 실제 값을 밀어 넣었는지도 같이 봐야 한다.

Spring Boot externalized configuration 문서는 PropertySource 계층을 통해 실제 설정 값 주입 순서를 설명한다.

즉 property smoke test가 통과하지 않을 때는 값 자체보다도 값이 어디에서 왔는지 기록해야 한다. YAML, profile, 환경 변수, Config Server 소스를 한 줄로 뭉개면 route 소스 분기가 늦어진다.

세 번째 공식 화면은 Spring Cloud Gateway 레퍼런스의 Route Predicate Factories 구간이다. 이 화면에서는 어떤 predicate와 filter 조합을 붙였는지 확인하고, 어떤 route 이름이 실패했는지 저장하고, 어떤 설정 경로가 실제로 적용됐는지 비교해야 한다.

Spring Cloud Gateway 문서는 route predicate 조합을 별도 reference 축으로 설명한다.

그래서 route 관련 실패는 단순 property binding 실패보다 한 단계 더 세밀하게 기록하는 편이 좋다. 어떤 route source에서 어떤 predicate 조합이 깨졌는지까지 남겨야 다음 diff가 짧다.

네 번째 자료는 Gateway configuration 문서다. route 정의 소스가 application config, Java DSL, discovery locator처럼 어디에 있는지가 실제 triage 순서를 바꾼다. 이 화면에서는 메뉴, 필드, 설정 경로, 결과 상태를 같이 확인하는 편이 좋다.

Spring Cloud Gateway configuration 문서는 Gateway route 설정이 어떤 configuration 표면에서 들어오는지 정리한다.

이 문서를 같이 보면 smoke test가 깨졌을 때 'route 값이 틀린가'보다 'route 정의 소스가 어디인가'를 먼저 적는 편이 낫다는 이유가 선명해진다.

운영에서는 property smoke test와 classpath diff를 끝낸 다음에야 더 좁은 표가 필요하다. route 소스 mismatch와 transitive dependency mismatch를 같은 실패로 두면 재현이 또 길어진다.

Gateway 업그레이드 뒤 route 정의 소스와 transitive dependency mismatch를 나누는 기록 표다.

이미 property smoke test와 classpath diff 글이 넓은 분기를 다뤘다면, 이번 표는 그 다음 단계로 route source와 transitive mismatch를 별개로 기록하는 후속편이다.

마지막 자료는 CI 메모 예시다. route source와 transitive mismatch를 따로 적는 구조만 있어도 다음 재현 시간이 많이 줄어든다.

Gateway 업그레이드 메모에서 route source와 transitive dependency drift를 분리해 남기는 예시다.

이 메모를 유지하면 'verifier는 통과했는데 Gateway만 깨진다'는 말이 훨씬 구체적인 runbook으로 바뀐다. 넓은 버전 정렬 앞단은 release train과 BOM 정렬 글과 이어 읽으면 된다.

5. 주의사항과 리스크

첫 번째 리스크는 route source mismatch와 transitive dependency mismatch를 같은 장애로 두는 것이다. 두 번째 리스크는 PropertySource order를 남기지 않아 profile에 따른 drift를 나중에야 발견하는 것이다. 세 번째 리스크는 failed route 이름을 적지 않아 integration test 실패를 다시 처음부터 파헤치는 것이다.

운영 전에 확인할 때는 최소한 failed test, route source, PropertySource order, suspect transitive dependency, dependency tree artifact를 같은 표에 두는 편이 좋다. 그래야 route branch와 classpath branch를 다음에도 빠르게 나눌 수 있다.

• route source 기록이 없으면 설정 drift를 좁히기 어렵다.
• transitive suspect 기록이 없으면 classpath diff가 다시 길어진다.
• Gateway smoke test는 failed route 이름까지 남겨야 재현이 짧다.

6. 결론

Spring Cloud Gateway 업그레이드에서 property smoke test와 classpath diff를 끝낸 뒤에는 route 정의 소스와 transitive dependency mismatch를 별개로 기록해야 한다. route source, PropertySource order, dependency tree artifact를 따로 남기면 Gateway branch triage가 훨씬 짧아진다.

만약 여기까지는 맞는데 discovery locator 결과만 환경마다 다르게 보인다면 후속으로 route source는 맞는데 discovery locator만 다를 때 유지할 smoke test 글까지 이어 보는 편이 좋다. 같은 Gateway 계열 장애라도 route branch와 locator branch를 분리해 두면 재현 시간이 더 짧아진다.

• route 정의 소스와 PropertySource order를 먼저 적는다.
• transitive dependency suspect는 classpath diff와 함께 남긴다.
• route branch와 classpath branch를 별도 smoke test로 유지한다.

7. 참고 링크

1. https://docs.spring.io/spring-cloud/docs/current/reference/htmlsingle/
2. https://docs.spring.io/spring-boot/reference/features/external-config.html
3. https://docs.spring.io/spring-cloud-gateway/reference/
4. https://docs.spring.io/spring-cloud-gateway/reference/spring-cloud-gateway-server-webflux/configuration.html