2nd/10_Wiki/Topics/Architecture/의존성 규칙 (Dependency Rule).md

---
id: wiki-2026-0508-의존성-규칙-dependency-rule
title: 의존성 규칙 (Dependency Rule)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Dependency Rule, Clean Architecture Dependency Rule]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [architecture, clean-architecture, dependency-rule, layering]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: nestjs
---

# 의존성 규칙 (Dependency Rule)

## 매 한 줄
> **"매 source code dependency는 안쪽으로만 향한다"**. Robert C. Martin이 *Clean Architecture* (2017)에서 정식화한 핵심 규칙으로, 외곽 layer (frameworks, UI, DB)는 내부 layer (use cases, entities)를 알지만 그 반대는 금지된다 — 도메인의 framework-independence를 강제하는 architectural invariant.

## 매 핵심

### 매 4-layer 모델
- **Entities** (innermost): enterprise-wide business rules. 가장 추상.
- **Use Cases**: application-specific business rules. Entities 사용.
- **Interface Adapters**: controllers, presenters, gateways. Use case에 맞춰 데이터 변환.
- **Frameworks & Drivers** (outermost): Web, DB, external API, UI framework.

### 매 규칙의 정확한 statement
- 안쪽 circle은 바깥쪽 circle의 **이름조차** 알아서는 안 됨 (class, function, variable, 어떤 software entity든).
- 바깥쪽 circle의 데이터 형식이 안쪽으로 새어들어와도 안 됨 — 새는 순간 dependency arrow가 거꾸로 흐름.
- 위반 발견 시 → DIP (Dependency Inversion Principle)로 풀기: interface를 안쪽에 정의, 구현을 바깥쪽에 둠.

### 매 응용
1. **Domain layer에서 ORM annotation 금지** — `@Entity` (TypeORM)를 도메인 클래스에 붙이는 순간 도메인이 ORM을 알게 됨.
2. **Use case는 HTTP request/response 모름** — controller가 DTO → command로 mapping.
3. **Test 전략**: 안쪽 layer는 framework 없이 pure unit test 가능. 이게 안 되면 위반 의심.

## 💻 패턴

### Anti-pattern: 도메인이 ORM을 알고 있음
```typescript
// 안티: 도메인 entity가 TypeORM에 의존
import { Entity, Column } from 'typeorm';

@Entity()
export class Order {
  @Column() id: string;
  @Column() total: number;
  // 도메인이 typeorm 패키지에 source-level dependency를 가짐 → 위반
}
```

### Fix: Pure 도메인 + 별도 persistence model
```typescript
// domain/order.ts — framework 모름
export class Order {
  constructor(
    public readonly id: string,
    public readonly total: number,
  ) {}

  static place(items: ReadonlyArray<{ price: number }>): Order {
    const total = items.reduce((s, i) => s + i.price, 0);
    if (total <= 0) throw new Error('empty order');
    return new Order(crypto.randomUUID(), total);
  }
}

// infra/persistence/order.entity.ts — ORM 전용
@Entity('orders')
export class OrderRow {
  @PrimaryColumn() id!: string;
  @Column('numeric') total!: number;
}

// infra/persistence/order.mapper.ts
export const toDomain = (r: OrderRow) => new Order(r.id, Number(r.total));
export const toRow = (o: Order): OrderRow =>
  Object.assign(new OrderRow(), { id: o.id, total: o.total });
```

### DIP로 use case → infra 의존 뒤집기
```typescript
// domain/ports/order-repository.ts (안쪽 layer가 interface 정의)
export interface OrderRepository {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
}

// application/place-order.usecase.ts (안쪽 layer)
export class PlaceOrderUseCase {
  constructor(private readonly repo: OrderRepository) {}
  async execute(items: { price: number }[]): Promise<string> {
    const order = Order.place(items);
    await this.repo.save(order);
    return order.id;
  }
}

// infra/typeorm-order-repository.ts (바깥쪽 layer가 구현)
export class TypeOrmOrderRepository implements OrderRepository {
  constructor(private readonly ds: DataSource) {}
  async save(o: Order) { await this.ds.getRepository(OrderRow).save(toRow(o)); }
  async findById(id: string) {
    const row = await this.ds.getRepository(OrderRow).findOneBy({ id });
    return row ? toDomain(row) : null;
  }
}
```

### Controller → use case (변환만, 비즈니스 로직 X)
```typescript
@Controller('orders')
export class OrderController {
  constructor(private readonly placeOrder: PlaceOrderUseCase) {}

  @Post()
  async create(@Body() dto: PlaceOrderDto): Promise<{ id: string }> {
    const id = await this.placeOrder.execute(dto.items);
    return { id };
  }
}
```

### ESLint로 dependency direction 강제
```js
// .eslintrc.cjs — eslint-plugin-boundaries
module.exports = {
  settings: {
    'boundaries/elements': [
      { type: 'domain',      pattern: 'src/domain/*' },
      { type: 'application', pattern: 'src/application/*' },
      { type: 'infra',       pattern: 'src/infra/*' },
      { type: 'web',         pattern: 'src/web/*' },
    ],
  },
  rules: {
    'boundaries/element-types': ['error', {
      default: 'disallow',
      rules: [
        { from: 'application', allow: ['domain'] },
        { from: 'infra',       allow: ['domain', 'application'] },
        { from: 'web',         allow: ['application', 'domain'] },
      ],
    }],
  },
};
```

### Test가 위반을 잡아냄
```typescript
// domain은 framework import 없이 build 되어야 함
import { Order } from './order';
test('place creates order with summed total', () => {
  const o = Order.place([{ price: 10 }, { price: 5 }]);
  expect(o.total).toBe(15);
});
// jest 단독, DB·HTTP·DI container 없이 통과 → 규칙 준수 신호
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| 작은 CRUD app, 팀 1-2명 | 규칙 약화 (도메인=ORM entity 허용) |
| 비즈니스 로직 복잡, 장수명 | 매 strict 적용 |
| Framework 교체 가능성 (DB, web) | 매 strict |
| Prototype·spike | 무시 가능 |

**기본값**: 도메인 layer는 framework import 0개로 시작 — 필요할 때 위반 허용.

## 🔗 Graph
- 부모: [[Clean Architecture]]
- 변형: [[Hexagonal Architecture (Ports and Adapters)]] · [[Onion Architecture]]
- 응용: [[Domain-Driven Design]]
- Adjacent: [[Dependency Inversion Principle]] · [[SOLID Principles]]

## 🤖 LLM 활용
**언제**: 코드 리뷰에서 "이 import가 layer 규칙을 깨는가?" 판단, refactor 계획 수립.
**언제 X**: 작은 script·prototype에서 규칙 강제 — 과잉.

## ❌ 안티패턴
- **도메인에 `@Entity` 부착**: ORM 의존이 안쪽으로 leak.
- **Use case에서 `req.body` 직접 참조**: HTTP 형식이 안쪽으로 leak.
- **Entity가 Repository import**: 안쪽 → 바깥 dependency.
- **DTO를 도메인 모델로 재사용**: layer 경계 소실.

## 🧪 검증 / 중복
- Verified (Robert C. Martin, *Clean Architecture*, 2017; Uncle Bob blog "The Clean Architecture", 2012).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — Dependency Rule 정의·layer model·DIP 적용 패턴 정리 |