포스트

카카오 「추가배포 없이 API의 case 통일시키기」 리뷰 — 받는 쪽이 자기 케이스에 맞춰 알아서 읽게 하면 배포 순서가 사라진다

Tech Blog Review
게시
By August
좋아요 조회 8 분 읽는 시간

원문: 추가배포 없이 API의 case 통일시키기 — kakao tech, 루이스(마이구독 백엔드), 2024-11-19

한 줄 요약

서버마다 camelCase와 snake_case가 섞인 DTO 900개를 camelCase로 통일해야 했다. 무중단으로 하려면 v2 API 추가 → 호출자 전환 → v1 제거의 배포 순서를 서버마다 지켜야 하는데, 서로 참조하는 서버가 많으면 순서를 맞추기 어려워 결국 점검을 걸게 된다. 케이스 변경 때문에 점검을 여러 번 하는 것은 배보다 배꼽이다. 해법은 받는 쪽(Callee)이 보내는 쪽의 케이스와 무관하게 자기 DTO에 선언된 케이스로 알아서 변환해 읽는 모듈을 모든 서버에 먼저 붙이는 것이다. 그러면 어느 서버부터 바꿔도 되고, 다 바꾼 뒤 모듈을 떼면 된다.

배경: 케이스가 섞이는 이유와 그 비용

“Admin은 camel”, “외부 연동처는 snake로 달라”처럼 요구가 다르다 보니 코드에 케이스가 섞인다. 팀은 camelCase로 합의하고 점진적으로 바꾸기로 했는데, 어느 정도 진행되자 문제가 나왔다.

  • 게이트웨이(camel)가 받은 DTO를 비즈니스 서버(snake)로 그대로 넘기려면 같은 값의 DTO가 두 벌 필요하고, 필드가 바뀌면 둘 다 고쳐야 한다.
  • DTO 안에 다른 DTO가 들어갈 때 바깥은 camel, 안쪽은 snake면 받는 쪽이 어느 케이스로 파싱할지 몰라 오류가 난다.
  • Jackson이 없는 필드를 null로 채우는 설정이라, 필드명을 못 알아봐도 컴파일 때도 파싱 때도 안 잡히고 그 필드를 쓰는 순간에야 터진다.

MSA에서는 서버 간 통신이 REST라 DTO가 많아 더 자주 생기고, 무중단 서비스에서는 DTO를 바꾸는 배포 자체가 어렵다.

핵심 아이디어

Caller가 무엇을 보내든 Callee가 파싱 직전에 자기 타깃 클래스의 케이스로 바꿔서 읽는다. 모든 서버에 이 모듈을 붙인 뒤 서버별로 케이스를 일원화하고, 끝나면 모듈을 제거한다. 배포 순서 의존이 사라진다.

자세히 보기

Request: RequestBodyAdvice

Filter는 타깃 클래스를 알 수 없고, Interceptor는 원본 body를 바꾸기 어렵다. RequestBodyAdvice는 @RequestBody에 값이 매핑되기 직전에 동작하고 beforeBodyRead에서 타깃 클래스를 알 수 있다. 타깃이 snake인지는 팀 규약대로 붙어 있던 @JsonNamingStrategy·@JsonProperty의 존재를 리플렉션으로 확인해 판단한다.

제네릭이 까다로웠다. 기준은 가장 안쪽 클래스의 케이스다. 안쪽 클래스들의 케이스가 다르면 오류 상황으로 보고 먼저 전환했다. 타입 인자가 둘 이상인 제네릭은 재귀 탐색이 너무 복잡해져 제외했고(Map 말고는 거의 없음), Map은 키가 실제 변수명인 경우가 있어 제외했다(팀이 원래 REST 응답에 Map을 지양해서 문제 없었다).

Response: Custom Deserializer

ResponseBodyAdvice는 받은 데이터가 아니라 내보내기 직전에 동작하므로 쓸 수 없다. 대신 팀의 응답이 항상 ApiResponse 래퍼로 감싸져 있다는 점을 이용해 Jackson JsonDeserializer를 그 클래스에 붙였다. 래퍼가 제네릭이라 ContextualDeserializer도 구현해야 한다. createContextual에서 제네릭 안의 타깃 타입을 알아내 멤버 변수로 들고 있다가 deserialize에서 Request와 같은 변환 로직을 적용한다.

여기서 잡은 버그가 이 글의 핵심 교훈이다. Jackson은 캐시되지 않은 deserializer를 createContextual로 가져오는데, 여기서 새 인스턴스를 반환하지 않으면 여러 요청이 최초 인스턴스 하나를 공유한다. 멤버 변수인 타깃 타입이 요청들 사이에 섞여 파싱 오류가 난다. 로컬 단건 테스트에서는 멀쩡했고, 스테이지에서 여러 요청을 동시에 보내다 발견해 배포 전에 고쳤다.

모듈을 붙이고 케이스를 바꾼 뒤 일정 기간 의도치 않은 케이스가 들어오는지 확인하고, 이상이 없음을 확인한 뒤 900개 DTO를 서버 중단 없이 바꿨다.

왜 가능했나

원문이 마지막에 짚는다. 변수 네이밍 규칙, ApiResponse 래퍼 사용 규칙, snake 표시에 쓰는 애너테이션 규칙처럼 팀에 공유된 규약이 있었기에 “애너테이션을 보고 케이스를 판단”, “래퍼에 deserializer를 붙임”이 가능했다. 규약이 없었다면 모듈이 무엇을 기준으로 변환할지 정할 수 없었을 것이다.

읽고 남는 질문

  • 변환 모듈은 파싱 직전에 JSON 트리를 한 번 더 다시 쓴다. 900개 DTO가 오가는 트래픽에서 지연·CPU 부담이 얼마나 됐는지 수치가 없다. 과도기용이라 감수했겠지만 궁금하다.
  • Map 제외, 다중 타입 제네릭 제외는 타협이다. 그 경우가 실제로 몇 건 있었고 어떻게 처리했는지가 있으면 재현에 도움이 된다.
  • 최종적으로 모듈을 제거했는지, 아니면 외부 연동처(snake 요구)를 위해 남겨 두었는지가 없다.

한 줄로 가져가기

호환성 문제의 배포 순서 지옥은 “보내는 쪽을 맞추는” 대신 “받는 쪽이 관대하게 읽게” 만들면 풀린다. 단, 그 관대함이 무엇을 기준으로 삼을지는 팀 규약이 먼저 정해 줘야 한다.

시리즈

빅테크 기술 블로그 리뷰

31편 중 2편

이전 시리즈 글 카카오 「실시간 메시징 시스템 개발기」(3편) 리뷰 — Redis에 몰린 부하를 서버로 옮기고, 그 서버를 pprof로 세 번 깎은 이야기 다음 시리즈 글 카카오 「MySQL DATETIME, TIMESTAMP 데이터 타입에 대한 분석」 리뷰 — 바이트 단위 저장 구조부터 아직 안 고쳐진 Y2K38까지
  1. 1 카카오 「실시간 메시징 시스템 개발기」(3편) 리뷰 — Redis에 몰린 부하를 서버로 옮기고, 그 서버를 pprof로 세 번 깎은 이야기
  2. 2 카카오 「추가배포 없이 API의 case 통일시키기」 리뷰 — 받는 쪽이 자기 케이스에 맞춰 알아서 읽게 하면 배포 순서가 사라진다
  3. 3 카카오 「MySQL DATETIME, TIMESTAMP 데이터 타입에 대한 분석」 리뷰 — 바이트 단위 저장 구조부터 아직 안 고쳐진 Y2K38까지
  4. 4 네이버 D2 「6개월 만에 연간 수십조를 처리하는 DB CDC 복제 도구 무중단/무장애 교체하기」 리뷰 — 복제·검증·복구를 셋으로 나누고, 옛 도구와 새 도구를 서로 모르게 같이 돌린 전환
  5. 5 카카오 「MySQL ALTER DDL 수행 방식에 대한 이해」 리뷰 — Copy·In-Place·Instant는 '무엇을 복사하느냐'보다 '언제 Exclusive 메타 락을 잡느냐'로 구분된다
  6. 6 카카오 「MySQL Orchestrator 기반의 새로운 HA 표준 개발기」 리뷰 — 10년 멈춘 Perl 도구를 떠나 Raft 클러스터로, 그리고 slave_net_timeout 한 줄
  7. 7 카카오 「MySQL Ver. 8.0 New Feature: Instant DDL Algorithm에 대한 이해」 리뷰 — 컬럼을 0.01초에 추가하는 대가는 '읽을 때마다 버전을 대조하는 것'이다
  8. 8 네이버 D2 「CDC 복제 이후 오라클이 느려졌다? child cursor 폭증이 만든 예상치 못한 문제」 리뷰 — 같은 SQL인데 바인딩 타입이 다르면 Oracle은 다른 쿼리로 본다
  9. 9 카카오 「MySQL InnoDB Log에 대한 이해 - (1)」 리뷰 — 트랜잭션 하나가 어떻게 MTR 여러 개로 쪼개져 Redo Log Buffer에 들어가는가
  10. 10 카카오 「PostgreSQL to ES: Kafka Connect CDC 파이프라인」 1·2편 리뷰 — 변경이 없어서 디스크가 차고, LSN이 사라져서 스냅샷을 다시 짜야 했던 CDC의 실제 운영 비용
  11. 11 LINE 「기획서 없이 내재화하기: 검증 로직으로 동일함을 증명하다」 리뷰 — 블랙박스는 입력과 출력만 정의하면 통계로 같음을 증명할 수 있다
  12. 12 뱅크샐러드 「게임을 만들 때 데이터 정합성을 유지하는 법 (feat. 낙관적 락)」 리뷰 — 같은 WHERE version 조건인데, 충돌한 요청을 어떻게 하는가에서 갈리는 두 설계
  13. 13 우아한형제들 「Spring Batch와 Querydsl」 리뷰 — offset을 버린 Reader가 21분을 4분으로 만든 이유, 그리고 그 Reader가 답하지 않는 두 가지
  14. 14 네이버 D2 「테스트는 어떻게 좋은 코드를 만드는가(feat. 험블 객체 패턴)」 리뷰 — 목이 많아지는 것은 테스트의 문제가 아니라 설계의 신호
  15. 15 당근 「QR을 찍으면 무슨 일이 벌어질까? 당근페이 현장 결제의 모든 것」 리뷰 — 카드망을 빌려 7주 만에 낸 결제와, 그 글이 다루지 않은 승인 응답이 사라지는 순간
  16. 16 네이버 D2 「스마트스토어센터 Oracle에서 MySQL로의 무중단 전환기」 리뷰 — 두 DB에 동시에 쓰되 한쪽 실패는 무시하고, 읽기 트래픽을 복제해 성능을 재고, 6개월간 불일치를 0으로 만든 과정
  17. 17 야놀자 「RESTful API validation 자동화 하기」 리뷰 — 인터페이스 하나에서 검증·문서·타입을 뽑는 이유, 그리고 자동화가 없으면 누락이 필연이라는 문장
  18. 18 카카오 「MySQL Json 데이터 타입의 저장 구조와 성능 비교」 리뷰 — 통째로 넣고 통째로 꺼내면 TEXT, 키로 파고들면 JSON
  19. 19 LINE 「도메인에 의존하지 않는 채팅 플랫폼은 어떻게 만들었을까?」 리뷰 — 사용자를 모르는 채팅 플랫폼, 웹으로 만든 클라이언트, SOFT STOP으로 갈아 끼우는 챗봇 시나리오
  20. 20 카카오페이 「MSA 환경에서 네트워크 예외를 잘 다루는 방법」 리뷰 — Unknown을 타입으로 만든 글과, Unknown을 상태로 저장한 프로젝트가 갈리는 지점
  21. 21 카카오 「메시징 서버의 스트레스 테스트 노하우와 AI가 덜어 준 부분」 리뷰 — 지표를 네 층으로 내려가 읽는 법, 그리고 LLM에게 맡긴 것과 맡기지 못한 것
  22. 22 네이버 D2 「일 3,000만 건의 네이버페이 주문 메시지를 처리하는 Kafka 시스템의 무중단 전환 사례」 리뷰 — 두 벌로 발행해 대조한 검증기와, 발행 제어 키를 파티션 키와 같게 둔 이유
  23. 23 카카오 「잃어버린 리포트를 찾아서: 카카오 메시징 시스템의 경쟁 조건 문제와 안티 패턴 제거 과정」 리뷰 — 벤더가 8ms 만에 리포트를 보냈고, 우리는 101ms짜리 트랜잭션 안에 있었다
  24. 24 컬리 「컬리의 입고 시스템이 외부 인입 데이터를 안전하게 동기화하는 방법」 리뷰 — 145회 재시도가 맞는 도메인과 재시도를 금지한 도메인, 그리고 발행부와 수신부가 각자 책임지는 구조
  25. 25 네이버 D2 「@RequestCache: HTTP 요청 범위 캐싱을 위한 커스텀 애너테이션 개발기」 리뷰 — 캐시의 수명을 '요청 하나'로 맞추면 TTL 고민이 사라진다, 그리고 @RequestScope가 안 되는 이유
  26. 26 무신사 「Kafka와 Strimzi를 이용하여 6개의 도메인을 하나의 도메인으로 합쳐보았습니다」 리뷰 — 배치 없이 CDC와 Kafka Streams로 옮긴 결정, 그리고 통합 모델이 원본과 같다는 것을 누가 확인하는가
  27. 27 쿠팡 「대용량 트래픽 처리를 위한 쿠팡의 백엔드 전략」 리뷰 — 캐시 두 겹과 '분 단위 99.99% 동일'이라는 문장, 그리고 그 0.01%를 누가 어떻게 세는가
  28. 28 LINE 「LINE에서 Kafka를 사용하는 방법 - 1편」 리뷰 — 초당 4GB 클러스터가 바이트가 아니라 요청 수를 제한하는 이유, 그리고 2,000틱짜리 파이프라인에서 같은 것을 본 기록
  29. 29 카카오 「MySQL 인증 플러그인 caching_sha2_password에 대한 이해」 리뷰 — 비밀번호 해시가 바뀌는 것보다 '평문이 서버까지 가야 한다'는 점이 전환의 진짜 비용
  30. 30 LINE 「초당 100만 건, LINE 앱에 Apache Kafka 종단 간 암호화 적용기」 리뷰 — 인터셉터와 시리얼라이저만으로 브로커에 평문을 남기지 않는 법
  31. 31 카카오뱅크 「하루 N억 건의 알림 시스템 구축기 (1)」 리뷰 — P99의 80%가 대기였다는 진단, Age 기반 Work-Stealing, 그리고 큐를 나누는 순간 순서를 잃는 문제
TechBlog, Kakao
Tech Blog Review Kakao Spring Jackson DTO MSA Zero Downtime API Design
이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.

댓글

아직 댓글이 없습니다