pile·
기타·모두싸인모두싸인·

비동기 메시지 가시화 파티가 1년 간 개발 문화를 바꾼 방법

모두싸인 팀이 서비스 간 비동기 메시지 흐름을 시각화하기 위해 AsyncAPI Spec을 도입하고, 관련 TypeScript 코드 생성 라이브러리 WAAX를 직접 개발한 과정을 다룬다. 기술 스펙 문서화가 개발 문화에 미친 영향까지 1년치 실험 결과를 정리했다.

핵심 포인트
  • AsyncAPI Spec을 활용해 마이크로서비스 간 비동기 메시지 계약을 문서화하고 시각화
  • 기존 AsyncAPI 코드젠 도구의 Date 타입 처리 한계를 해결하기 위해 자체 라이브러리 WAAX 직접 개발
  • npm 의존성 충돌 문제를 해결하며 2024년 7월 실서비스에 배포 완료
  • 스펙 기반 개발로 메시지 구조 변경 시 consumer/producer 양측의 타입 불일치를 빌드 타임에 감지
  • 1년간 운영 결과: 메시지 구조 논의가 코드 리뷰에서 스펙 문서 리뷰로 이동하는 문화적 변화
상세 정리
  • AsyncAPI는 REST용 OpenAPI와 대응하는 비동기 통신 표준 스펙 포맷으로, Kafka/SNS/SQS 등을 아우른다
  • 기존 오픈소스 코드젠 툴은 Date 타입을 string으로 flatten하는 문제가 있어 도메인 모델과 불일치 발생
  • WAAX(WAX AsyncAPI eXtension)는 AsyncAPI YAML 스펙에서 TypeScript 타입 정의를 생성하는 CLI 도구
  • npm peer dependency 버전 충돌은 --legacy-peer-deps 우회 대신 direct dependency 버전 고정으로 해결
  • 스펙 파일을 모노레포의 shared 패키지로 관리해 producer/consumer가 동일 계약을 참조
  • 2024년 7월 실서비스 배포 이후 비동기 메시지 관련 런타임 타입 오류가 유의미하게 감소
  • 메시지 스키마 변경 PR에 스펙 파일 diff가 포함되면서 리뷰어가 임팩트 범위를 즉시 파악 가능
  • 문서화 자동화가 '문서는 낡는다'는 인식을 개선해 비동기 인터페이스 설계 논의 질이 향상
왜 읽나마이크로서비스 간 비동기 메시지 계약을 코드 수준으로 강제하고 싶은 팀에 실전 구현 사례와 자체 코드젠 라이브러리 개발 경험을 제공한다.
모두싸인
모두싸인 블로그
원문은 여기서 이어서 읽을 수 있어요
원문 읽기
읽음 (0)

이 글과 비슷한

  1. 기타·NHN Cloud MeetupNHN Cloud·

    바겐세일은 끝난다

    NHN Cloud 개발자가 AI 에이전트 코딩 붐의 이면을 짚는다. OpenAI·Anthropic 등 AI 기업들이 막대한 적자를 감수하며 의도적으로 저가에 서비스를 제공하고 있으며, 이 바겐세일이 영원하지 않을 것이라 경고한다. ccusage 같은 도구로 실제 토큰 비용을 가시화해보면, 정액제로 사용하는 비용 대비 실비가 수십 배에 달한다는 불쾌한 진실이 드러난다.

    요약 이어보기
    #claude-code#developer-experience#llm+1
  2. 기타·stackoverflow-blogStack Overflow Blog·

    개발자가 도구에 애착을 갖는 이유: 도구는 신뢰를 인코딩한다

    개발자들이 특정 도구에 강한 애착을 형성하는 이유는 그 도구가 안정적인 워크플로우와 신뢰를 인코딩하기 때문이다. AI 코딩 에이전트의 급격한 보급에도 불구하고 개발자 신뢰도가 오히려 낮아진 역설적 현상을 분석하고, 도구 신뢰를 회복하기 위한 조건을 제시한다.

    요약 이어보기
    #developer-productivity#code-review#developer-experience+1
  3. 기타·포스타입포스타입·

    AI 코드 리뷰, 3번 갈아엎고 배운 것

    포스타입이 AI 코드 리뷰를 CodeRabbit, 자체 구축, 재도입 순으로 세 번 갈아엎으며 배운 것을 정리했다. 세 번 모두 도구는 달랐는데 불만의 모양은 같았다. 노이즈 지적이 나오고 사람마다 평가가 갈렸다. 결론은 문제가 도구가 아니라 AI 리뷰에 무엇을 기대할지에 대한 합의의 부재였다는 것이다.

    요약 이어보기
    #github-actions#code-review#claude-code+2