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

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-의존성-규칙-dependency-rule	의존성 규칙 (Dependency Rule)	10_Wiki/Topics	verified	self	Dependency Rule Clean Architecture Dependency Rule	none	A	0.9	applied	architecture clean-architecture dependency-rule layering		2026-05-10	pending	language framework typescript 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을 알고 있음

// 안티: 도메인 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

// 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 의존 뒤집기

// 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)

@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 강제

// .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가 위반을 잡아냄

// 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 적용 패턴 정리