포스트

야놀자 「RESTful API validation 자동화 하기」 리뷰 — 인터페이스 하나에서 검증·문서·타입을 뽑는 이유, 그리고 자동화가 없으면 누락이 필연이라는 문장

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

엔지니어링 요약

Problem

입력 검증은 촘촘하면 개발 비용이 오르고 느슨하면 장애가 난다. 야놀자클라우드 키오스크 서버팀은 TypeScript 인터페이스에 주석을 달아 JSON Schema·Swagger·TypeDoc을 한 번에 생성해 그 트레이드오프를 없애려 했다. 결제 프로젝트에서 나는 같은 문제를 다른 도구로 만났다.

Decision

원문의 흐름(인터페이스 → JSON Schema → ajv 검증 + fastify-swagger 문서)과 원문 스스로 적은 제약 넷을 옮기고, parity-pay의 OpenAPI 스냅샷·생성 타입 드리프트 검사, 결함 L(취소 UNKNOWN이 HTTP 계약에서 빠짐), ArchUnit 규칙을 빌드에 넣은 경험과 대조했다.

Result

'검증과 문서화가 자동화되지 않으면 누락은 필연이며 인력으로 막기 어렵다'는 원문의 인용이 결함 L의 정확한 설명이었다. 서비스는 UNKNOWN을 보존했는데 HTTP 계약에는 그 상태가 없었고, 그것을 잡은 것은 리뷰가 아니라 실제 연결이었다. 원문의 방식(단일 원천에서 계약과 검증을 생성)이 그 결함을 미리 막았을 것이다. 다만 원문의 네 번째 제약(스키마로는 비즈니스 규칙을 못 적는다)이 결제 도메인에서는 검증의 절반이라는 것이 갈리는 곳이다.

원문: RESTful API validation 자동화 하기 — 야놀자클라우드 Tech Blog, 이병준(키오스크 서버팀), 2022-01-11

야놀자의 현재 기술 블로그는 야놀자클라우드 Medium이고, 옛 주소 techblog.yanolja.com은 NOL 메인으로 리다이렉트된다. 그 Medium에서 백엔드 글을 고르면 이것이다. 2022년 글이고 TypeScript·fastify 스택이라 내 스택(Java·Spring)과 다르지만, 다루는 문제는 스택과 무관하다. 계약을 한 곳에 적고 검증과 문서를 거기서 뽑을 수 있는가.

원문이 말하는 것

RESTful API에서 입력 검증은 필수인데, 치밀하게 하면 개발 비용이 오르고 느슨하게 하면 검증되지 않은 곳에서 장애가 난다. 저자는 그 트레이드오프를 자동화로 없애려 한다.

방법은 TypeScript 인터페이스를 단일 원천으로 두는 것이다. Request 인터페이스에 JSDoc 태그로 최솟값·최댓값·설명을 적고, ts-json-schema-generator로 JSON Schema를 뽑는다. 그 스키마를 fastify의 route에 등록하면 내장 ajv가 요청을 검증하고, fastify-swagger 플러그인이 같은 스키마로 Swagger 문서를 만들며, 풍부해진 주석 덕에 TypeDoc 문서 품질도 오른다. 인터페이스 하나에서 검증·API 문서·코드 문서 셋이 나온다. 배포 시 Jenkins가 생성된 문서를 S3에 올려 항상 최신이다.

원문이 스스로 적은 제약이 넷이다. 도구들이 서로를 위해 만들어진 것이 아니라 연결 고리가 취약하고(definition 처리 같은 것은 시행착오 없이는 모른다), JSON Schema가 아직 draft이고 ajv 버전 간 차이가 크며, 변환기가 mapped access 타입을 못 다루고, 스키마는 스키마라서 검증 코드를 넣을 수 없다(방문객 나이 100세 이하 같은 커스텀 규칙은 Joi·Yup은 되지만 JSON Schema는 안 된다).

결론은 그래도 장점이 크다는 것이고, 근거는 인용 하나다. 검증과 문서화가 자동화돼 있지 않으면 누락은 필연이며 인력으로 막기 어렵다.

같은 곳: 계약이 두 곳에 있으면 어긋난다

이 인용이 parity-pay 4편 결함 L의 정확한 설명이다. 서비스 계층은 취소를 UNKNOWN으로 보존했고 테스트도 그것을 확인했다. 그런데 HTTP 계약에는 그 상태가 없었다. 취소 API가 201로 응답했고 조회 API가 없어서 화면이 “취소됨”으로 보여줬다. 서비스 계층의 상태 모델과 HTTP 계약이 두 곳에 따로 있었고, 하나를 고칠 때 다른 하나를 사람이 기억해야 했다. 기억하지 못했다. 잡은 것은 리뷰가 아니라 프론트엔드를 실제 백엔드에 연결한 날이었다.

원문의 방식이 그것을 막는다. 인터페이스가 하나면 UNKNOWN을 상태 enum에 추가하는 순간 검증 스키마와 Swagger 문서가 같이 바뀌고, 문서를 보는 프론트엔드가 그 상태를 처리하지 않으면 타입 검사에서 걸린다. parity-pay는 결함 L 이후 OpenAPI 스냅샷과 프론트엔드 생성 타입의 드리프트를 CI에서 검사하게 했다. 원문이 2022년에 하고 있던 것을 결함을 겪고 나서 붙인 셈이다.

ArchUnit 글의 논리도 같다. 아키텍처 규칙을 문서에 적으면 위반이 480건 쌓이고, 빌드에 넣으면 신규 코드에서는 0건이다. 규칙이 사람의 기억에 있으면 어긋나고, 도구에 있으면 어긋나지 않는다. 원문은 그것을 API 계약에 적용했다.

갈리는 곳: 스키마가 못 적는 것이 결제에서는 절반이다

원문의 네 번째 제약이 내 도메인에서는 제약이 아니라 본체다. 결제 API의 검증은 “금액이 양수인가”(스키마)보다 “이 멱등 키로 이미 다른 금액의 요청이 왔는가”, “이 지갑의 가용 잔액이 금액 이상인가”, “이 결제가 취소 가능한 상태인가”(비즈니스 규칙)가 더 많다. 7편에서 Money는 스키마 수준(양수, 같은 통화)이고 Journal은 규칙 수준(차변=대변)이며 DB 트리거는 그 규칙을 저장소가 다시 검사하는 층이었다. 스키마 검증은 세 층 중 첫 층만 자동화한다.

그래서 원문의 방식을 결제에 가져오면 “스키마로 되는 것은 전부 스키마로, 나머지는 도메인 객체의 생성자로”가 된다. 원문이 Joi·Yup을 언급하며 커스텀 규칙의 자리를 남겨 둔 것이 그 경계다. 자동화의 범위를 정직하게 그은 것이 이 글의 좋은 점이고, 그 경계 바깥이 결제에서는 넓다는 것이 다른 점이다.

원문이 답하지 않는 것

  • 생성된 스키마가 틀렸을 때. 변환기의 버그(mapped access)를 원문이 언급했는데, 그 경우 검증이 조용히 느슨해진다. 스키마가 인터페이스와 일치하는지를 검사하는 테스트가 있는지는 없다. 계약을 한 곳에 뒀는데 그 한 곳에서 파생되는 과정이 틀리면 결과는 두 곳에 둔 것과 같다.
  • 수치. 자동화 전후로 검증 누락으로 인한 장애가 몇 건에서 몇 건이 됐는지, 문서와 구현의 불일치가 얼마나 줄었는지는 없다. “정말 편리하다”까지다.
  • Response 검증. Request 검증과 문서화를 다루고 Response는 문서화만 언급한다. fastify는 response 스키마로 응답도 검증할 수 있는데, 결함 L 같은 문제(서버가 계약에 없는 상태를 돌려줌)는 Response 쪽 검증이 잡는다.

가져갈 것

  • 계약은 한 곳에 적고 검증·문서·타입을 거기서 생성한다. 두 곳에 있으면 사람이 기억해야 하고, 기억은 실패한다.
  • 자동화의 범위를 정직하게 긋는다. 스키마가 적을 수 있는 것과 없는 것을 나누고, 없는 것은 도메인 객체가 맡는다.
  • 파생 과정 자체를 검증한다. 생성된 스키마가 원천과 같은지 검사하지 않으면 자동화가 조용히 무력해진다.
  • Response도 계약이다. 서버가 계약에 없는 상태를 돌려주는 것을 잡는 층이 있어야 한다.
시리즈

빅테크 기술 블로그 리뷰

31편 중 17편

이전 시리즈 글 네이버 D2 「스마트스토어센터 Oracle에서 MySQL로의 무중단 전환기」 리뷰 — 두 DB에 동시에 쓰되 한쪽 실패는 무시하고, 읽기 트래픽을 복제해 성능을 재고, 6개월간 불일치를 0으로 만든 과정 다음 시리즈 글 카카오 「MySQL Json 데이터 타입의 저장 구조와 성능 비교」 리뷰 — 통째로 넣고 통째로 꺼내면 TEXT, 키로 파고들면 JSON
  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, Yanolja
Tech Blog Review Yanolja API Validation JSON Schema OpenAPI Contract TypeScript ArchUnit
이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.

댓글

아직 댓글이 없습니다