Files
clean-architecture-backend-…/docs/manual/02-new-feature.md
T
DongHyeonka 1400dc1506 feat!: 남은 리뷰 발견을 고치고 개발 매뉴얼과 기능 생성 명령을 더한다
문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지
크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의
500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본
(TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR
테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로
만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져
객체 저장소 lane이 돌지 않았다.

방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은
결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD,
S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한).
MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자·
mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고,
scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과
왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와
결정은 리뷰 README 14절에 있다.

위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서
H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC·
WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체,
샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개
(composition:durable-operation, adapter:inbound:messaging)와 새
마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1,
grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면
실패한다(runbook에 확인 쿼리).

검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함
전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절
BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션
기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가,
샘플 Idempotency-Key 오류 코드 변경.
2026-11-03 19:52:06 +09:00

8.7 KiB

02. 새 도메인·유스케이스 추가

핵심

안쪽 계층부터 바깥으로 만든다. 각 단계는 그 단계의 테스트까지 끝내고 다음으로 간다. 생성 명령(01장)이 1~5단계의 뼈대를 만들고, 이 장은 각 단계에서 사람이 정할 것을 적는다.

1 domain-core ─▶ 2 application-core ─▶ 3 outbound adapter ─▶ 4 inbound adapter ─▶ 5 app-bootstrap
 모델·불변식       유스케이스·포트          저장·외부 연동         전송·DTO·오류         bean·조건·권한
 (Java만)          (Java + 계약 타입)       (Spring·JPA 등)         (HTTP 등)             (조립)

바깥 계층은 안쪽을 알지만 안쪽은 바깥을 모른다. 그래서 안쪽부터 만들면 각 단계가 앞 단계만 보고 컴파일된다. 한 단계가 다른 leaf나 계층을 고쳐야 하면 거기서 멈추고 설계를 다시 본다(CLAUDE.md Layer workflow).

0단계 — 배치를 정한다

먼저 03장으로 이 기능을 어디 둘지 정한다. 기본은 계층 leaf 안 <feature> 패키지다. 생성 명령은 이 기본값만 만든다.

1단계 — domain-core: 모델과 불변식

만드는 것: aggregate(@AggregateRoot), id(@ValueObject record, ResourceId), id 생성 포트 (IdFactory 상속), 저장 포트(*Repository), 불변식 예외(Reason enum). 예: 생성 결과 src/domain-core/src/main/java/dev/caskeleton/domain/<f>/.

검사: DomainPurityArchitectureTest(Spring·JPA·전송 타입 금지, setter 비공개, 감사 필드 금지), ForbiddenApiArchitectureTest.NO_LONG_ID_PK.

판단: id를 누가 만드나

  • 고르는 기준: 클라이언트가 같은 요청을 다시 보낼 때 같은 리소스를 가리켜야 하는가.
  • 기본값: 서버가 만든다. domain XIdFactory extends IdFactory<XId> + adapter:outbound:identifier 구현. 문법은 id 값 객체 생성자에서 검사한다.
  • 예외: 클라이언트가 자연 키(주문번호 등)를 주는 기능은 그 키를 id로 쓴다. 이때 중복은 DB 유일성 제약이 막는다(04장). UUIDv7이 필요하면 src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/outbound/identifier/UuidWorkLogIdFactory.java처럼 바꾼다.

판단: 불변식을 어디 두나

  • 고르는 기준: 규칙이 aggregate 하나의 상태만 보고 판정되는가.
  • 기본값: aggregate 메서드·팩토리 안. 위반은 XInvariantException(Reason).
  • 예외: 둘 이상의 aggregate나 저장된 다른 행을 봐야 하는 규칙(중복 금지 등)은 유스케이스 + DB 제약. 조회 후 insert만으로는 동시 요청에서 깨진다(04장).

판단: 저장 포트를 누가 소유하나

  • 고르는 기준: 포트가 aggregate 단위로 말하는가, 기술적 저장·조회인가.
  • 기본값: aggregate를 통째로 저장·로드하면 domain 소유 XRepository.
  • 예외: 읽기 모양이 aggregate와 다르면 application 소유 XQueryPort + projection(record). QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES가 반환 타입을 검사한다. lease·claim 같은 기술 저장은 application 소유 *StorePort. 이름 규칙의 정본은 src/application-core/CLAUDE.md.

2단계 — application-core: 유스케이스와 포트

만드는 것: command/query record, 유스케이스(쓰기 CommandUseCase, 읽기 QueryUseCase), 반환용 view record, 오류 코드 enum과 carrier 예외. 예: src/application-core/src/main/java/dev/caskeleton/application/<f>/.

필수 선언(ArchUnit이 강제, ApplicationBoundaryArchitectureTest):

  • 모든 유스케이스에 @UseCaseCapability(transactionMode, idempotency, repositoryAccess). 선언과 실제 TransactionPort 호출이 맞아야 한다(USE_CASE_CAPABILITY_MATCHES_TRANSACTION_PORT_BOUNDARY).
  • 쓰기 유스케이스에 @RequiresPermission("<resource>:<action>")(MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION).
  • 유스케이스 클래스는 final이 아니다. 권한 프록시가 하위 클래스를 만든다 (src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/authz/RequiresPermissionProxyabilityTest.java).

판단: 트랜잭션 모양

  • 고르는 기준: 결과를 커밋 뒤에 내보내야 하는가, 호출자와 독립적으로 커밋해야 하는가.
  • 기본값: 쓰기 tx.inWrite, 읽기 tx.inRead.
  • 예외: 커밋 확인 뒤 결과를 노출해야 하면 inRootWrite(바깥 트랜잭션이 있으면 거부). 감사·보상만 inNew(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: src/application-core/CLAUDE.md 「Allowed transactional shapes」.

판단: 무엇을 반환하나

  • 기본값: application view record(XView). 전송 계층이 aggregate를 받지 않는다 (TypeBoundaryArchitectureTest.CONTROLLERS_DO_NOT_RETURN_DOMAIN_OR_ENTITY_TYPES).
  • 예외: 같은 leaf 안 다른 유스케이스가 aggregate를 이어 받아야 하면 aggregate를 반환해도 된다. 컨트롤러는 그때도 응답 DTO로 바꾼다.

판단: 멱등성 선언

05장. 기본값 NOT_IDEMPOTENT(쓰기), IDEMPOTENT(읽기). 클라이언트가 재전송할 수 있는 결제·주문류 쓰기는 KEYED.

3단계 — outbound adapter

만드는 것: 포트 구현. 생성 명령은 id adapter(adapter:outbound:identifier/<f>/Uuid<F>IdFactory)만 만든다. 저장 adapter는 04장 순서로 직접 만든다.

필수: adapter는 포트 소유자 testFixtures의 XRepositoryContract를 실제 저장소로 상속하는 테스트를 가진다(08장). 실 DB가 필요하면 strict lane(integrationTest 등)에 둔다.

4단계 — inbound adapter (HTTP)

만드는 것: 컨트롤러, 요청·응답 DTO. 예: src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/<f>/.

  • 컨트롤러는 변환만 한다: 요청 → command/query → 유스케이스 → Envelope.ok(응답 DTO, ResponseMetaFactory.fromMdc()). repository·엔티티 직접 사용 금지(CONTROLLERS_DO_NOT_ACCESS_REPOSITORIES_OR_JPA_ENTITIES).
  • 생성 201은 Location 헤더를 준다. 비동기 수락은 202(DurableOperationController).
  • 경로는 lowerCamel 복수형(AIP-122).
  • 실패는 던지기만 한다. ApiErrorCarrier를 전역 핸들러가 매핑한다(06장). 기능 전용 핸들러를 만들지 않는다.

판단: 입력 검증을 어디서 하나

  • 고르는 기준: 규칙이 도메인 규칙인가, wire 모양(형식·필수 키)인가.
  • 기본값: 도메인 규칙은 aggregate가 한 번만 검사한다. DTO에 같은 규칙을 bean validation으로 또 쓰지 않는다(두 벌이 갈라진다).
  • 예외: 도메인이 볼 수 없는 wire 모양 — 크기 상한, 형식 패턴, 필수 키 — 은 DTO에 @NotNull·@Size·@Pattern으로 둔다(SubmitOperationHttpRequest). 이것은 400 VALIDATION_FAILED로 나간다.

5단계 — app-bootstrap 조립

만드는 것: @AutoConfiguration 클래스 하나 + AutoConfiguration.imports 한 줄. 예: src/composition/durable-operation/src/main/java/dev/caskeleton/composition/operation/DurableOperationAutoConfiguration.java.

  • @ConditionalOnBean(필요한 포트들): 포트 구현이 없으면 기능 전체가 없다.
  • 유스케이스는 @Bean으로 만든다. 직접 new 하면 권한 프록시가 없어 @RequiresPermission이 조용히 빠진다.
  • 컨트롤러는 component scan이 아니라 @Import로 등록한다. scan은 dev.caskeleton.bootstrap만 본다 (CaSkeletonApplication).
  • 포트 구현이 다른 자동 설정에서 오면 afterName으로 순서를 적는다. 안 적으면 조건이 그 bean을 못 본다.
  • 이벤트를 내면 계약 contribution도 @Bean으로 등록한다(09장).
  • 역할 → 권한 매핑을 app.authz.role-permissions에 더한다(07장).

6단계 — 공개 계약이 바뀌었으면 함께 고친다

바뀐 것 같이 할 것
새 공개 경로(인증 없이 열림) docs/security/public-paths-snapshot.txt, ./gradlew verifyPublicPathSnapshot
새 env 키 docs/registries/env-keys.yaml, ./gradlew :app-bootstrap:verifyEnvKeys
새 의존성 lockfile 갱신(./gradlew :<leaf>:resolveAndLockAll --write-locks), verifyDependencyLocks
새 마이그레이션 04장 번호 규칙
새 이벤트 계약 09장

지금 이해하면 되는 것

  • 안쪽부터: domain → application → outbound → inbound → bootstrap.
  • 쓰기 유스케이스는 non-final + @RequiresPermission + bean. 셋 중 하나라도 빠지면 권한 검사가 없다.
  • 조립은 포트가 있을 때만 켜진다. 저장 adapter가 생기기 전 기능은 없는 상태다.
  • 같은 규칙을 두 곳에 쓰지 않는다. 도메인 규칙은 aggregate, wire 모양은 DTO.