처음부터 완벽한 공통화를 하지 않은 이유

기술 실무 설계 시리즈 6/8

비슷한 운영 콘솔을 여러 개 만들면 공통화 욕구가 생긴다.

같은 React를 쓰고, 비슷한 레이아웃을 쓰고, API 호출 방식도 비슷하다면 공통 패키지를 만들고 싶어진다.

하지만 처음부터 완벽한 공통화를 하는 것이 항상 좋은 선택은 아니다.

특히 도메인이 다른 운영 도구에서는 중복 제거보다 책임 경계가 더 중요할 때가 있다.

공통화가 매력적인 이유

공통화에는 분명한 장점이 있다.

• 중복 코드가 줄어든다.
• UI 일관성이 생긴다.
• API 에러 처리 방식이 통일된다.
• 배포 스크립트를 재사용할 수 있다.
• 새 콘솔을 만들 때 속도가 빨라질 수 있다.

그래서 비슷한 화면이 두세 개 생기면 바로 공통 라이브러리를 만들고 싶어진다.

하지만 공통화는 공짜가 아니다.

너무 이른 공통화의 문제

아직 요구사항이 안정되지 않았는데 공통화를 하면 공통 모듈이 빠르게 비대해진다.

처음에는 단순한 버튼 컴포넌트였는데, 어느 순간 콘솔 A의 예외와 콘솔 B의 예외가 모두 들어간다.

API 클라이언트도 마찬가지다.

한 콘솔은 쿠키 인증을 쓰고, 다른 콘솔은 API Key를 쓸 수 있다.

한 콘솔은 S3 JSON을 읽고, 다른 콘솔은 RDB 기반 API를 호출할 수 있다.

이 차이를 공통 레이어에 억지로 넣으면 추상화가 흐려진다.

중복보다 경계가 더 중요할 때

코드 몇 줄이 중복되는 것보다 위험한 것은 책임 경계가 섞이는 것이다.

예를 들어 외부 공개 페이지와 내부 리포트 콘솔이 같은 공통 인증/라우팅 모듈을 억지로 쓰면 보안 예외가 늘어날 수 있다.

스프레드시트 기반 콘솔과 RDB 기반 콘솔을 같은 데이터 접근 추상화로 묶으면 각자의 특성이 사라질 수 있다.

이런 경우에는 중복을 감수하고 분리하는 편이 낫다.

반복을 관찰한 뒤 공통화하기

공통화는 반복이 충분히 관찰된 뒤 해도 늦지 않다.

처음에는 각 콘솔 안에서 구현한다.

그다음 실제로 반복되는 것이 무엇인지 본다.

• UI primitive인가
• 날짜 포맷인가
• API 에러 처리인가
• 인증 처리인가
• 배포 스크립트인가
• 문서 템플릿인가

반복이 안정적으로 보이면 그때 공통화한다.

예측으로 만든 공통 모듈보다 관찰 후 만든 공통 모듈이 오래 간다.

공통화하기 좋은 것

다음은 비교적 공통화하기 좋다.

• 기본 UI 컴포넌트
• 로딩/에러 표시 패턴
• 날짜와 숫자 포맷
• 공통 타입 또는 상수
• 문서 템플릿
• 배포 체크리스트
• 로그 메시지 규칙

이런 것들은 도메인 의존성이 낮다.

공통화해도 각 콘솔의 책임 경계를 크게 흐리지 않는다.

공통화에 조심해야 하는 것

다음은 조심해야 한다.

• 인증과 권한
• 데이터 접근 계층
• 업무 상태값
• 라우팅 구조
• 배포 대상과 환경 변수
• 공개 데이터와 내부 데이터 처리

이 영역은 도메인 차이가 크다.

성급히 공통화하면 예외 분기가 많아질 수 있다.

공통화한다면 인터페이스와 책임을 아주 명확히 해야 한다.

공통 패키지의 유지보수 비용

공통 패키지를 만들면 관리해야 할 것이 늘어난다.

• 버전 관리
• 배포 순서
• breaking change
• 각 콘솔의 의존성 업데이트
• 테스트 범위
• 소유권

공통화는 코드를 줄이지만 운영 단위를 늘릴 수 있다.

따라서 공통 패키지를 만들 때는 이 비용을 감당할 가치가 있는지 봐야 한다.

정리

중복 제거는 좋은 목표다.

하지만 처음부터 완벽한 공통화를 목표로 하면 도메인 경계가 흐려질 수 있다.

운영 도구에서는 중복보다 책임 경계가 더 중요할 때가 많다.

좋은 순서는 이렇다.

1. 먼저 각 콘솔의 책임을 분리한다.
2. 실제 반복을 관찰한다.
3. 도메인 의존성이 낮은 것부터 공통화한다.
4. 인증, 데이터, 권한은 신중하게 다룬다.

공통화는 편의를 위한 것이 아니라 변경 비용을 줄일 때 가치가 있다.

함께 볼 GitHub 저장소

• practical-system-design-playbook