ADR-01: 코어 라이브러리의 독립 리포지토리화
| 날짜 | 작성자 | 영향 리포지토리 |
|---|---|---|
| 2024-12-17 | @KubrickCode | core |
Context
문제 정의
코어 라이브러리는 여러 서비스에서 사용해야 하는 공유 기능이다:
- 워커 서비스 (worker): 큐에서 분석 작업 처리
- API 서비스 (web): 동기 작업을 위한 직접 접근 필요 가능
- CLI 도구: 개발자가 로컬에서 실행 희망
- Docker 이미지: CI/CD 파이프라인에서 컨테이너화된 실행 필요
전략적 질문
코어 라이브러리를 서비스 내부에 포함시킬 것인가, 아니면 독립적이고 재사용 가능한 라이브러리로 분리할 것인가?
Decision
코어 라이브러리를 별도 리포지토리의 독립 Go 라이브러리로 분리한다.
코어는 Go 모듈로 게시되어 다음과 같이 사용 가능:
- 모든 Go 서비스에서 임포트 (
go get) - CLI 바이너리로 배포
- Docker 이미지로 패키징
Options Considered
Option A: 독립 라이브러리 (선택됨)
별도 리포지토리에서 재사용 가능한 Go 모듈로 코어 제공.
장점:
- 다중 배포 모드: 단일 코드베이스로 라이브러리, CLI, Docker 사용 사례 지원
- 독립적 릴리스 사이클: 코어 수정이 서비스 재배포를 요구하지 않음
- 오픈소스 가능: 커뮤니티가 코어를 사용하고 기여할 수 있음
- 명확한 API 계약: 코어와 소비자 간 명확한 경계 강제
- 생태계 가치: 플랫폼을 넘어 독립적 가치 제공
단점:
- 소비 서비스 간 버전 조율 필요
- API 안정성 유지 책임
- 별도 CI/CD 파이프라인 관리
Option B: 서비스 내부 모듈
코어 코드가 소비 서비스(예: worker) 내부에 위치.
장점:
- 초기 설정이 단순
- 크로스 리포지토리 조율 불필요
- 버전 관리 없이 빠른 이터레이션
단점:
- 코드 중복: 코어가 필요한 다른 서비스에서 코드 복제 필요
- 독립 사용 불가: 추가 작업 없이 CLI나 Docker 제공 불가
- 긴밀한 결합: 코어 변경이 서비스 릴리스 사이클에 종속
- 제한된 재사용: 외부에서 코어 사용 불가
Option C: 소스 공유 (Git Submodule)
Git submodule로 리포지토리 간 코어 코드 공유.
장점:
- 게시 없이 소스 수준 공유
단점:
- 복잡한 Git 워크플로우
- 독립적 버저닝 없음
- 열악한 도구 지원
- 라이브러리로 게시 불가
Consequences
Positive
오픈소스 전략
- 코어를 별도로 MIT 라이선스 가능
- 투명성을 통한 신뢰 구축
- 새 프레임워크에 대한 커뮤니티 기여 가능
유연한 소비
- 서비스는 Go 모듈로 임포트
- 개발자는 로컬에서 CLI 실행
- CI/CD는 Docker 이미지 사용
- 모두 단일 소스에서
독립적 발전
- 코어 팀이 버그 수정을 즉시 릴리스 가능
- 소비자는 자신의 속도로 업그레이드
- 호환성 깨지는 변경은 semver로 커뮤니케이션
생태계 기여
- 독립 도구로서 플랫폼 외부에서도 가치
- 조직 외부 채택 가능성
Negative
조율 오버헤드
- 어떤 서비스가 어떤 코어 버전을 사용하는지 추적 필요
- 완화: 자동화된 의존성 업데이트 (Dependabot)
API 안정성 부담
- 공개 API 변경에 신중한 계획 필요
- 완화: 보수적인 API 표면, 확장 포인트
유지보수 비용
- 별도 리포지토리, CI/CD, 문서화
- 완화: 리포지토리 간 표준화된 도구
영향받는 리포지토리
| 리포지토리 | 역할 | 영향 |
|---|---|---|
| core | 코어 라이브러리 | 주요 - 공개 API 정의 |
| worker | 소비자 | 코어를 의존성으로 임포트 |
| web | 소비자 | 동기 작업용 임포트 가능 |