JFoundry 사용하기
목적
이 스킬은 JFoundry에서 비즈니스 애플리케이션을 구축할 때 프레임워크가 의도한 아키텍처를 벗어나지 않도록 사용합니다. 이 스킬은 애플리케이션 프로젝트를 위한 것이며, JFoundry 프레임워크 내부를 변경하기 위한 것이 아닙니다.
사용자가 명시적으로 Onion을 선택하지 않는 한 새로운 Java 21 Maven 프로젝트는 헥사고날 아키텍처(Hexagonal Architecture)를 기본값으로 사용합니다. 런타임 프레임워크를 Spring Boot로 기본 설정하지 마십시오; 사용자가 Spring Framework, Spring Boot 또는 Spring 관련 스타터를 선택한 경우에만 Spring을 선택하십시오. 번들 템플릿을 먼저 복사한 후 이름과 패키지를 조정하는 것을 선호합니다.
첫 사용 워크플로우
- 프로젝트 형태를 확인합니다: 단일 애플리케이션 모듈, 멀티 모듈 Maven 앱, 또는 분리된 도메인/애플리케이션/인프라 모듈. 일반 DDD 프로젝트에는 멀티 모듈 Maven을 선호합니다.
- 하나의 기본 아키텍처 스타일을 선택합니다. 새로운 비즈니스 프로젝트에는 헥사고날을 선호하고, 사용자가 요청하거나 코드베이스가 이미 사용 중인 경우에만 Onion을 선택합니다. 동일한 ArchUnit 분석 범위 내에서 헥사고날과 Onion을 혼합하지 마십시오.
references/dependencies.md를 읽고 런타임별 BOM을 선택한 후assets/templates/maven/에서 일치하는 Maven 템플릿 스니펫을 복사합니다.references/architecture.md를 읽고assets/templates/structure/에서 일치하는 패키지 구조를 복사합니다.assets/templates/java/에서 하나의 아키텍처 테스트 템플릿을 복사하고PACKAGE_NAME을 대체한 후 비즈니스 프로젝트의 테스트 소스 세트에 추가합니다.- 애그리게이트 리포지토리, 읽기 측 포트, 쿼리 포트, 조회 포트, 읽기 모델 또는 유지보수 포트를 만들기 전에
references/repository-and-ports.md를 읽습니다. AggregateData,DataConverter, MyBatis-Plus 데이터 객체 또는 MapStruct 컨버터를 구현하기 전에references/persistence-data-converters.md를 읽습니다.- 프로젝트에 안정적인 외부 이벤트 발행 또는 멱등성 메시지 소비가 필요한 경우에만
references/outbox-inbox.md를 읽습니다. - 가장 작은 관련 Maven 검증 명령(보통
mvn test) 또는 모듈 범위의mvn -pl <module> test를 실행합니다.
핵심 규칙
- 도메인 코드에 Spring, MyBatis, 영속성 모델, 메시지 브로커 클라이언트, 프레임워크 수명 주기 API를 포함시키지 마십시오.
- 규칙과 불변 조건이 의미 있는 경우 도메인에서 비즈니스 동작을 모델링하고, 복잡도가 낮은 영역에서는 단순한 CRUD 또는 트랜잭션 스크립트를 사용하십시오.
- 중요한 도메인 동작의 경우 코딩 전에 애그리게이트, 명령, 불변 조건, 이벤트, 리포지토리 및 읽기 측 포트 가정을 확인하고, 열린 도메인 질문을 숨기지 마십시오.
- Spring Boot 스타터는 부트/런타임 어셈블리 모듈에만 배치하고, 도메인 또는 애플리케이션 모듈에는 절대 배치하지 마십시오.
- 유스 케이스 오케스트레이션과 트랜잭션 중심 워크플로우는 애플리케이션 계층에 배치하십시오.
- 외부 요구사항을 2차 포트(secondary ports)로 표현하십시오. MyBatis, JPA, Redis, HTTP 클라이언트, MQ 클라이언트 및 기타 기술 세부 사항은 인프라 어댑터에 배치하십시오.
- JFoundry 헥사고날 또는 Onion 프로젝트에서 컨트롤러, 메시지 리스너, CLI 명령, 스케줄러와 같은 1차 어댑터는 2차 어댑터가 아닌 1차 포트 또는 애플리케이션 서비스를 호출해야 합니다.
- 애그리게이트 수명 주기와 명령 측 애그리게이트 로딩에는 애그리게이트 리포지토리를 사용하십시오. 비 애그리게이트 읽기의 경우 읽기 측 포트를 선호하고, 프로젝트에 도움이 될 때만 조회/읽기 모델/유지보수 역할로 분할하십시오.
- 영속성 데이터 컨버터를 인프라 로컬로 유지하십시오.
INSTANCE가 있는 MapStruct@Mapper인터페이스를 선호하고,toEntity(...)를 명시적으로 작성하며 애그리게이트restore(...)를 호출하십시오. - 아웃박스는 외부 프로세스나 브로커에 안정적으로 발행할 때만 활성화하십시오. 이벤트가 프로세스 내에 머무를 때는 로컬 도메인 이벤트 디스패치를 사용하십시오.
- 인박스는 소비자가 중복 전달을 안전하게 처리해야 할 때만 활성화하십시오.
- ArchUnit 테스트는 초기에 추가하십시오. 이는 프로젝트 스켈레톤의 일부이며, 늦은 정리 작업이 아닙니다.
번들 템플릿
템플릿을 기억에서 다시 작성하지 말고 복사하십시오:
assets/templates/java/HexagonalArchitectureTest.javaassets/templates/java/OnionSimpleArchitectureTest.javaassets/templates/maven/dependency-management-core.xmlassets/templates/maven/dependency-management-spring.xmlassets/templates/maven/domain-module-dependencies.xmlassets/templates/maven/application-module-dependencies.xmlassets/templates/maven/infrastructure-mybatis-plus-dependencies.xmlassets/templates/maven/architecture-test-dependencies.xmlassets/templates/maven/spring-boot-app-dependencies.xmlassets/templates/maven/spring-boot-mybatis-plus-dependencies.xmlassets/templates/maven/outbox-dependencies.xmlassets/templates/maven/outbox-mybatis-plus-dependencies.xmlassets/templates/maven/inbox-dependencies.xmlassets/templates/maven/inbox-mybatis-plus-dependencies.xmlassets/templates/maven/broker-dependencies.xmlassets/templates/structure/hexagonal-package-structure.txtassets/templates/structure/onion-simple-package-structure.txt
PACKAGE_NAME 및 JFOUNDRY_VERSION과 같은 플레이스홀더를 대체하십시오. 선택적 스니펫은 선택 사항으로 유지하십시오. 유스 케이스에 필요하지 않으면 Outbox, Inbox, MyBatis-Plus 또는 브로커 스타터를 추가하지 마십시오.
참조 라우팅
references/first-use.md는 사용자가 새 프로젝트를 시작하거나 이 스킬을 호출하는 방법을 물을 때 읽습니다.references/architecture.md는 패키지 역할, 어노테이션, 의존성 방향 및 아키텍처 스타일 선택을 위해 읽습니다.references/dependencies.md는 스타터 선택 및 Maven 스니펫을 위해 읽습니다.references/repository-and-ports.md는 영속성, 애그리게이트 리포지토리, 읽기 모델 또는 쿼리 포트를 모델링하기 전에 읽습니다.references/persistence-data-converters.md는DataConverter구현, 영속성 데이터 객체 또는 MapStruct 매핑 규칙을 작성하기 전에 읽습니다.references/outbox-inbox.md는 이벤트 외부화, 브로커 어댑터, Outbox 테이블, 디스패처 또는 소비자 멱등성을 추가하기 전에 읽습니다.references/testing.md는 아키텍처 테스트를 추가하거나 변경하기 전에 읽습니다.
일반적인 첫 프롬프트
새 프로젝트를 안내할 때는 기본 패키지, 프로젝트/모듈 형태, 런타임 스택, 영속성 선택 및 외부 메시징 필요 여부를 먼저 질문하십시오. 사용자가 선호하는 것이 없으면 다음을 진행하십시오:
- Java 21
- Maven
- 아직 결정되지 않은 런타임 프레임워크
- 헥사고날 아키텍처
jfoundry-dependenciesBOMjfoundry-domain-starterjfoundry-application-starterJFoundryRules.hexagonalStrict()및JFoundryRules.jmoleculesDdd()
새 비즈니스 프로젝트를 위한 제안 사용자 프롬프트:
Use $use-jfoundry to create the initial architecture for a new Java 21 business project.
Base package: com.example.order
Project shape: multi-module Maven
Runtime: undecided
Persistence: MyBatis-Plus
Messaging: Kafka later, not in the initial skeleton
Architecture: default unless you need to choose
세부 정보가 누락된 경우 간결한 질문을 하나 하거나 위의 기본값을 선택해도 위험이 낮을 때 해당 기본값을 진행하십시오.