[중간 회고] 여기까지 구현 하면서...

바인드 프로젝트 퍼블릭 모듈 설계기(6/17)

개요

우리는 마이크로서비스 기반 프로젝트인 Bind를 설계하며, 각 서비스가 공통적으로 사용할 수 있는 기능들을 별도의 퍼블릭 모듈로 구성하기로 했습니다.
이러한 모듈화는 개발 효율성 향상뿐 아니라, 책임 분리 및 유지보수성을 크게 개선합니다.

이번 글에서는 Bind 프로젝트에서 먼저 구현한 퍼블릭 모듈들에 대해,
각 모듈의 설계 목적과 구현 과정, 그리고 실제 사용하는 예시까지 간단히 소개합니다.

---

퍼블릭 모듈의 구성

현재까지 다음과 같은 퍼블릭 모듈들을 구축했습니다:

모듈 이름	역할 및 목적
primary-id-provider	고속 유니크 ID 생성기 (Snowflake 알고리즘 기반)
exception	전역 예외 처리 및 예외 구조 표준화
serializer	Kafka/Redis에 대응 가능한 공용 직렬화 유틸리티
event	커스텀 이벤트 발행 구조 정의
infra-messaging	Kafka 메시징 송신자 추상화
outbox	트랜잭션 안전한 메시지 발송 구조 (Outbox 패턴 기반)

---

각 모듈별 설명

1. primary-id-provider

목적:
서비스 전반에서 사용할 수 있는, 정렬 가능한 유니크 ID를 생성합니다.

핵심 설계:

• Snowflake 기반 구조
• 단일 노드에서도 충돌 없이 ID 생성 가능
• 테스트 코드로 동시성 검증도 수행됨

예시 사용처:

long id = Snowflake.getInstance().getNextId();

---

2. exception

목적:
모든 서비스에 일관된 예외 구조를 제공하고, 오류 코드를 표준화합니다.

핵심 설계:

• ErrorCode, BaseException 구조 정의
• 전역 예외 처리기 GlobalExceptionHandler 구현
• 커스텀 예외 분류(비즈니스, 인증, 시스템 등) 확장 가능

예시 사용처:

throw new BusinessException(ErrorCode.INVALID_INPUT);

---

3. serializer

목적:
Kafka, Redis 등 다양한 시스템에서 공통으로 사용할 수 있는 직렬화 도구를 제공합니다.

핵심 설계:

• ObjectMapper 기반
• Java Time 모듈 지원 및 실패 안전화
• DataSerializer.serialize(), deserialize() 유틸 메서드 제공

예시 사용처:

String json = DataSerializer.serialize(someObject);
SomeClass obj = DataSerializer.deserialize(json, SomeClass.class);

---

4. event

목적:
Kafka 기반 이벤트 아키텍처의 전송 단위와 표준을 정합니다.

핵심 설계:

• BindEvent 인터페이스 및 공통 필드 제공
• 이벤트 타입, 식별자, 페이로드 구조 통일

예시 사용처:

BindEvent event = new UserCreatedEvent(userId, payload);

---

5. infra-messaging

목적:
Kafka 전송 기능을 추상화하여 도메인 로직과의 결합을 제거합니다.

핵심 설계:

• MessagingSender 인터페이스 제공
• Kafka 구현체는 KafkaEventProducer로 감쌈
• 다른 시스템(Redis 등)도 쉽게 구현체만 추가 가능

예시 사용처:

messagingSender.send(topic, payload, key);

---

6. outbox

목적:
DB 트랜잭션과 메시지 발행의 일관성을 보장하는 Outbox 패턴을 구현합니다.

핵심 설계:

• DB에 이벤트 저장 (OutboxEventEntity)
• 스케줄러가 주기적으로 발송 시도
• 실패/재시도/Dead 처리 포함
• Kafka 직접 호출 대신 MessagingSender 사용

예시 사용처:

eventPublisher.publish(someEvent);
// Kafka는 백그라운드에서 안전하게 전송됨

---

기술적 일관성과 구조적 이점

퍼블릭 모듈은 단순한 유틸리티 묶음이 아니라,
서비스 전반의 기술 표준을 구현하고 확장 가능한 구조를 유지하기 위한 중요한 기반입니다.

• Kafka에 대한 직접 의존 제거 → 테스트 용이성 증가
• 예외, ID, 이벤트 구조 통일 → 코드 이해도 상승
• 재사용 가능한 직렬화 유틸 → Kafka/Redis에서 동일 동작 보장
• Outbox 패턴 도입 → 데이터 유실 없이 안정적인 메시지 전송

---

마치며

Bind 프로젝트는 아직 초기 단계지만,
이렇게 서비스 개발 전에 공통 기반을 먼저 다지는 전략이 장기적으로 매우 큰 효과를 발휘할 것입니다.

다음 글부터는 각 모듈의 상세 설계와 구현, 테스트에 대한 내용을 시리즈로 정리할 예정입니다.