Files
clean-architecture-backend-…/docs/manual/01-generator.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

6.8 KiB

01. 생성 명령 — 새 기능 뼈대

핵심

scripts/new-feature.sh <FeatureName> 한 번으로 새 업무 기능의 뼈대가 계층 leaf 다섯 곳에 생긴다. 만든 직후 그대로 PR 게이트(ci의 해당 leaf check)와 architectureCheck를 통과한다. 이 성질은 scripts/verify-feature-scaffold.sh가 main 단계(mainCheck)에서 매번 확인한다.

scripts/new-feature.sh Invoice
  -> domain-core          Invoice, InvoiceId, InvoiceIdFactory, InvoiceRepository, InvoiceInvariantException
                          + testFixtures: InMemoryInvoiceRepository, SequentialInvoiceIdFactory, InvoiceRepositoryContract
  -> application-core     CreateInvoiceUseCase, GetInvoiceUseCase, command·query·view, InvoiceErrorCode, 예외 2개
  -> outbound:identifier  UuidInvoiceIdFactory
  -> inbound:web          InvoiceController (POST /invoices, GET /invoices/{id}), 요청·응답 DTO
  -> app-bootstrap        InvoiceConfig + AutoConfiguration.imports 한 줄
  -> 각 leaf 테스트       불변식, id 문법, 유스케이스, 공유 계약, HTTP 계약, 조립 조건
  -> spotlessApply        (이름 길이에 따라 Javadoc 줄바꿈이 달라져서)

사용법

scripts/new-feature.sh Invoice                 # /invoices, 권한 invoice:create
scripts/new-feature.sh PurchaseOrder           # /purchaseOrders, 권한 purchase-order:create
scripts/new-feature.sh Person --path people    # 복수형이 규칙대로 안 될 때
scripts/new-feature.sh Invoice --no-format     # Gradle 없이 파일만 (뒤에 spotlessApply 직접)
입력 규칙 어디서 막나
이름 PascalCase, 영숫자 스크립트
패키지 이름 이름을 소문자로(purchaseorder). Java 예약어·플랫폼 패키지(operation, lock, cache…)와 겹치면 거절 스크립트
HTTP 경로 lowerCamel 복수형. AIP-122 모양 스크립트, ForbiddenApiArchitectureTest.CONTROLLER_REQUEST_MAPPINGS_FOLLOW_AIP122
이미 있는 파일·패키지 덮어쓰지 않고 멈춘다 스크립트

생성 뒤 확인:

cd src
./gradlew :domain-core:check :application-core:check :adapter:outbound:identifier:check \
          :adapter:inbound:web:check :app-bootstrap:check architectureCheck --console=plain

만드는 것과 만들지 않는 것

만든다 만들지 않는다 이유
도메인 모델·포트·불변식, 유스케이스 두 개(쓰기·읽기), id adapter, 컨트롤러, 조립, 테스트 저장 adapter(JPA 엔티티·Spring Data·마이그레이션) 저장소 종류(JPA/Mongo), 마이그레이션 위치·번호대, 실 DB 계약 lane은 서비스가 정한다(04장). 템플릿이 정하면 upstream과 병합 충돌이 나는 자리다
권한 선언 @RequiresPermission("<f>:create") 역할 → 권한 매핑 어떤 역할이 쓸 수 있는지는 서비스의 결정이다(07장). 매핑 전에는 쓰기가 모두 403 — 안전한 쪽
<F>ErrorCode enum docs/registries/error-codes.yaml 행 그 registry는 템플릿 운영 코드 전용이다. 서비스 코드는 서비스 registry에(06장)
읽기 유스케이스 목록·수정·삭제 목록은 페이지·정렬·N+1 판단이, 수정은 동시성(버전) 판단이 필요하다(04장)

저장 adapter가 없으면 <F>Config의 @ConditionalOnBean(<F>Repository)가 꺼져 있어 엔드포인트가 없다. 반쯤 켜진 상태(엔드포인트는 있는데 저장이 안 됨)가 생기지 않는다.

생성 결과는 placeholder 필드 name 하나를 가진다. 기능의 실제 상태로 바꾸는 것이 첫 작업이다.

왕복 검사

verify-feature-scaffold.sh
  -> 작업 트리를 임시 디렉터리로 복사(추적 + 무시되지 않은 새 파일), git init
  -> new-feature.sh Invoice, new-feature.sh PurchaseOrder   (한 단어 / 여러 단어)
  -> 생성 파일이 있는지 확인
  -> ./gradlew 5 leaf check + architectureCheck
  -> 각 leaf 테스트 결과에 생성된 테스트 클래스가 실행·통과로 남았는지 확인
  -> 임시 디렉터리 삭제
  • 루트 태스크 verifyFeatureScaffold(src/build.gradle)가 이 스크립트를 부르고 mainCheck에 들어 있다. 중첩 Gradle 빌드라 PR 단계가 아니라 main 단계다.
  • 템플릿이나 템플릿이 기대는 규칙(ArchUnit, Error Prone, 포맷)이 바뀌어 생성물이 깨지면 여기서 빨강이 된다.
  • 생성된 테스트가 실행되지 않고 지나가는 일(빈 녹색)을 막으려고 결과 XML을 확인한다.

고른 형태와 버린 대안

형태 결정 이유
scripts/의 bash + 텍스트 템플릿(scripts/feature-scaffold/templates/**/*.tmpl) 채택 개발자 도구는 scripts/에 둔다는 repo 관례(ca.developer-bootstrap 플러그인을 지우고 scripts/bootstrap-local.sh로 옮긴 것, src/build-logic/README.md). 템플릿이 실제 Java 파일 모양이라 리뷰가 쉽다. Gradle 설정 단계를 거치지 않아 빠르다
build-logic의 Gradle 태스크(./gradlew newFeature -Pname=…) 버림 build-logic은 빌드 규약·아키텍처 검사만 둔다(CLAUDE.md Gradle policy). 소스를 쓰는 태스크는 configuration cache·up-to-date와 맞지 않는다
생성 대신 예시 기능을 커밋해 두고 복사 버림 복사본이 하나 더 생겨 규칙과 갈라진다. 이름 바꾸기를 사람이 손으로 한다
왕복 검사를 JUnit 안에서 javac로 컴파일 버림 Spotless·Error Prone·ArchUnit 전체를 다시 구현해야 하고, 실제 게이트와 다른 것을 검사하게 된다. 실제 Gradle 게이트를 그대로 돌리는 쪽을 골랐다
생성 뒤 자동 spotlessApply 채택(끄려면 --no-format) google-java-format이 Javadoc을 이름 길이에 따라 다시 접는다. 템플릿만으로는 모든 이름에서 포맷 검사를 통과시킬 수 없다

생성 결과가 기대는 빌드 설정

생성물이 컴파일되려고 다음 의존이 미리 들어 있다(모두 registry가 허용한 edge).

파일 설정 왜
src/domain-core/build.gradle java-test-fixtures domain 소유 포트의 fake·계약이 포트 소유자 testFixtures에 있어야 한다(AGENTS.md 테스트 규칙 6)
src/application-core/build.gradle, src/adapter/inbound/web/build.gradle, src/app-bootstrap/build.gradle testImplementation testFixtures(project(':domain-core')) 유스케이스·HTTP·조립 테스트가 그 fake를 쓴다
src/adapter/inbound/web/build.gradle implementation project(':domain-core') 컨트롤러가 경로 문자열을 도메인 id로 바꾼다
src/adapter/outbound/identifier/build.gradle implementation project(':domain-core') id adapter가 도메인 IdFactory 포트를 구현한다