문제: `docs/manual/01-generator.md`가 「./gradlew 5 leaf check」로 leaf 개수를 복사해 숫자 검사 예외에 있다. 고른 방법: `scripts/verify-feature-scaffold.sh`가 실제로 돌리는 leaf 이름(domain-core, application-core, identifier, web, app-bootstrap)을 쓴다. 검증: `python3 scripts/check-docs.py` rc=0.
7.2 KiB
7.2 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 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(operation, lock, cache…)가 모두 여기 걸린다. 목록은 src/application-core/CLAUDE.md 「Package ownership」 |
스크립트, NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES |
| 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 Operation / Notification / Common (템플릿 패키지 이름: 거절되고 아무것도 안 씀)
-> new-feature.sh Invoice, new-feature.sh PurchaseOrder (한 단어 / 여러 단어)
-> 생성 파일이 있는지 확인
-> 생성물이 닿는 leaf(domain-core, application-core, identifier, web, app-bootstrap) 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 포트를 구현한다 |