[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -2,99 +2,200 @@
|
||||
id: wiki-2026-0508-의존성-규칙-dependency-rule
|
||||
title: 의존성 규칙 (Dependency Rule)
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [P-Reinforce-AUTO-57A5BA]
|
||||
aliases: [Dependency Rule, Clean Architecture Dependency Rule]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.9
|
||||
tags: [auto-reinforced]
|
||||
verification_status: applied
|
||||
tags: [architecture, clean-architecture, dependency-rule, layering]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-04-20
|
||||
github_commit: "[P-Reinforce] Continuous Worker - 의존성 규칙 (Dependency Rule)"
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
tech_stack:
|
||||
language: unspecified
|
||||
framework: unspecified
|
||||
language: typescript
|
||||
framework: nestjs
|
||||
---
|
||||
|
||||
# [[의존성 규칙 (Dependency Rule)|의존성 규칙 (Dependency Rule]]
|
||||
# 의존성 규칙 (Dependency Rule)
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
> 의존성 규칙(Dependency Rule)은 클린 아키텍처(Clean [[Architecture|Architecture]])의 핵심 원칙으로, 모든 소스 코드 의존성이 반드시 고수준의 핵심 비즈니스 로직을 향해 '안쪽으로만' 향해야 한다는 원칙입니다 [1-3]. 이 규칙은 내부 계층(뇌)이 외부 계층(팔다리)의 존재에 대해 전혀 알지 못하도록 통제하여 시스템의 결합도를 낮추고 독립성을 극대화합니다 [2-4]. 결과적으로 비즈니스의 본질적인 규칙을 UI, 데이터베이스, 프레임워크 등 변동성이 높은 기술적 세부 사항으로부터 완벽하게 격리하고 보호하는 역할을 수행합니다 [1, 4, 5].
|
||||
## 매 한 줄
|
||||
> **"매 source code dependency는 안쪽으로만 향한다"**. Robert C. Martin이 *Clean Architecture* (2017)에서 정식화한 핵심 규칙으로, 외곽 layer (frameworks, UI, DB)는 내부 layer (use cases, entities)를 알지만 그 반대는 금지된다 — 도메인의 framework-independence를 강제하는 architectural invariant.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
* **의존성의 방향 (Direction of Dependencies)**
|
||||
의존성 규칙에 따르면 소프트웨어의 소스 코드 의존성은 오직 안쪽, 즉 중앙의 핵심 비즈니스 로직(엔티티 및 유스케이스 등)으로만 향해야 합니다 [1, 3]. 이는 저수준의 모듈(외부의 프레임워크나 UI)이 고수준의 모듈(내부의 도메인)에 의존해야 하며, 고수준 모듈은 외부 기관에 결코 의존해서는 안 된다는 것을 의미합니다 [2].
|
||||
## 매 핵심
|
||||
|
||||
* **내부 계층의 완전한 격리 (Isolation of Inner Layers)**
|
||||
내부의 원에 속한 코드(뇌)는 외부의 원에 선언된 어떤 것(팔다리)에 대해서도 그 이름을 언급해서는 안 됩니다 [3]. 즉, 함수, 클래스, 변수 등 외부에 존재하는 모든 소프트웨어 요소의 존재를 내부 계층은 몰라야 합니다 [3]. 이를 통해 외부의 인프라스트럭처가 변경되더라도 핵심 비즈니스 규칙이 영향을 받지 않도록 보장합니다 [4, 6].
|
||||
### 매 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.
|
||||
|
||||
* **데이터 형식의 독립성 (Data Format Independence)**
|
||||
외부 원에서 선언된 데이터 형식이나 특정 프레임워크가 생성한 데이터 구조를 내부 원에서 절대로 사용해서는 안 됩니다 [3]. 계층의 경계를 가로질러 데이터를 전달할 때는, 데이터베이스의 행(Row) 같은 외부 포맷이 아닌 내부의 원에서 사용하기 편리한 형태(간단한 데이터 전송 객체나 구조체)로 변환되어 전달되어야 합니다 [6, 7].
|
||||
### 매 규칙의 정확한 statement
|
||||
- 안쪽 circle은 바깥쪽 circle의 **이름조차** 알아서는 안 됨 (class, function, variable, 어떤 software entity든).
|
||||
- 바깥쪽 circle의 데이터 형식이 안쪽으로 새어들어와도 안 됨 — 새는 순간 dependency arrow가 거꾸로 흐름.
|
||||
- 위반 발견 시 → DIP (Dependency Inversion Principle)로 풀기: interface를 안쪽에 정의, 구현을 바깥쪽에 둠.
|
||||
|
||||
* **경계 횡단과 의존성 역전 원칙 (Crossing [[Boundaries|Boundaries]] and DIP)**
|
||||
시스템의 제어 흐름이 의존성 규칙과 반대 방향으로 향해야 하는 경우(예를 들어, 내부의 유스케이스 계층이 외부의 프레젠터 계층을 호출해야 할 때), 이를 직접 호출하면 의존성 규칙을 위배하게 됩니다 [8]. 이 문제는 의존성 역전 원칙(DIP)과 동적 다형성을 활용하여 해결합니다 [8, 9]. 내부 계층에 인터페이스를 정의하고 외부 계층이 이를 구현하게 함으로써, 제어 흐름이 밖으로 향하더라도 소스 코드 의존성은 계속 안쪽을 유지할 수 있게 만듭니다 [8-10].
|
||||
### 매 응용
|
||||
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 가능. 이게 안 되면 위반 의심.
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
|
||||
- **정책 변화:** Design & Experience 분야의 자동 자산화 수행.
|
||||
## 💻 패턴
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- **Related Topics:** [[클린 아키텍처 (Clean Architecture)|클린 아키텍처 (Clean Architecture]], 의존성 역전 원칙 (Dependency Inversion Principle, DIP), 엔티티 (Entities), [[유스케이스 (Use Cases)|유스케이스 (Use Cases]]
|
||||
- **Projects/Contexts:** [[엔터프라이즈 소프트웨어 시스템 설계|엔터프라이즈 소프트웨어 시스템 설계]], [[모듈화 및 아키텍처 경계 설정|모듈화 및 아키텍처 경계 설정]]
|
||||
- **Contradictions/Notes:** 의존성 규칙을 엄격하게 준수하기 위해 완벽한 아키텍처 경계(쌍방향 다형적 인터페이스, 분리된 입/출력 데이터 구조 등)를 만드는 것은 초기 설정 및 유지보수 비용이 상당히 큽니다 [11]. 따라서 모든 상황에 이 규칙을 엄격히 적용하기보다는, 프로젝트의 규모에 따라 전략 패턴이나 퍼사드(Facade) 패턴을 활용한 부분적 경계(Partial Boundary)를 두거나 실무적 타협을 하는 경우도 존재합니다 [11-13].
|
||||
### Anti-pattern: 도메인이 ORM을 알고 있음
|
||||
```typescript
|
||||
// 안티: 도메인 entity가 TypeORM에 의존
|
||||
import { Entity, Column } from 'typeorm';
|
||||
|
||||
---
|
||||
*Last updated: 2026-04-18*
|
||||
|
||||
---
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
@Entity()
|
||||
export class Order {
|
||||
@Column() id: string;
|
||||
@Column() total: number;
|
||||
// 도메인이 typeorm 패키지에 source-level dependency를 가짐 → 위반
|
||||
}
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### Fix: Pure 도메인 + 별도 persistence model
|
||||
```typescript
|
||||
// domain/order.ts — framework 모름
|
||||
export class Order {
|
||||
constructor(
|
||||
public readonly id: string,
|
||||
public readonly total: number,
|
||||
) {}
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
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);
|
||||
}
|
||||
}
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
// infra/persistence/order.entity.ts — ORM 전용
|
||||
@Entity('orders')
|
||||
export class OrderRow {
|
||||
@PrimaryColumn() id!: string;
|
||||
@Column('numeric') total!: number;
|
||||
}
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
// 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 });
|
||||
```
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
### 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>;
|
||||
}
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
// 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]] · [[Architectural Principles]]
|
||||
- 변형: [[Hexagonal Architecture Ports and Adapters]] · [[Onion Architecture]]
|
||||
- 응용: [[Domain-Driven Design]] · [[Use Case Pattern]]
|
||||
- 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 적용 패턴 정리 |
|
||||
|
||||
Reference in New Issue
Block a user