문제: `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.
97 lines
7.2 KiB
Markdown
97 lines
7.2 KiB
Markdown
# 01. 생성 명령 — 새 기능 뼈대
|
|
|
|
## 핵심
|
|
|
|
`scripts/new-feature.sh <FeatureName>` 한 번으로 새 업무 기능의 뼈대가 계층 leaf 다섯 곳에 생긴다.
|
|
만든 직후 그대로 PR 게이트(`ci`의 해당 leaf check)와 `architectureCheck`를 통과한다. 이 성질은
|
|
`scripts/verify-feature-scaffold.sh`가 main 단계(`mainCheck`)에서 매번 확인한다.
|
|
|
|
```text
|
|
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 줄바꿈이 달라져서)
|
|
```
|
|
|
|
## 사용법
|
|
|
|
```bash
|
|
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` |
|
|
| 이미 있는 파일·패키지 | 덮어쓰지 않고 멈춘다 | 스크립트 |
|
|
|
|
생성 뒤 확인:
|
|
|
|
```bash
|
|
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` 하나를 가진다. 기능의 실제 상태로 바꾸는 것이 첫 작업이다.
|
|
|
|
## 왕복 검사
|
|
|
|
```text
|
|
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` 포트를 구현한다 |
|