모듈 아키텍처 심층 분석

Why This Work Exists

모듈 수가 늘어나면 빌드 시간, 테스트 비용, 변경 파급이 급격히 커진다. 특히 "공통 모듈이 기능 모듈을 참조"하거나 "구현체 직접 의존"이 누적되면 작은 수정도 다수 모듈 재빌드와 회귀 검증으로 이어진다.

Scope / Non-scope

• 범위: 모듈 경계/의존 방향/테스트 대체성/변경 전파 분석
• 범위: DI 경계 설계와 인터페이스 분리 전략
• 제외: 특정 앱의 실제 그래프 추출 결과(별도 문서에서 수행)
• 제외: CI 파이프라인/캐시 최적화의 도구별 세부 튜닝

As-is

• 기능 모듈에서 공통 모듈 구현체를 직접 참조
• 공통 모듈에서 기능 모듈 타입을 참조(역방향 의존)
• 테스트 시 mock 주입 경계가 약해 실제 I/O 연결 발생
• 변경 영향 범위를 예측하지 못해 릴리즈 리스크 확대

To-be

• 상위 레이어는 하위 레이어만 참조
• 모듈 간 계약은 interface(프로토콜)로만 노출
• 테스트 더블 주입 지점을 강제해 모듈 테스트 분리
• 변경 전파를 계약 변경 시점으로 제한

API / Data Contract

Risks And Decisions Needed

• 리스크: 과도한 추상화로 코드량/복잡도만 증가
• 리스크: 계약 설계 미숙으로 interface churn 발생
• 결정: interface 모듈 위치(공통 패키지 내부 vs 별도 패키지)
• 결정: 모듈 분리 granularity(화면 단위 vs 도메인 단위)

Class Diagram

classDiagram
            class AppComposer
            class FeatureInteractor
            class FeaturePresenter
            class WorkerInterface {
              <>
              +execute()
            }
            class WorkerImpl
            class CoreGatewayInterface {
              <>
              +request()
            }
            class CoreGatewayImpl

            AppComposer --> FeatureInteractor : injects
            FeatureInteractor --> WorkerInterface : depends on
            WorkerImpl ..|> WorkerInterface
            WorkerImpl --> CoreGatewayInterface
            CoreGatewayImpl ..|> CoreGatewayInterface
            FeatureInteractor --> FeaturePresenter
          

Sequence Diagram

sequenceDiagram
            participant VC as ViewController
            participant I as Interactor
            participant W as WorkerInterface
            participant C as CoreGatewayInterface
            participant P as Presenter

            VC->>I: doAction(request)
            I->>W: execute(request)
            W->>C: request(dto)
            C-->>W: response
            W-->>I: result
            I->>P: present(result)
            P-->>VC: viewModel
          

Before / After 코드 예시

Before (구현체 직접 의존)

final class LoginInteractor {
    private let worker = RealLoginWorker()

    func login(id: String, pw: String) async throws -> Token {
        try await worker.login(id: id, pw: pw)
    }
}

After (계약 의존 + 주입)

protocol LoginWorkerInterface {
    func login(id: String, pw: String) async throws -> Token
}

final class LoginInteractor {
    private let worker: LoginWorkerInterface

    init(worker: LoginWorkerInterface) {
        self.worker = worker
    }

    func login(id: String, pw: String) async throws -> Token {
        try await worker.login(id: id, pw: pw)
    }
}

테스트 예시 (mock/stub)

final class LoginWorkerStub: LoginWorkerInterface {
    var result: Result!

    func login(id: String, pw: String) async throws -> Token {
        switch result {
        case .success(let token): return token
        case .failure(let error): throw error
        case .none: fatalError("result not set")
        }
    }
}

func test_login_success() async throws {
    let stub = LoginWorkerStub()
    stub.result = .success(Token(value: "t1"))
    let sut = LoginInteractor(worker: stub)

    let token = try await sut.login(id: "a", pw: "b")
    assert(token.value == "t1")
}

핵심: 실제 네트워크 없이 use case 테스트가 독립적으로 수행된다.

QA Checklist

• 성공: 인터페이스 교체 후 기능 동작 동일
• 성공: 테스트가 실제 네트워크 없이 통과
• 실패: 역방향 의존이 재발하지 않는지 정적 점검
• 회귀: 기존 기능 모듈의 import 경로 변화 점검

Operations / Rollout Checklist

• 릴리즈 전: 핵심 사용자 플로우 smoke test
• 릴리즈 후: 빌드 시간/실패율 추이 모니터링
• 문제 발생 시: interface 변경과 구현 변경 분리 rollback
• 지속 관리: 아키텍처 규칙(역방향/순환 금지) CI 검사