UML 패키지 다이어그램으로 모듈 경계와 의존성 관리하기

모듈 경계를 의존성 정책으로 드러내기

대규모 소프트웨어에서는 모듈이 무엇을 소유하고 어디까지 공개하는지, 다른 모듈과 어떤 방식으로 연결되는지를 분명히 해야 한다. UML 패키지 다이어그램은 클래스·컴포넌트·유스케이스 같은 모델 요소를 패키지로 묶고, 패키지 사이의 의존 관계와 네임스페이스 구성을 표현하는 정적 구조 다이어그램이다.

이 도식은 설계 문서에만 쓰이지 않는다. 아키텍처 거버넌스, 변경 영향 분석, 리팩터링 방향 설정, 조직과 팀 경계의 정렬에 필요한 기준으로 활용할 수 있다.

패키지가 관리하는 공개 범위와 이름 공간

패키지는 모델 요소의 집합이자 이름 공간의 단위다. 도메인, 계층, 기능 축에 따라 서브패키지로 분해할 수 있으며, 내부 요소와 외부에 공개할 요소를 구분한다. 이 구분은 외부 API와 구현 세부 사항의 경계를 만든다.

공개(+)와 비공개(-) 요소를 규정하면 외부 의존성 노출을 줄이고 내부 구현을 캡슐화할 수 있다. 패키지 접두사나 버전 태그 같은 명명 규칙, 팀·레포지토리 같은 소유권 메타데이터도 운영 관리에 사용된다.

관계의 의미를 구분해 결합도를 통제한다

패키지 사이의 의존성은 단순한 화살표가 아니라 설계 의도를 담는다.

• «import»는 대상 패키지의 공개(public) 타입을 소스 패키지의 네임스페이스로 가져온다. 타입을 재정의하지 않고 참조할 수 있다.
• «access»는 공개 멤버에 접근할 수 있음을 나타낸다. 네임스페이스를 병합하지 않고 참조 관계만 만든다.
• «merge»는 패키지를 병합하는 관계다. 정의가 충돌하면 규칙에 따라 병합 또는 재정의가 발생한다. 프레임워크 확장이나 표준 프로파일 합성에 쓸 수 있지만 신중하게 다뤄야 한다.

역할과 정책은 «layer», «service», «library», «feature», «context» 같은 스테레오타입으로도 표시할 수 있다. 조직 표준 프로파일을 적용하면 설계 리뷰의 일관성과 거버넌스 자동화 기반을 마련할 수 있다.

계층은 한 방향으로 흐르게 둔다

계층 구조에서는 상위에서 하위로 향하는 단방향 의존과 비순환 의존 원칙(Acyclic Dependencies Principle)을 따르는 방식이 권장된다. «layer» 스테레오타입으로 이 규칙을 다이어그램에 드러낼 수 있다.

의존 사이클은 빌드와 배포의 위험을 키우고, 한 모듈의 변경이 예상보다 넓게 번지게 한다. 사이클을 탐지하고 차단하는 일은 모듈 경계 관리의 핵심이다.

UI·도메인·인프라 패키지의 관계

⤢✕

이 예시에서 UI는 Domain을 «import»하여 공개 타입을 네임스페이스에 도입한다. Domain은 Infra에 «access»로 접근하며, Common은 공유 타입을 제공하고 Domain은 필요하면 이를 «merge»한다. Infra에서 UI로 향하는 의존은 사이클을 만들기 때문에 금지한다.

아키텍처 경계를 검토하는 장면

마이크로서비스에서는 서비스별 패키지 경계와 공유 커널 패키지를 규정해 팀 간 결합을 줄일 수 있다. 금지 의존 규칙을 CI에서 검증하면 릴리스 위험을 통제하는 데 도움이 된다.

DDD의 바운디드 컨텍스트를 다룰 때는 컨텍스트별 패키지와 «access», «merge» 규칙으로 번역 계층 및 ACL(Anti-Corruption Layer)을 표현할 수 있다. 이때 컨텍스트 사이의 의존 방향과 데이터 소유권을 함께 명확히 한다.

모놀리스를 모듈화하는 작업에서는 프레젠테이션·도메인·인프라 계층을 나누고 사이클을 제거하는 기준으로 쓸 수 있다. Gradle 멀티모듈, 자바 패키지, 네임스페이스와 대응시키면 빌드와 테스트 격리에도 연결된다.

플랫폼 라이브러리는 «library» 스테레오타입 패키지로 선언하고 «import» 사용을 강제할 수 있다. 버전 태그는 호환성 매트릭스 관리에 사용한다.

다이어그램을 규칙과 검증으로 연결하는 과정

입력으로는 요구사항 목록, 도메인 개념 카탈로그, 기존 코드베이스 및 모듈 인벤토리, 조직 구조와 팀 경계, 컴플라이언스 제약을 사용한다.

먼저 응집도를 기준으로 후보 패키지를 식별하고 명명 규칙을 정한다. 이어 계층과 허용 의존 방향을 정의해 허용 매트릭스를 만들고, «import»·«access»·«merge» 관계와 가시성을 할당한다. 발견된 사이클은 추상화 도입이나 의존성 역전으로 제거한다.

리뷰와 워크숍에서 이해관계자 합의를 거쳐 베이스라인을 확정한 뒤, ArchUnit, jQAssistant, deptrac 등의 도구와 린팅을 이용해 CI 규칙으로 만든다. 산출물에는 패키지 다이어그램 v1, 허용 의존성 규칙 매트릭스, 명명·가시성 가이드, 소유권 및 승인 프로세스 문서가 포함된다.

사이클이 발견되면 공통 추상화를 도입하거나 의존 방향을 바꾸고, 필요하면 관계를 «access»로 축소한다. 금지 의존 위반은 빌드 게이트 실패로 처리하며 변경 승인을 통한 예외 관리가 필요하다. 네임스페이스 충돌에는 접두사 또는 컨텍스트 재명명을 적용하고 «merge» 사용을 최소화한다. 팀이 동시에 수정하면서 충돌할 때는 모델 저장소 잠금·분기 전략과 변경 충돌 해결 절차를 운영한다.

구조 개선 효과를 측정하는 기준

패키지 간 의존 간선 수를 3060% 줄이고 평균 경로 길이를 단축하면 변경 영향 범위를 축소할 수 있다. CI 의존 분석과 증분 빌드 시간은 1535% 단축되고, 모듈 단위 테스트의 병렬성은 높아진다. 사이클을 제거해 배포 차단 건수 0건을 유지하고 릴리스 실패율을 20% 이상 낮추는 효과도 기대할 수 있다.

정성적으로는 경계가 분명해져 온보딩과 리뷰 효율이 높아지고, 아키텍처 의사소통의 기준이 통일된다. 기술 부채를 가시화해 상향식 리팩터링의 우선순위를 정하기도 쉬워진다.

마틴 메트릭은 패키지 안정성을 추적하는 지표로 사용할 수 있다. Ca(내입력)와 Ce(외출력)를 측정해 불안정성 I=Ce/(Ca+Ce)를 추적하고, 추상화 A와 주서열 거리 D=|A+I−1|를 최소화해 설계 균형을 유도한다.

규칙을 강하게 만들수록 생기는 비용

비순환 의존을 지키고 상향 의존을 제한하며, 공용 타입은 «library» 또는 Common 패키지에 격리하는 방식이 기본이다. «merge»는 최소화하고 명시적인 «access»를 사용하면 네임스페이스 누수를 막을 수 있다. 구조 규칙은 CI에 자동 검증으로 포함하고, 위반 사항은 PR 게이트에서 차단한다.

다만 패키지를 지나치게 잘게 나누면 경계 유지 비용과 의사소통 오버헤드가 커질 수 있다. 엄격한 규칙은 초기 생산성을 낮출 수 있으므로 중장기 안정성과 균형을 잡아야 한다. Common 패키지가 비대해지면 상향 의존이 한곳에 집중되어 결합도가 높아질 위험도 있다.

패키지·컴포넌트·클래스 다이어그램이 다루는 범위

구분	패키지 다이어그램	컴포넌트 다이어그램	클래스 다이어그램
범위/추상화	모듈/네임스페이스 수준	배포 가능한 컴포넌트/인터페이스 수준	타입/연관/상속 수준
의존 표현	«import»/«access»/«merge» 중심	제공/요구 인터페이스, 포트/커넥터	연관/의존/일반화
일관성/안정성	비순환·계층 규칙 관리에 적합	배포·런타임 경계 검증에 적합	정밀한 도메인 모델링에 적합
확장성	모듈 수 증가에도 관리 용이	컴포넌트 수 증가 시 인터페이스 관리 필요	대규모 시 시각 복잡도 급증
운영 편의	CI 구조 규칙 자동화 용이	릴리스 관리/버전 호환성 관리 강점	코드 설계 상세 검토에 적합

패키지 다이어그램은 모듈 경계와 의존 정책을 명확히 한 뒤, 비순환·계층 규칙을 실행 가능한 거버넌스로 연결하는 도구다. 설계 단계에서 규칙을 명시하고 CI 구조 검증에 통합하면 마이크로서비스, DDD, 모놀리스 모듈화의 변경 비용과 운영 위험을 관리할 수 있다.