모두싸인 팀이 서비스 간 비동기 메시지 흐름을 시각화하기 위해 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가 포함되면서 리뷰어가 임팩트 범위를 즉시 파악 가능
- 문서화 자동화가 '문서는 낡는다'는 인식을 개선해 비동기 인터페이스 설계 논의 질이 향상
왜 읽나마이크로서비스 간 비동기 메시지 계약을 코드 수준으로 강제하고 싶은 팀에 실전 구현 사례와 자체 코드젠 라이브러리 개발 경험을 제공한다.