배경 및 목표
개발자마다 Kafka 토픽 이름을 다르게 지어서, 토픽명만 보고는 용도나 컨슈머 수를 판단할 수 없었습니다. 새로운 개발자가 합류할 때 기존 토픽들의 역할을 파악하는 데 시간이 걸렸고, 토픽을 새로 만들 때도 기준이 없어 혼란이 있었습니다.
목표
- 토픽명만으로 용도·컨슈머 수를 판단할 수 있는 네이밍 표준을 정립한다.
- 신규 개발자 온보딩과 토픽 신설 기준을 명확히 한다.
해결 방법과 해결 후보군
후보군 비교
| 방식 | 설명 | 한계 |
|---|---|---|
| 자유 네이밍 유지 | 개발자 재량에 맡김 | 토픽명으로 용도·컨슈머 수 판단 불가, 온보딩 지연 |
| 문서로만 규칙 안내 | 위키에 가이드 문서 | 강제성 없어 미준수, 문서-실제 괴리 발생 |
| 네이밍 컨벤션 표준화 (채택) | event.* / queue.* 규칙 정의 | 토픽명이 곧 문서, 코드 리뷰에서 강제 가능 |
1. 이벤트와 작업의 구분
Kafka 토픽의 사용 패턴을 분석한 결과, 크게 두 가지로 나뉘었습니다.
| 유형 | 패턴 | 네이밍 | 예시 |
|---|---|---|---|
| 이벤트 | 1:N (여러 컨슈머 구독) | event.{domain}.{sub-domain} | event.domain.created |
| 작업 | 1:1 (단일 컨슈머 처리) | queue.{domain}.{behavior} | queue.domain.process |
2. 컨벤션 정의와 적용 예시
토픽명만 보면 “이건 이벤트니까 새 컨슈머를 추가해도 되겠다” 또는 “이건 큐니까 하나의 워커가 처리하는 거구나”를 즉시 판단할 수 있습니다.
3. 팀 표준 채택
컨벤션을 문서화하여 팀에 제안했고, 팀 표준으로 채택되었습니다. 이후 새로운 토픽을 만들 때 모두 이 규칙을 따르게 되어, 코드가 곧 문서가 되는 효과를 얻었습니다.
결과
| 지표 | 결과 |
|---|---|
| 네이밍 규칙 | 팀 표준 채택 (모든 신규 토픽 동일 규칙) |
| 온보딩 | 토픽명만으로 목적·컨슈머 수 판단 |
| 문서화 | 코드 = 문서 (별도 문서 불필요) |
모니터링
- 신규 토픽이 컨벤션(event.* / queue.*)을 따르는지 리뷰 단계에서 점검한다.
- 표준 채택 후 토픽 신설 시 혼선·문의 감소를 관측한다.