chore(brain): ASTRA 성장 자산 동기화 — 기능 인벤토리·growth(약점프로필/학습큐)·일화기억·장기기억·회의록 원문
This commit is contained in:
+201
@@ -0,0 +1,201 @@
|
||||
---
|
||||
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 적용 패턴 정리 |
|
||||
Reference in New Issue
Block a user