TL;DR — 외부 업로드 API가 같은 코드인데 어제는 되고 오늘은 전건 400이었다. 요청 본문을 불변 Map 리터럴로 만들었는데, 이 자료구조는 순회 순서가 JVM 기동마다 무작위로 정해진다. 서버가 특정 키 순서를 요구해서, 순서가 어긋난 기동에서만 실패했다.

배경

• 프로젝트/기능: DeployHub — 완성된 반입 아카이브를 문서 라이브러리에 올리는 업로드 단계
• 환경: Java 17, Spring Boot 3.5, 외부 문서 API

문제 (증상)

• 어떤 날은 업로드가 전부 성공한다
• 어떤 날은 9건이 전부 400으로 실패한다
• 그 사이 코드는 한 글자도 바뀜 게 없다. 재현이 안 되니 원인을 찾기 어렵다

원인 분석

• 서버가 요구하는 본문 규칙이 있었다 — 특정 키가 다른 키보다 앞에 와야 한다(실측: 순서를 바꾸면 200과 400으로 갈린다)
• 그런데 본문을 Map.of(...)로 만들었다. 이 구현은 내부 해시 분산에 JVM 기동마다 달라지는 난수를 섮는다
• 결과적으로 직렬화 순서가 재기동 뿽기가 된다. 배포할 때마다 주사위를 던진 셈
• "가끔 실패"가 아니라 기동 단위로 전석승 또는 전석패라는 점이 단서였다 — 요청별 랜덤이 아니라 프로세스별 랜덤이라는 뜻

해결

• 순서가 보장되는 본문 생성기로 교체해 키 순서를 고정했다
• 테스트는 객체 비교가 아니라 직렬화된 본문 문자열 자체를 고정했다 — 순서가 문제인데 객체로 비교하면 같다고 나와 잡지 못한다
• 문서 예시에 있는 일부 필드는 오히려 넣으면 400이 난다는 것도 실측으로 확인해 제외했다

결과

• 재기동과 무관하게 업로드가 일관되게 성공한다
• 순서 규칙이 깨지면 테스트가 먼저 알려준다