공통 라이브러리의 버전 관리 및 배포 방식 결정 - Genie-Uss/genieus GitHub Wiki
🧩 문제 상황 (Problem)
MSA 환경에서 공통 라이브러리(이벤트 처리, 로깅 등)를 여러 서비스에 적용하면서 다음과 같은 문제에 직면했습니다:
- 공통 로직을 각 서비스 내에서 복사/붙여넣기 방식으로 중복 작성함에 따라 코드 일관성 유지가 어려움
- 일부 서비스가 로컬 JAR 파일을 직접 의존하거나, Gradle 프로젝트에 포함된 모듈로만 관리되어 버전 충돌 및 변경 이력 추적이 어려움
- 신규 기능 또는 버그 수정 시, 모든 서비스에 동일하게 적용되었는지 확인할 수 있는 체계 부족
🎯 선택한 해결 방안 (Decision)
GitHub Packages를 활용한 내부 공통 라이브러리의 버전 관리 및 배포 체계 구축
- 모든 공통 기능을 별도 Maven 프로젝트로 분리하여 도메인 서비스와 완전히 독립된 모듈화 수행
- 공통 모듈을 GitHub Packages의 Private Maven Repository로 배포하여 버전 기반 참조 가능하도록 구성
- 팀 전체가 공통 모듈을
implementation("com.genieus-common-lib:1.2.3")방식으로 명시적 참조
⚙️ 적용 목표 (Objectives)
- ✅ 코드 중복 제거: 모든 서비스에서 동일한 로직을 하나의 공통 모듈로 사용
- ✅ 버전 명시적 관리: 배포된 기능 및 변경 이력 추적 가능 (
1.2.3,1.2.4-beta등) - ✅ 개발 편의성 향상: 신규 프로젝트에서 공통 기능을 바로 사용할 수 있도록 템플릿화
- ✅ 의도치 않은 변경 방지: 각 서비스는 명시된 버전을 사용할 뿐 내부 구현을 참조하지 않음
🧪 적용 결과 (Results)
- 공통 이벤트 처리, 로깅 AOP, 메시지 역직렬화 등 5개 이상의 도메인 서비스에서 동일한 방식으로 일관되게 적용
- 신규 기능 릴리즈 시 공통 라이브러리만 업데이트하고, 각 서비스는
버전만 변경하여 수용 - 팀 내 신규 개발자도 공통 라이브러리 구조를 통해 빠르게 온보딩 가능
- 공통 모듈 사용 중 문제가 발생할 경우,
해당 버전에서만 재현되는 버그를 구분할 수 있어 디버깅 효율성 증가
🔭 향후 개선 사항 (Next Steps)
- 🔄 Semantic Versioning(SemVer) 적용 강화를 통해 Major / Minor / Patch 릴리즈 정책을 명확히 정립
- 📦 GitHub Packages 외에도 Artifactory, AWS CodeArtifact 등의 대체 배포 채널 도입 검토 (트래픽, 보안 이슈 고려)
- 📋 공통 라이브러리 전용 CHANGELOG 및 문서 자동 생성 파이프라인 구성 → 릴리즈 시점에 릴리즈 노트 자동 배포
- 🧪 각 서비스에 적용된 공통 모듈의 버전과 주요 변경점을 한눈에 확인할 수 있는 공통 사용 현황 대시보드 구축