Functorium 가이드

비즈니스 로직과 기술 코드가 뒤섞여 변경이 어렵고, 테스트하기 힘든 경험을 해본 적이 있나요? Functorium은 DDD 전술적 설계와 함수형 프로그래밍을 결합하여 관심사를 명확히 분리하고, 프로젝트에 필요한 아키텍처·구현 패턴·관측성까지 모든 가이드를 제공합니다.

들어가며

개발 현장에서 이런 고민을 마주한 적이 있을 것입니다.

비즈니스 규칙이 인프라 코드 사이에 흩어져 변경할 때마다 어디를 수정해야 할지 파악하기 어렵지 않았나요?
도메인 로직을 단위 테스트하려면 데이터베이스나 외부 서비스를 함께 준비해야 하는 부담을 느낀 적이 없나요?
프로젝트가 커질수록 레이어 간 의존성이 꼬여 한 곳을 고치면 다른 곳이 깨지는 악순환을 경험하지 않았나요?

Functorium은 이러한 문제를 DDD 전술적 설계 패턴으로 관심사를 분리하고, 함수형 프로그래밍으로 부수효과를 통제하여 해결합니다.

이 가이드에서 다루는 내용

내부 아키텍처 설계 원칙 — 관심사 분리, 레이어 구조, 의존성 방향의 근거
DDD 전술적 설계 빌딩블록 — Value Object, Entity, Aggregate, Domain Event, Specification
Application/Adapter 계층 구현 — Use Case, Port, Adapter, Pipeline, DI
테스트 전략 — 단위 테스트, 통합 테스트, 테스트 라이브러리
관측성(Observability) — 로깅, 메트릭, 트레이싱 사양과 구현

Functorium 가이드는 WHY → WHAT → HOW 순서로 구성되어, 각 개념이 왜 필요한지 이해한 후 구현으로 나아갈 수 있도록 안내합니다.

DDD 전술적 설계와 Functorium

Functorium은 DDD 전술적 설계 패턴과 함수형 프로그래밍을 결합한 프레임워크입니다. 가이드 문서는 DDD 빌딩블록 순서로 배치되어 있으며, 각 문서는 WHY → WHAT → HOW 구조를 따릅니다.

학습 로드맵

[00] 00-writing-guide.md ─── 문서 작성 가이드

Architecture
├── [00] 00-architecture-design-principles.md ─── 내부 아키텍처 설계 원칙
├── [01] 01-project-structure.md ─── 프로젝트 구조
├── [02] 02-solution-configuration.md ─── 솔루션 구성
├── [02b] 02b-ci-cd-and-versioning.md ─── CI/CD 워크플로우 및 버전 관리
└── [03] 03-dotnet-tools.md ─── .NET 도구

[04] 04-ddd-tactical-overview.md ─── DDD 전술적 설계 개요
│
├── Domain Layer
│   ├── [05a] 05a-value-objects.md ─── 값 객체 (핵심 개념·검증·구현 패턴)
│   ├── [05b] 05b-value-objects-validation.md ─── 값 객체 (열거형·실전·FAQ)
│   ├── [05c] 05c-union-value-objects.md ─── 값 객체: Union 타입
│   │   └── [06a] 06a-aggregate-design.md ─── Aggregate 설계 (WHY + WHAT)
│   │       ├── [06b] 06b-entity-aggregate-core.md ─── Entity/Aggregate 핵심 패턴 (HOW)
│   │       └── [06c] 06c-entity-aggregate-advanced.md ─── Entity/Aggregate 고급 패턴
│   │           └── [07] 07-domain-events.md ─── 도메인 이벤트
│   ├── [08a] 08a-error-system.md ─── 에러 시스템: 기초와 네이밍
│   ├── [08b] 08b-error-system-domain-app.md ─── 에러 시스템: Domain/Application 에러
│   ├── [08c] 08c-error-system-adapter-testing.md ─── 에러 시스템: Adapter 에러와 테스트
│   ├── [09] 09-domain-services.md ─── 도메인 서비스
│   └── [10] 10-specifications.md ─── Specification 패턴
│
├── Application Layer
│   └── [11] 11-usecases-and-cqrs.md ─── Use Case와 CQRS
│
├── Adapter Layer
│   ├── [12] 12-ports.md ─── Port 정의
│   ├── [13] 13-adapters.md ─── Adapter 구현
│   ├── [14a] 14a-adapter-pipeline-di.md ─── Pipeline, DI
│   ├── [14b] 14b-adapter-testing.md ─── 단위 테스트
│   └── [14c] 14c-repository-query-implementation-guide.md ─── Repository & Query 구현 가이드
│
├── Testing
│   ├── [15] 15a-unit-testing.md ─── 단위 테스트
│   ├── [15b] 15b-integration-testing.md ─── 통합 테스트
│   └── [16] 16-testing-library.md ─── 테스트 라이브러리
│
├── DTO 전략
│   └── [17] 17-dto-strategy.md ─── DTO 전략
│
├── Observability
│   ├── [18a] → spec/08-observability.md ─── 사양 (spec으로 이동)
│   ├── [18b] 18b-observability-naming.md ─── 네이밍
│   ├── [19] 19-observability-logging.md ─── 로깅
│   ├── [20] 20-observability-metrics.md ─── 메트릭
│   └── [21] 21-observability-tracing.md ─── 트레이싱
│
├── 진단
│   └── [22] 22-crash-diagnostics.md ─── 크래시 덤프
│
└── Appendix
    ├── [A01] A01-vscode-debugging.md ─── VSCode 디버깅
    ├── [A02] A02-git-reference.md ─── Git 참조
    ├── [A03] A03-response-type-evolution.md ─── FinResponse 타입 진화
    └── [A04] A04-architecture-rules-coverage.md ─── 아키텍처 규칙 검증 커버리지

빠른 참조 (작업별 가이드 바로가기)

프로젝트 시작하기

새 서비스를 시작할 때 프로젝트 구조, 빌드 구성, CI/CD를 어떻게 잡을지 안내합니다.

하고 싶은 작업	참조 문서
아키텍처 설계 원칙 이해하기	00-architecture-design-principles.md
프로젝트 구성/폴더 구조	01-project-structure.md
솔루션 구성 파일/빌드 스크립트	02-solution-configuration.md
CI/CD 워크플로우 및 버전 관리	02b-ci-cd-and-versioning.md
도구 사용법 (커버리지/스냅샷/ER 다이어그램)	03-dotnet-tools.md

도메인 모델 구축

비즈니스 개념을 코드로 옮기는 과정 — 값 객체로 시작해 Aggregate로 묶고, 이벤트와 에러로 상호작용을 표현합니다.

하고 싶은 작업	참조 문서
DDD 빌딩블록 개요/네이밍/용어집	04-ddd-tactical-overview.md
값 객체 만들기 (검증, 동등성)	05a-value-objects.md
열거형(SmartEnum) 패턴	05b-value-objects-validation.md
Union 값 객체 (Discriminated Union)	05c-union-value-objects.md
Aggregate 경계 설계하기	06a-aggregate-design.md
Entity/Aggregate 구현 (생성 패턴 포함)	06b-entity-aggregate-core.md
Cross-Aggregate 관계, 부가 인터페이스	06c-entity-aggregate-advanced.md
도메인 이벤트 정의/발행/핸들러	07-domain-events.md
에러 타입 정의 및 테스트	08a → 08b → 08c
도메인 서비스 만들기	09-domain-services.md
Specification 만들기	10-specifications.md

Application 계층

도메인 모델을 외부에 노출하는 유스케이스를 정의하고, Command/Query 책임을 분리합니다.

하고 싶은 작업	참조 문서
Usecase 만들기 (CQRS)	11-usecases-and-cqrs.md
DTO 전략/재사용 규칙	17-dto-strategy.md

Adapter 계층

도메인이 외부 세계와 만나는 경계 — Port로 계약을 정의하고 Adapter로 구현합니다.

하고 싶은 작업	참조 문서
Port 인터페이스 정의하기	12-ports.md
Adapter 구현 (Repository, API, Messaging)	13-adapters.md
Pipeline/DI 등록, Options 패턴, 캐싱	14a-adapter-pipeline-di.md
Adapter 단위 테스트	14b-adapter-testing.md
Repository & Query 구현 (페이지네이션, Dapper)	14c-repository-query-implementation-guide.md

테스트

도메인 순수성이 테스트를 단순하게 만듭니다. 단위 테스트부터 통합 테스트까지의 전략입니다.

하고 싶은 작업	참조 문서
단위 테스트 (명명, AAA, MTP)	15a-unit-testing.md
통합 테스트 (HostTestFixture)	15b-integration-testing.md
테스트 라이브러리 (로그/아키텍처/소스생성기/Job)	16-testing-library.md
아키텍처 규칙 커버리지 매트릭스	A04-architecture-rules-coverage.md

관측성과 운영

개발과 운영의 언어를 통일합니다. 구조화된 로깅, 메트릭, 트레이싱 사양과 크래시 진단입니다.

하고 싶은 작업	참조 문서
Observability 사양	08-observability.md
크래시 덤프 설정/분석	22-crash-diagnostics.md

코드 예시 규칙

구분	형식	설명
규칙 구현 코드	실제 C# 코드	컴파일 가능한 수준의 코드 (타입, 메서드, 패턴 예시)
아키텍처 흐름 설명	pseudo-code 허용	반드시 `pseudo-code` 또는 `개념 코드` 라벨을 코드 블록 앞에 표기
코드 블록 언어 태그	항상 명시	```csharp, ```xml, ```bash, ```promql 등

문서 전체 목록

아키텍처

관심사 분리, 레이어 구조, 의존성 방향의 근거를 먼저 이해하고, 프로젝트 폴더 구성과 빌드 구성으로 구체화합니다. 새 서비스를 만들 때 가장 먼저 참조하는 영역입니다.

문서	설명
00-architecture-design-principles.md	내부 아키텍처 설계 원칙 (관심사 분리, 레이어 구조, 의존성 방향)
01-project-structure.md	서비스 프로젝트 구성 (폴더, 네이밍, 의존성)
02-solution-configuration.md	솔루션 루트 구성 파일 및 빌드 스크립트
02b-ci-cd-and-versioning.md	CI/CD 워크플로우 및 버전 관리 (GitHub Actions, NuGet 패키지, MinVer, 버전 제안 커맨드)
03-dotnet-tools.md	.NET 도구 가이드 (CLI 도구, 소스 생성기, 파일 기반 스크립트)

DDD 전술적 설계 (번호순 학습 경로)

비즈니스 규칙이 인프라에 의존하지 않도록 순수한 도메인 모델을 구축합니다. 값 객체로 불변 검증을 보장하고, Aggregate로 트랜잭션 경계를 설정하며, 도메인 이벤트로 느슨한 결합을 실현합니다.

번호	문서	설명
04	04-ddd-tactical-overview.md	DDD 전술적 설계 개요, 빌딩블록 맵, Functorium 타입 매핑
05a	05a-value-objects.md	값 객체 (핵심 개념, 기반 클래스, 검증 시스템, 구현 패턴)
05b	05b-value-objects-validation.md	값 객체 (열거형 패턴, 실전 예제, Application 검증, FAQ)
05c	05c-union-value-objects.md	값 객체: Union 타입 (Discriminated Union, 상태 전이, Match/Switch)
06a	06a-aggregate-design.md	Aggregate 설계 (WHY + WHAT: 설계 규칙, 경계 설정, 안티패턴)
06b	06b-entity-aggregate-core.md	Entity/Aggregate 핵심 패턴 (HOW: 클래스 계층, ID, 생성 패턴, 이벤트)
06c	06c-entity-aggregate-advanced.md	Entity/Aggregate 고급 패턴 (Cross-Aggregate 관계, 부가 인터페이스, 실전 예제)
07	07-domain-events.md	도메인 이벤트 정의, 발행, 핸들러 구현
08a	08a-error-system.md	에러 시스템: 기초와 네이밍 (WHY, Fin 패턴, 네이밍 규칙)
08b	08b-error-system-domain-app.md	에러 시스템: Domain/Application 에러 (Domain/Application/Event 에러 정의와 테스트)
08c	08c-error-system-adapter-testing.md	에러 시스템: Adapter 에러와 테스트 (Adapter 에러, Custom 에러, 테스트 모범 사례, 체크리스트)
09	09-domain-services.md	도메인 서비스 (교차 Aggregate 순수 로직, IDomainService)
10	10-specifications.md	Specification 패턴 (비즈니스 규칙 캡슐화, 조합, Repository 통합)

Application 계층

도메인 모델을 애플리케이션 경계에 노출하는 유스케이스를 정의합니다. CQRS로 쓰기와 읽기 책임을 분리하고, DTO로 레이어 간 데이터 전달 규칙을 명확히 합니다.

번호	문서	설명
11	11-usecases-and-cqrs.md	Use Case 구현 (CQRS Command/Query)
17	17-dto-strategy.md	DTO 전략 (레이어별 소유권, 재사용 규칙, 변환 패턴)

Adapter 계층

도메인이 외부 세계와 만나는 경계입니다. Port로 계약을 정의하고 Adapter로 구현하며, Pipeline과 DI로 조립합니다. Repository, 외부 API, 메시징 등 구체적인 인프라 구현이 이 영역에 위치합니다.

번호	문서	설명
12	12-ports.md	Port 아키텍처, IObservablePort 계층, Port 정의 규칙
13	13-adapters.md	Adapter 구현 (Repository, External API, Messaging, Query)
14a	14a-adapter-pipeline-di.md	Pipeline 생성, DI 등록, Options 패턴
14b	14b-adapter-testing.md	Adapter 단위 테스트, E2E Walkthrough
14c	14c-repository-query-implementation-guide.md	Repository & Query 구현 가이드

테스트

도메인 레이어의 순수성이 단위 테스트를 단순하게 만들고, Adapter 분리가 통합 테스트의 경계를 명확하게 합니다. Functorium.Testing 라이브러리는 아키텍처 규칙 검증, 구조화된 로그 테스트, 소스 생성기 테스트를 위한 도구를 제공합니다.

문서	설명
15a-unit-testing.md	단위 테스트 규칙 (명명, AAA 패턴, MTP 설정)
15b-integration-testing.md	통합 테스트 (HostTestFixture, 환경 설정)
16-testing-library.md	Functorium.Testing 라이브러리 (로그/아키텍처/소스생성기/Job 테스트)

Observability

개발과 운영이 같은 언어로 소통할 수 있도록 관측성 사양을 정의합니다. Field/Tag 네이밍부터 구조화된 로깅, 메트릭, 분산 트레이싱까지 일관된 관측성 체계를 구축합니다.

문서	설명
08-observability.md	Observability 사양 (Field/Tag, Meter, 메시지 템플릿)
18b-observability-naming.md	Observability 네이밍 가이드 (코드, Logger 메서드)
19-observability-logging.md	Observability 로깅 상세
20-observability-metrics.md	Observability 메트릭 상세
21-observability-tracing.md	Observability 트레이싱 상세

진단

프로덕션 환경의 비정상 종료를 사후 분석하기 위한 크래시 덤프 수집과 분석 가이드입니다.

문서	설명
22-crash-diagnostics.md	크래시 덤프 핸들러 설정 및 분석 가이드

Appendix

문서	설명
A01-vscode-debugging.md	VSCode 디버깅 및 개발 환경 설정
A02-git-reference.md	Git 명령어 참조 및 Git Hooks
A03-response-type-evolution.md	FinResponse 타입 진화 기록
A04-architecture-rules-coverage.md	아키텍처 규칙 검증 커버리지 매트릭스

리뷰

문서	설명
dto-strategy-review.md	DTO 매핑 전략 리뷰 (DDD & Hexagonal Architecture 관점)

기타

문서	설명
book-writing-guide.md	서적 집필 가이드
00-writing-guide.md	문서 작성 가이드 (가이드 문서 작성 규칙)