공통 모듈, 무엇을 담고 무엇을 빼야할까?

지난 시간, 우리는 MSA 환경에서 왜 공통 모듈(Common Library)이 필요한 이유에 대해 살펴보았습니다. 서비스가 분산될수록 파편화되는 코드를 관리하기 위해 공통 모듈은 필수적인 선택지입니다. 하지만 막상 모듈을 만들고 나면 새로운 고민이 시작됩니다.

"공통 모듈에 어디까지 넣어야 할까요?"

너무 많이 넣으면 서비스 간 결합도가 높아져 MSA의 독립성을 해치고, 너무 적게 넣으면 모듈을 사용하는 의미가 퇴색됩니다. 오늘은 공통 모듈을 설계할 때 반드시 지켜야 할 기준과 포함해야 할 핵심 요소들을 정리해 보겠습니다.

공통 모듈 설계의 핵심 원칙: 응집도와 결합도

공통 모듈에 코드를 추가하기 전에 항상 다음 두 가지 질문을 던져보아야 합니다.

• 모든 도메인 서비스에서 공통으로 사용하는가?
• 비즈니스 로직(업무 규칙)이 포함되어 있는가?

가장 이상적인 공통 모듈은 비즈니스 로직을 배제하고, 서비스들이 공통으로 사용하는 '기술적인 규약'과 '인프라 설정'만을 담는 것입니다. 특정 서비스의 업무 규칙이 공통 모듈에 들어가기 시작하면, 그 순간부터 공통 모듈은 모든 서비스의 변경을 유발하는 결합도의 폭탄이 됩니다. 공통 모듈은 서비스의 구현체가 아닌, 서비스들이 함께 공유하는 언어와 도구 상자여야 합니다.

공통 모듈에 포함하면 효과적인 항목들

그렇다면 실무에서는 구체적으로 어떤 것들을 관리할까요?

공통 응답 객체 (Common Response)

API의 일관성을 유지하는 것은 프론트엔드와 백엔드 간의 소통 비용을 줄이는 핵심입니다. 성공과 실패 시의 응답 포맷(message, data 등)을 공통 모듈에서 정의하여 모든 서비스가 동일한 형태의 응답을 반환하도록 강제합니다.

전역 예외 처리 (Global Exception Handling)

각 서비스마다 에러 응답 형식이 다르면 클라이언트 입장에선 혼란스럽습니다. 비즈니스 예외(Business Exception)와 시스템 예외(System Exception)를 공통 모듈에서 정의하고, 이를 처리하는 전역 핸들러를 구성하면 모든 서비스에서 동일한 에러 응답이 나가도록 제어할 수 있습니다.

공통 엔티티 (BaseEntity)

모든 테이블에 반복적으로 들어가는 created_at, updated_at, created_by 등의 필드는 중복의 온상입니다. 이를 추상 클래스로 정의하여 배포하면 엔티티 설계의 표준화를 쉽게 달성할 수 있습니다.

공통 유틸리티 및 기술 설정

날짜 포맷 처리, JSON 직렬화 설정, 공통으로 사용하는 정규식, 혹은 특정 인프라 의존성(Feign Client 설정, Redis Config 등)을 템플릿 형태로 제공합니다.

넣지 말아야 할 것들

반대로, 공통 모듈에 포함되는 순간 MSA의 발목을 잡는 항목들도 있습니다.

• 서비스 고유의 비즈니스 도메인 로직: "주문 생성 시 재고를 확인하는 로직" 같은 것은 결코 공통 모듈에 들어가면 안 됩니다. 이 로직은 재고 서비스나 주문 서비스에 존재해야 하며, 필요하다면 API 호출을 통해 협업해야 합니다.
• 특정 환경에 종속된 설정: DB 접속 정보, 특정 서비스의 API 주소 등은 각 서비스의 설정 파일(application.yml)이나 중앙 설정 서버(Spring Cloud Config)에서 관리해야 합니다.

마무리

공통 모듈은 단순히 중복을 제거하는 도구를 넘어, 팀 전체가 개발 표준을 공유하는 강력한 수단입니다. 하지만 그 편리함에 취해 비즈니스 로직까지 모두 끌어안게 되면, 오히려 MSA가 지향하는 독립적인 배포와 운영을 방해하는 장애물이 될 수 있습니다.

다음 시간에는 이렇게 설계한 공통 모듈을 어떻게 GitHub Packages를 통해 배포하고, 각 도메인 서비스에서 안전하게 의존성을 주입하여 사용하는지 그 실전 파이프라인 구축 과정을 다루어 보겠습니다.