시스템이 부르는 쓰기가 유스케이스 계약 밖에 있다. fileserver 정리·맞추기, 알림 claim·발송·lease 회복·맞추기·provider event replay는 capability도 트랜잭션 선언도 없는 서비스를 worker가 바로 부르고, 그 worker와 조립은 outbound adapter 안에 있다. 알림 운영자 연산 넷은 permission 없이 서비스 하나에 모여 있고 재시도 시각은 상수다. web stream bridge는 outbound가 구현한 replay 포트를 바로 읽는다. fileserver 관리 HTTP 기본값은 controller가 정한다. 고른 방법: 시스템 쓰기는 @SystemInvoked 유스케이스로 나누고 composition worker 설정이 new로 만든다(bean 아님). 알림 worker와 fileserver 정리 조립은 composition으로 옮기고, 맞추기의 재시도·포기 시점은 유스케이스가 정한다. 운영자 연산은 platform.admin의 유스케이스 클래스 넷과 notification-admin:* permission이다(port.in 인터페이스는 port.in과 admin의 cycle을 만들어 두지 않는다). replay 읽기는 조회 유스케이스 둘을 거치고 포트는 LiveEventReplayQueryPort로 이름을 바꾼다. 아키텍처 규칙 둘: 사용자 전송은 저장·id 포트를 쥐지 못하고, inbound는 application 서비스·coordinator를 interface로도 쥐지 못한다. 재시도 시각은 설정, 관리 기본값은 command 팩터리다. 재시도 시각의 규칙은 policy의 값 RetryTiming 하나가 갖고 설정은 그 값을 만든다. retry·routing 값들은 서버가 만드는 값이라 잘못된 값을 IllegalStateException으로 거절한다(manual 06). 모듈 기본값이 role notification-admin에 운영자 permission 넷을 준다(fileserver의 ROLE_FILE_ADMIN과 같다). 버린 대안: 서비스에 @UseCaseCapability만 달기(사용자와 시스템이 같은 진입점을 나눠 써서 권한 규칙이 막지 못한다), 운영자 서비스 삭제, 설정에서 policy를 만들어 버리며 검증하기(규칙이 바뀐 policy bean과 상관없이 남는다). 위험·한계: 공개 타입·생성자·bean 이름·아키텍처 규칙이 바뀐다. 파생 서비스가 할 일은 docs/upgrade/2026-11-round9-application.md 1~3·5·6행이다. claim·fence 커밋 위에 쌓았다. 검증: PR 본문의 desktop 결과. Refs: RR9-05-06, RR9-05-07, RR9-05-08, RR9-05-10, RR9-05-19 BREAKING CHANGE: NotificationAdminService·NotificationAdminApplicationService가 없어지고 운영자 연산은 platform.admin의 RedriveDeliveryUseCase 등이다(permission notification-admin:*). 알림 worker가 composition:notification-platform으로 옮기고 ReconciliationJobWorker·ProviderEventReplayWorker는 유스케이스가 됐다. MessagingReplayBridge 생성자가 조회 유스케이스를 받고 LiveEventReplayPort는 LiveEventReplayQueryPort다. 사용자 전송이 저장·id 포트나 application 서비스 interface를 쥐면 architectureTest가 실패한다. 운영자 요청 record 이름이 *Request로 바뀌고 DefaultNotificationRetryPolicy 생성자가 RetryTiming을 받는다. RetryBackoff·RetryBudget·RetryContext·RetryDecision.RetryAfter·RouteCandidate·RoutingContext·RoutingDecision·EligibilityResult가 잘못된 값에 IllegalStateException을 던진다.
14 KiB
application-core — 애플리케이션 유스케이스
등록 정보
- 모듈 ID:
application-core - Gradle 경로:
:application-core - 이 모듈만 시험(Gradle 경로에서 나온 명령):
./gradlew :application-core:test --console=plain - 실행 기준: Java 21. 프레임워크 기준은 공용 버전 카탈로그(
gradle/libs.versions.toml)가 고정한 Spring Boot 4.x다. - registry 정본:
gradle/modules.json.
패키지 루트: dev.caskeleton.application.
코드 주석에서 덜어낸 설계 결정의 근거는 README.md 가 모아둔다 (이 문서는 모듈 규칙 SSOT).
책임 (Responsibility)
- 유스케이스 inbound 포트(
CommandUseCase,QueryUseCase)와 그 command·query 계약. - 유스케이스가 의존하는 outbound 포트(
*Port인터페이스). - 애플리케이션 예외와 정책 타입.
- 포트를 거쳐 도메인 모델을 조율한다.
TransactionPort추상화로 애플리케이션 트랜잭션 경계를 가진다.CorrelationIdPort같은 포트로 프레임워크 없는 호출 문맥을 내놓는다. MDC 같은 실제 저장소는 어댑터가 가진다.- 프레임워크 없는 integration event 초안(semantic draft), 검증된 이벤트의 값 계약, 정확한 타입의 payload를 내놓는 SPI를 가진다. 메시징 semantic contract R1 경계까지만이다.
허용
:domain-core:shared-contract- Java 표준 라이브러리 타입.
금지 (Forbidden)
adapter-*구현 클래스.app-bootstrap.- controller의 요청·응답 DTO.
- JPA 엔티티와 Spring Data repository.
- HTTP 상태, 전송 타입(
org.springframework.web..). org.springframework.transaction.annotation.Transactional(대신TransactionPort를 쓴다).org.springframework.context.ApplicationContext— 직접 의존 금지 (getBean(Class)같은 리플렉션식 우회는 ArchUnit 규칙APPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXT가 막는다). 문자열 키로 bean을 찾기,Class.forName(String),BeanFactory#getBeansOfType은 ArchUnit 정적 분석이 보지 못하는 곳이다. 코드 리뷰 체크리스트로 막는다.- Lombok(
lombok..) —domain-core에서도 금지다.application-core에서는 지금 Lombok이 계약 범위에 없다. 쓰려면 바이트코드가 불투명해지는 비용을 먼저 따진다. - 이 모듈 안의 영속 계층 트랜잭션 애너테이션은 종류를 가리지 않고 금지다.
- 진단 프레임워크(
org.slf4j,java.util.logging, Logback, Log4j, Micrometer). 진단 의도는 전용 outbound*Port로 나타내고, 어떻게 남길지는 어댑터가 정한다. - 메시징 provider·런타임 타입: 물리 topic, Kafka record나 metadata, JSON tree·raw JSON payload, serializer·schema validator 구현, 보안 토폴로지, publication epoch.
계약 타입
표와 자세한 계약은 README.md 「계약 타입」 절이다. 지킬 것:
- 구체 inbound 포트는
CommandUseCase나QueryUseCase를 상속하고, 그 구현은@UseCaseCapability를 단다(ArchUnitINBOUND_PORT_IMPLEMENTATIONS_DECLARE_CAPABILITY).
알림 (NOTIF-ADR-005)
알림 타입은 이 leaf에 하나도 없다. ..notification.platform..과
dev.caskeleton.application.notification 바로 아래의 단순한 NotificationPort, Notification,
NotificationChannel은 모두 leaf application-notification의 것이다. 패키지 접두어가 같은 것이
유일한 연결이다. R1 조율 타입은 2026-09-25에 지웠다.
이름 규칙 (Naming convention)
이 절이 저장소의 이름 규칙 정본이다. 기계로 볼 수 있는 행은 NamingConventionTest(app-bootstrap
architectureTest)가 강제한다. 나머지는 리뷰 규칙이고, 리뷰가 이 표와 대조한다. 새 기능은 「새 코드」
열을 따른다. 「이미 있는 예외」는 누가 실수로 따라 하지 않게 이름을 적어 둔 것이다.
| 역할 | 이름 | 위치 | 이미 있는 예외(따라 하지 않는다) |
|---|---|---|---|
| 유스케이스(inbound 포트 구현) | <Verb><Noun>UseCase, ArchUnit이 강제 |
기능의 application 패키지 |
*ApplicationUseCase(application-fileserver, application-notification), *Service(notification, fileserver) |
| command·query record | *Command / *Query |
그 유스케이스 옆 | — |
| 요청 값 record: command가 담는 호출자 요청 내용(호출자가 누구인지는 뺀 값), 또는 포트 인자 묶음 | *Request |
그것을 담는 command나 받는 포트 옆 | CreateUploadRequest·FinalizeUploadRequest(application-fileserver upload, command는 port.in), VerificationRequest(application-fileserver api.security, 포트는 upload), application-objectstorage의 request 패키지(포트는 port, leaf가 값 타입 패키지로 정했다) |
| aggregate 영속(aggregate 전체를 저장하고 돌려준다) | <Aggregate>Repository |
aggregate의 domain 패키지, 도메인이 가진다 | — |
| 애플리케이션이 가진 기술 저장소(outbox, 멱등성, operation 행) | <Thing>StorePort |
application 패키지 | *WritePort(옛 onboarding fixture, 지움) |
| aggregate가 아니라 projection을 돌려주는 읽기 모델 | <Thing>QueryPort |
application 패키지. projection만 돌려준다(ArchUnit) | — |
| 그 밖의 outbound 포트 | <Capability>Port |
application 패키지 | — |
| 서버가 정하는 id 생성 | <Aggregate>IdFactory extends IdFactory<<Aggregate>Id> |
domain 패키지. id record는 implements ResourceId<Self> |
DurableOperationIdFactory(durable operation id는 aggregate의 resource id가 아니라 IdFactory를 따르지 않는다), NotificationIdGeneratorPort(application-notification), UploadIdentifierPort(application-fileserver). 셋 다 사용자 전송이 쥐면 USER_TRANSPORTS_DO_NOT_HOLD_PERSISTENCE_OR_ID_PORTS가 막는다 |
| 설정 바인딩 | *Settings(운영) 또는 *Policy(인가·도메인 정책), ArchUnit이 강제 |
그것을 바인딩하는 leaf | — |
| Throwable | *Exception, ArchUnit이 강제 |
— | — |
| 포트의 계약 시험 키트 | 포트 소유자의 testFixtures에 둔 추상 <Port>Contract. fake의 시험과 각 어댑터의 시험이 상속한다 |
testFixtures | 값 타입 시험의 이름이 한때 *ContractTest였다. 지금은 *ValueTypesTest다 |
저장소의 한 줄 규칙: 도메인이 알아볼 만한 것을 저장하면 도메인의 Repository다. 애플리케이션에
필요한 배관이면 application의 StorePort다.
패키지 소유 (Package ownership)
표와 자세한 계약은 README.md 「패키지 소유 (Package ownership)」 절이다. 그 표가 템플릿 패키지 목록의 정본이다. 지킬 것:
- 업무 기능은 루트마다 바로 아래에 기능 하나당 패키지 하나다(
dev.caskeleton.application.<feature>,dev.caskeleton.domain.<feature>등).command·usecase·port하위 패키지를 두지 않는다. <feature>는 템플릿 패키지 이름이 아니다. 업무 코드를 템플릿 패키지에 넣지 않고, 템플릿 패키지는 기능 패키지를 import하지 않는다(NamingConventionTest).- 템플릿 패키지를 더하거나 이름을 바꾸거나 지우면 README 표와
TemplatePackageOwnership을 같은 변경에서 고친다.TemplatePackageOwnershipDocumentTest가 둘을 대조한다.
정해진 유스케이스 모양 (Canonical use case shape)
표와 자세한 계약은 README.md 「정해진 유스케이스 모양 (Canonical use case shape)」 절이다. 지킬 것:
- 유스케이스는 평범한 Java이고 final이 아니다(web 어댑터가 CGLIB proxy로
@RequiresPermission을 강제한다). 조립 루트가 bean으로 만든다. application-core는 DI 프레임워크에 스스로 등록하지 않는다. - 상태를 바꾸면
@RequiresPermission, 시스템만 부르면@SystemInvoked(reason = ...)를 달고 bean으로 두지 않는다. 시스템 호출자 목록의 정본은docs/manual/07-authorization.md「시스템이 부르는 쓰기」다. - 일은
TransactionPort로 감싼다(아래 「허용하는 트랜잭션 모양」).
허용하는 트랜잭션 모양 (Allowed transactional shapes)
| 유스케이스 모양 | transactionMode |
TransactionPort 호출 | 언제 |
|---|---|---|---|
| 쓰기 command | WRITE |
tx.inWrite(...) |
CommandUseCase의 기본. |
| 물리 루트 쓰기 command | WRITE |
tx.inRootWrite(...) |
바깥 트랜잭션이 없음을 증명하고 커밋 뒤에 결과를 내놓아야 하는 조율일 때만. |
| 읽기 전용 query | READ_ONLY |
tx.inRead(...) |
QueryUseCase의 기본. |
| outbox·감사·보상 | REQUIRES_NEW |
tx.inNew(...) |
유스케이스가 반드시 호출자와 따로 커밋해야 할 때만. |
NESTED와 NEVER 전파는 금지다.
inRootWrite는 action이나 PlatformTransactionManager를 부르기 전에 실제로 열린 바깥 트랜잭션을
반드시 거절한다. 루트 전용 동작을 REQUIRES_NEW로 흉내 내면 안 된다.
WRITE_REPOSITORY + WRITE 유스케이스의 직접 경계 적합성 규칙은 inWrite와 inRootWrite가 모두
만족한다. READ와 REQUIRES_NEW의 대응은 계속 서로 배타적이다.
콜백 시그니처 계약
TransactionPort 콜백은 Supplier<T> / Runnable이라 checked 예외를 던지지 못한다. Spring
TransactionCallback<T>의 제약과 같다. 도메인의 checked 예외는 RuntimeException 하위 클래스로
감싼다(DomainException extends RuntimeException). IOException은 UncheckedIOException으로
감싼다. SQLException은 Spring의 DataAccessException 계층이 자동으로 번역한다.
inNew 풀 크기 제약
inNew는 새 물리 JDBC 연결을 얻는다. 풀 크기는 반드시 다음을 만족한다.
hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1
금지: 많은 레코드를 도는 반복문 안에서 tx.inNew(...)를 부른다 — 풀이 바닥나고 교착이 생길
수 있다. 레코드를 inNew 호출 하나 안에서 묶어 처리하거나, 반복문을 트랜잭션 경계 밖으로 뺀다.
멱등성 (KEYED) — feature-rate-limit-idempotency-contract
표와 자세한 계약은 README.md 「멱등성 (KEYED) — feature-rate-limit-idempotency-contract」 절이다. 지킬 것:
- KEYED 유스케이스는 일을
IdempotencyExecutor로 감싼다. 원본Idempotency-Key는 이 계층에 들이지 않고IdempotencyScopeDigest만 받는다. - executor는
composition:idempotency가 만든다. 유스케이스나 서비스 설정에서 만들지 않는다. 운영에서 메모리 저장소는 금지다.
읽기·query 경로 (feature-application-query-bypass-contract)
읽기 쪽에는 똑같이 유효한 모양이 둘 있다. 읽기마다 고르고, 하나를 강요하지 않는다.
| 모양 | 돌려주는 것 | 언제 | 어떻게 |
|---|---|---|---|
| aggregate를 거쳐서(단순 읽기의 기본) | *Repository 포트로 받은 도메인 aggregate |
읽기 모양 == 쓰기 aggregate 이고 aggregate가 최소 불변식 경계일 때(지연 컬렉션이 필요 없음) | QueryUseCase → repository 포트 → Order |
| projection (CQRS-lite) | *QueryPort로 받은 애플리케이션 계층 projection DTO |
읽기 모양 ≠ 쓰기, 또는 aggregate 수화·지연 컬렉션 join을 건너뛰려 할 때 | QueryUseCase → *QueryPort → OrderSummary(record). query는 JPQL SELECT new / JdbcTemplate |
- 순수성 가드레일(core, 기계로 강제): 단순 이름이
QueryPort로 끝나는 읽기 포트는 반드시 애플리케이션 계층 projection DTO만 돌려준다 — 도메인 aggregate, JPA 엔티티, web 타입은 제네릭 타입 인자를 거쳐서도(List<DomainType>) 안 된다. ArchUnitQUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES가 강제한다. projection 사용 자체는 강요된 기본이 아니라 선택이다. - 엄격한 절차: 모든 읽기는
QueryUseCasebean을 거친다. web → 읽기 포트로 바로 가는 얇은 경로는 없다. 그런 경로는 필수인@UseCaseCapability적합성 검사를 건너뛴다. - 트랜잭션: 읽기의 기본은
TransactionPort.inRead다. 트랜잭션 없는(autocommit) 읽기는spring.jpa.open-in-view=false가 확인됐고 그리고 읽기가 projection만 쓰고(지연 접근 없음) 그리고 문장 하나일 때만 고를 수 있다. 아니면inRead를 쓴다. - capability: repository를 쓰는 projection 읽기도
repositoryAccess = READ_REPOSITORY다. 「projection이냐 aggregate냐」는 돌려주는 모양 축이고, repository 접근 수준 축과 따로다 — 새 enum이 없다. outbound HTTP 읽기(repository 없음)는RepositoryAccess.NONE이다. - 물리적으로 따로 둔 읽기 저장소를 쓰는 완전한 CQRS는 범위 밖이다. 올려서 정할 일이다.
ArchUnit 가드레일(강제됨)
APPLICATION_DOES_NOT_DEPEND_ON_ADAPTERS_OR_TRANSPORTAPPLICATION_DOES_NOT_USE_SPRING_TRANSACTIONAL_ANNOTATIONAPPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXTAPPLICATION_HAS_NO_DIAGNOSTIC_FRAMEWORKINBOUND_PORT_IMPLEMENTATIONS_END_WITH_USE_CASEINBOUND_PORT_IMPLEMENTATIONS_DECLARE_CAPABILITYQUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES(*QueryPort반환 순수성)
테스트
- fake·in-memory 포트로 유스케이스 흐름을 검증한다. Spring context를 띄우지 않는다.
- 포트마다 fake 하나와 추상 계약 테스트(
*Contract)를 이 모듈 testFixtures에 둔다. 작성 규칙은.claude/rules/java-tests.md다.
./gradlew :application-core:test
./gradlew :app-bootstrap:architectureTest
위 메시징 타입은 semantic contract R1까지만 세운다. JSON Schema 검증, Kafka 발행, durable outbox 영속, 그 밖의 메시징 R2 capability를 주장하지 않는다.