| name | spring-multimodule-implement |
| description | yogieat-server 멀티모듈 클린 아키텍처의 구현 가이드. 새 도메인이나 기능을 추가할 때 어떤 모듈에 어떤 파일을 어떤 패턴으로 만들어야 하는지 안내한다. Spring Boot 멀티모듈, 클린 아키텍처, domain Record, Entity 매핑, Repository 인터페이스 패턴 등을 다룬다. |
Spring Multi-Module Implementation Guide
yogieat-server의 멀티모듈 클린 아키텍처에서 코드를 구현할 때 따르는 가이드.
아키텍처 흐름
Controller (apps:api)
↓ Request DTO
Facade (apps:domain) — @Transactional 경계
↓ Command Record
Service (apps:domain) — 비즈니스 로직
↓ Domain Record
Repository Interface (apps:domain) ← implements ← CoreRepository (storage:db-core)
↓ ↓
Domain Record Entity ↔ Domain (toDomain/from)
모듈별 파일 생성 레시피
apps/domain 모듈
apps:domain은 프레임워크에 의존하지 않는 순수 비즈니스 로직 모듈이다.
허용 의존성: spring-context, spring-tx, spring-web, jackson-databind, slf4j-api만 가능.
JPA, QueryDSL, 외부 API 클라이언트 import는 절대 금지.
| 구성요소 | 패키지 | 네이밍 | 타입 |
|---|
| Domain model | com.yogieat.{domain}.domain | {Domain} | Java Record |
| Value object | com.yogieat.{domain}.domain.value | 도메인에 맞게 | Enum 또는 Record |
| Command | com.yogieat.{domain}.service | {Domain}Command | Record (Nested) |
| Result | com.yogieat.{domain}.domain.result | {Domain}Result | Record (Nested) |
| Repository | com.yogieat.{domain}.service | {Domain}Repository | Interface |
| Service | com.yogieat.{domain}.service | {Domain}Service | @Service class |
| Validator | com.yogieat.{domain}.service | {Domain}Validator | @Component class |
| API Facade | com.yogieat.{domain}.service | {Domain}Facade | @Service class |
| Admin Facade | com.yogieat.{domain}.facade | {Domain}AdminFacade | @Service class |
storage/db-core 모듈
storage:db-core는 JPA Entity와 Repository 구현을 담당한다.
apps:domain의 도메인 모델(Record)만 import 가능.
| 구성요소 | 패키지 | 네이밍 | 타입 |
|---|
| Entity | com.yogieat.datasource.db.core.{domain} | {Domain}Entity | @Entity class |
| JPA Repository | com.yogieat.datasource.db.core.{domain} | {Domain}JpaRepository | Spring Data Interface |
| Core Repository | com.yogieat.datasource.db.core.{domain} | {Domain}CoreRepository | @Repository class |
apps/api 모듈
| 구성요소 | 패키지 | 네이밍 | 타입 |
|---|
| Controller | com.yogieat.controller.v1.{domain} | {Domain}Controller | @RestController |
| Request DTO | com.yogieat.controller.v1.{domain}.request | {Action}{Domain}Request | Record |
| Response DTO | com.yogieat.controller.v1.{domain}.response | {Action}{Domain}Response | Record |
구현 순서
반드시 이 순서를 따른다. 의존 방향이 안쪽(domain)에서 바깥쪽(api)으로 흐르기 때문이다.
- Domain model (Record) — 핵심 도메인 객체 정의
- Value objects — Enum, 값 객체
- Command/Result — 레이어 간 데이터 전달 객체
- Repository interface — 도메인 레이어의 데이터 접근 계약
- Validator — 비즈니스 규칙 검증
- Service — 비즈니스 로직
- Facade — 트랜잭션 경계 + 서비스 조합
- Entity — JPA 엔티티 (
toDomain() + from() 필수)
- JPA Repository — Spring Data 인터페이스
- Core Repository — Repository 인터페이스 구현
- Controller + Request/Response DTO
- Tests
핵심 패턴 상세
상세 코드 패턴은 references/patterns.md를 참조하라. 구현 시 반드시 해당 패턴을 읽고 기존 코드와 일관되게 작성한다.
테스트 작성 규칙
- Given-When-Then 패턴
@DisplayName은 한국어로 작성 (예: "모임 생성 시 accessKey가 자동 생성된다")- DatabaseCleaner로 테스트 격별리
- Fixture 패턴 사용
- 동시성 테스트는
@RepeatedTest 또는 CountDownLatch 활용
