코드베이스 설계
딥 모듈(deep modules) 설계: 작은 인터페이스 뒤에 많은 행동을 숨기고, 깔끔한 경계(seam)에 배치하며, 그 인터페이스를 통해 테스트 가능하게 만듭니다. 코드를 설계하거나 재구성할 때마다 이 언어와 원칙을 사용하세요. 목표는 호출자에게 레버리지(leverage), 유지보수자에게 지역성(locality), 모두에게 테스트 용이성입니다.
용어집
다음 용어를 정확히 사용하세요 — 'component', 'service', 'API', 'boundary'로 대체하지 마세요. 일관된 언어가 핵심입니다.
Module — 인터페이스와 구현을 가진 모든 것. 의도적으로 규모와 무관: 함수, 클래스, 패키지, 또는 계층을 넘나드는 조각. 피할 것: unit, component, service.
Interface — 호출자가 모듈을 올바르게 사용하기 위해 알아야 하는 모든 것: 타입 시그니처뿐만 아니라 불변 조건, 순서 제약, 오류 모드, 필수 설정, 성능 특성까지 포함합니다. 피할 것: API, signature (너무 좁음 — 타입 수준 표면만 가리킴).
Implementation — 모듈 내부, 코드 본문. Adapter와 구분: 어떤 것은 큰 구현을 가진 작은 어댑터(PostgreSQL 저장소)일 수 있고, 작은 구현을 가진 큰 어댑터(인메모리 페이크)일 수 있습니다. 경계(seam)가 주제일 때는 'adapter'를, 그 외에는 'implementation'을 사용하세요.
Depth — 인터페이스에서의 레버리지: 호출자(또는 테스트)가 배워야 하는 인터페이스 단위당 발휘할 수 있는 행동의 양. 작은 인터페이스 뒤에 많은 행동이 있으면 깊고(deep), 인터페이스가 구현만큼 복잡하면 얕습니다(shallow).
Seam (Michael Feathers) — 그 자리에서 편집하지 않고 행동을 변경할 수 있는 곳; 모듈의 인터페이스가 위치한 지점. 경계를 어디에 둘지는 그 자체로 설계 결정이며, 그 뒤에 무엇이 올지와는 별개입니다. 피할 것: boundary (DDD의 bounded context와 중복됨).
Adapter — 경계(seam)에서 인터페이스를 충족하는 구체적인 것. 역할(무엇을 채우는지)을 설명하며, 내용(내부가 무엇인지)은 설명하지 않습니다.
Leverage — 호출자가 깊이(depth)로부터 얻는 것: 배운 인터페이스 단위당 더 많은 능력. 하나의 구현이 N개의 호출 지점과 M개의 테스트에서 보답합니다.
Locality — 유지보수자가 깊이(depth)로부터 얻는 것: 변경, 버그, 지식, 검증이 호출자들로 퍼지지 않고 한 곳에 집중됩니다. 한 번 고치면 모든 곳에서 고쳐집니다.
깊음(Deep) vs 얕음(Shallow)
깊은 모듈 = 작은 인터페이스 + 많은 구현:
┌─────────────────────┐
│ 작은 인터페이스 │ ← 적은 메서드, 간단한 파라미터
├─────────────────────┤
│ │
│ 깊은 구현 │ ← 숨겨진 복잡한 로직
│ │
└─────────────────────┘
얕은 모듈 = 큰 인터페이스 + 적은 구현 (피할 것):
┌─────────────────────────────────┐
│ 큰 인터페이스 │ ← 많은 메서드, 복잡한 파라미터
├─────────────────────────────────┤
│ 얇은 구현 │ ← 그냥 통과만 시킴
└─────────────────────────────────┘
인터페이스를 설계할 때 물어보세요:
- 메서드 수를 줄일 수 있나요?
- 파라미터를 단순화할 수 있나요?
- 더 많은 복잡성을 내부에 숨길 수 있나요?
원칙
- 깊이(Depth)는 구현이 아닌 인터페이스의 속성입니다. 깊은 모듈은 내부적으로 작고, 목킹 가능하며, 교체 가능한 부품들로 구성될 수 있습니다 — 그저 인터페이스의 일부가 아닐 뿐입니다. 모듈은 내부 경계(internal seams) (구현에 비공개이며 자체 테스트에서 사용됨)와 외부 경계(external seam) (인터페이스에 있음)를 모두 가질 수 있습니다.
- 삭제 테스트. 모듈을 삭제한다고 상상해보세요. 복잡성이 사라지면 통과(pass-through)였던 것입니다. 복잡성이 N개의 호출자에 걸쳐 다시 나타나면 그만한 가치가 있었던 것입니다.
- 인터페이스는 테스트 표면입니다. 호출자와 테스트는 같은 경계(seam)를 가로지릅니다. 인터페이스를 지나쳐 테스트하고 싶다면 모듈 모양이 잘못된 것입니다.
- 어댑터 하나는 가상의 경계(seam)입니다. 어댑터 두 개는 진짜 경계입니다. 실제로 변하는 것이 없으면 경계를 도입하지 마세요.
테스트 용이성을 위한 설계
좋은 인터페이스는 테스트를 자연스럽게 만듭니다:
-
의존성을 받아들이고, 생성하지 마세요.
// 테스트 가능 function processOrder(order, paymentGateway) {} // 테스트 어려움 function processOrder(order) { const gateway = new StripeGateway(); } -
결과를 반환하고, 부작용을 만들지 마세요.
// 테스트 가능 function calculateDiscount(cart): Discount {} // 테스트 어려움 function applyDiscount(cart): void { cart.total -= discount; } -
작은 표면적. 메서드가 적을수록 필요한 테스트도 적습니다. 파라미터가 적을수록 테스트 설정이 간단해집니다.
관계
- Module은 정확히 하나의 Interface를 가집니다 (호출자와 테스트에 제공하는 표면).
- Depth는 Module의 속성이며, 해당 Interface에 대해 측정됩니다.
- Seam은 Module의 Interface가 위치하는 곳입니다.
- Adapter는 Seam에 위치하며 Interface를 충족합니다.
- Depth는 호출자에게 Leverage를, 유지보수자에게 Locality를 제공합니다.
거부된 프레임
- 구현 줄 수 대 인터페이스 줄 수 비율로서의 깊이(Depth) (Ousterhout): 구현을 부풀리도록 유도합니다. 우리는 레버리지로서의 깊이(leverage)를 사용합니다.
- TypeScript
interface키워드 또는 클래스의 public 메서드로서의 'Interface': 너무 좁음 — 인터페이스는 여기서 호출자가 알아야 하는 모든 사실을 포함합니다. - 'Boundary': DDD의 bounded context와 중복됨. Seam 또는 Interface라고 말하세요.
더 깊이 들어가기
- 의존성이 주어진 클러스터 심화(deepening) — DEEPENING.md 참조: 의존성 범주, 경계(seam) 규율, 교체-하지말고-계층화(replace-don't-layer) 테스트.
- 대안 인터페이스 탐색 — DESIGN-IT-TWICE.md 참조: 병렬 하위 에이전트를 실행하여 인터페이스를 근본적으로 다른 여러 방식으로 설계한 다음, 깊이(Depth), 지역성(Locality), 경계(seam) 배치를 기준으로 비교합니다.