문제:
- 루트 compose 6개와 infra/ 아래 12개가 개발 환경, 테스트 lane fixture,
보조 파일을 가리지 않고 섞여 있다. 이름 모양도 셋이다.
- README 빠른 시작 scripts/bootstrap-local.sh는 docker-compose.yml과
.local.yml만 합친 뒤, 둘 어디에도 없는 db 서비스를 띄우려다 멈춘다.
- compose smoke all-adapters lane은 앱이 mem_limit 512m를 넘어 커널에
죽고(OOM), restart: unless-stopped로 다시 떠서 죽는 때가 smoke 요청과
겹칠 때만 실패한다. smoke는 재시작을 보지 않아 나머지 실행은 거짓 통과다.
고른 방법(소유자 결정 2026-11-07):
- 루트에 개발용 compose.yaml 하나. app(local 런타임)과 뒷단 서비스를
capability profile(jpa, redis, kafka, mongo, objectstorage, auth, mail)로
고른다. 마운트하는 보조 파일은 compose/(keycloak, minio init, Redis ACL,
mailpit 인증서 폴더).
- lane fixture는 lane을 가진 leaf로: dev·prod-smoke·tls overlay, fileserver
overlay, smoke·스키마 적용 서비스(lane-services.yaml)와 스크립트, lane
계약 JSON → src/app-bootstrap/compose-lanes/. Redis topology →
redis-sdk/compose/, NFS → fileserver/compose/nfs/. infra/는 없어진다.
- 계약의 composeProfile(문자열)을 composeProfiles(목록)로 바꾼다. lane이
backing profile과 lane profile을 함께 켠다. 18 lane의 서비스 집합은
전과 같다(verify-compose-profile-contracts.sh가 정확히 대조).
- smoke: lane이 끝나기 전에 그 project의 모든 컨테이너가 재시작 0,
OOMKilled false인지 보고 아니면 실패한다. 앱의 memory.peak를 증거로
남긴다. all-adapters만 appMemoryLimit 1g(계약 칸, smoke가 overlay에 씀).
- bootstrap-local.sh는 compose.yaml로 db와 app을 띄운다(인자 없음).
- 개발 compose와 lane 바탕이 같은 파일이라, app healthcheck는 모든
런타임에서 답하는 관리 포트 readiness로 둔다.
버린 대안: lane을 Testcontainers로 옮기기(설계 다-2, 별도 판단), lane마다
기본 메모리를 올리기(배포 기본값 512m 계약을 흐림).
위험·한계:
- 개발 compose의 app이 src/.env를 읽으므로, 개발자 src/.env가 dev·prod
lane에도 들어간다. lane 값은 생성 overlay의 environment가 이기고, CI에는
src/.env가 없다.
- MinIO 이미지 기본값이 compose.yaml과 lane-services.yaml 두 곳에 있다
(YAML anchor는 파일을 넘지 못한다). ComposeMinioImageMatchesEvidenceTest가
둘 다 evidence digest와 대조한다.
- env 키 검사(verifyEnvKeys)는 compose.yaml과 lane overlay를 읽고
lane-services.yaml(smoke client 변수)은 뺀다.
검증(desktop, 트리 6d1e9f9d → 주석·문서만 고친 d0703901, ~/t1-layout-logs/):
- verify-compose-profile-contracts.sh rc=0 (18 lane 정확히 일치)
- :app-bootstrap:check :app-bootstrap:documentContractTest
:app-bootstrap:verifyEnvKeys와 objectstorage·cache-redis·redis-sdk·
redis-runtime·fileserver·composition:fileserver-platform check rc=0
- :app-bootstrap:integrationTest(ComposeMergeCharacterizationTest 포함),
:adapter:outbound:cache-redis:redisContainerContractTest rc=0
- -p build-logic check rc=0, :verifyStrictLaneStages --dry-run rc=0
- scripts/run-compose-runtime-smoke.sh --matrix(18 lane) rc=0, 794초.
모든 lane 컨테이너 재시작 0·OOMKilled false. 앱 memory.peak 최고
all-adapters 532MiB(512m 한도를 넘는 값이라 1g의 근거), 나머지 244~422MiB
- scripts/bootstrap-local.sh rc=0(db·app 기동, /api/healthcheck 200 UP).
기준 ac03192d의 base+local 조합은 config --services가 app뿐이고
up --wait db가 "no such service: db"로 rc=1
- 정리할 때 `docker compose down`은 profile 서비스(db)를 남겨
README·compose.yaml 안내를 `--profile '*' down`으로 고치고 다시 확인
- 주석·문서 수정 뒤 :app-bootstrap:repositoryContractTest
:app-bootstrap:documentContractTest, verify-compose rc=0
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.3
BREAKING CHANGE: 루트 docker-compose*.yml과 infra/가 없어지고 compose.yaml(profile)·compose/·leaf 안 lane fixture로 옮겨졌다. lane 계약은 src/app-bootstrap/compose-lanes/compose-profile-contracts.json, composeProfile → composeProfiles. docs/upgrade/2026-11-maturity-review.md B-51.
162 lines
10 KiB
Markdown
162 lines
10 KiB
Markdown
# ca-skeleton — Clean Architecture Spring Boot 템플릿
|
|
|
|
ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Gradle 멀티모듈 기반의 Clean Architecture 백엔드 템플릿입니다. fork해서 도메인·패키지·엔티티·유스케이스만 교체하면 새 서비스를 시작할 수 있고, 모듈 경계와 의존 방향은 그대로 유지합니다. 기본 패키지는 `dev.caskeleton`입니다. 업무 기능의 예시는 생성 명령 `scripts/new-feature.sh`의 출력과 [docs/manual/](docs/manual/README.md)입니다.
|
|
|
|
이 문서는 전체 구조와 첫 실행만 다룹니다. 모듈별 상세 규칙과 설계 근거는 각 모듈의 README와 `CLAUDE.md`가, 빌드·환경 변수 상세는 [src/README.md](src/README.md)가 소유합니다.
|
|
|
|
## 아키텍처 한눈에
|
|
|
|
의존은 항상 바깥에서 안으로 흐릅니다. adapter가 core의 port에 의존하고, core는 adapter를 알지 못합니다. 이 방향이 유지되는 한 도메인 규칙과 기술 선택(웹 프레임워크, DB, 메시징)을 서로 독립적으로 바꿀 수 있습니다.
|
|
|
|
```text
|
|
app-bootstrap -> adapter:inbound:* -> application-core -> domain-core
|
|
app-bootstrap -> adapter:outbound:* -> application-core -> domain-core
|
|
모든 런타임 모듈 -> shared-contract
|
|
```
|
|
|
|
family 수준의 책임은 다음과 같습니다.
|
|
|
|
| 모듈 family | 책임 |
|
|
| --- | --- |
|
|
| `domain-core` | 순수 도메인 모델·불변식·이벤트·port. 프레임워크·transport·DB·IO 타입 금지 |
|
|
| `application-core` | command·유스케이스·application 정책·트랜잭션 port. inbound DTO·persistence entity 금지 |
|
|
| `adapter:inbound:*` | HTTP·gRPC·GraphQL·WebSocket transport 경계, DTO·validation·인증·에러 매핑 |
|
|
| `adapter:outbound:persistence-*` | JPA/PostgreSQL·MongoDB 영속 구현과 매핑·migration |
|
|
| `adapter:outbound:*` | support(공유 베이스)·messaging·cache·notification·object storage·file·HTTP client·identifier 능력을 port 뒤에서 구현. 기본 조립에는 support·identifier만 들어 있고, 나머지는 `app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 고릅니다 |
|
|
| `shared-contract` | skeleton 전역 운영 계약. business/domain 개념 저장 금지 |
|
|
| `app-bootstrap` | Spring Boot entrypoint와 composition root |
|
|
|
|
등록된 leaf 목록과 각 leaf의 Gradle path·소스 경로·허용 production 의존 edge는
|
|
[src/config/architecture/modules.json](src/config/architecture/modules.json)이 SSOT입니다. focused
|
|
test는 해당 Gradle path에서 `./gradlew <gradle-path>:test --console=plain` 형태로 파생하며, root
|
|
문서나 기억에서 개별 leaf edge를 추론하지 않습니다.
|
|
|
|
## 퀵스타트
|
|
|
|
전제조건은 Temurin 21(루트 [.tool-versions](.tool-versions)에 고정)과 Docker Engine 또는 Docker Desktop입니다. Gradle은 저장소 wrapper를 씁니다. 첫 실행 진입점은 하나입니다.
|
|
|
|
```bash
|
|
scripts/bootstrap-local.sh
|
|
```
|
|
|
|
`scripts/bootstrap-local.sh`는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, `GET /api/healthcheck` HTTP smoke를 순서대로 실행합니다. 쓰는 compose 파일은 저장소 루트의 `compose.yaml` 하나입니다. 각 단계가 `bootstrap N/4` 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
|
|
|
|
```bash
|
|
curl -fsS http://localhost:8080/api/healthcheck
|
|
```
|
|
|
|
로컬 스택을 내릴 때는 저장소 루트에서 실행합니다.
|
|
|
|
```bash
|
|
docker compose --profile '*' down
|
|
```
|
|
|
|
`--profile '*'`가 없으면 profile이 달린 `db`가 남습니다. compose는 켜진 profile의 서비스만 내립니다.
|
|
|
|
Redis·Kafka·MongoDB 같은 뒷단 서비스는 `compose.yaml`의 profile로 고릅니다(`docker compose --profile redis up -d --wait`). profile 목록은 그 파일 머리에 있습니다.
|
|
|
|
`src/.env.example`은 배포 환경 변수의 추적 가능한 복사/검증 계약이고 `src/.env`는 로컬 실행 입력입니다. 전체 환경 변수 목록과 조정 시점은 [src/README.md](src/README.md)와 [docs/registries/env-keys.yaml](docs/registries/env-keys.yaml)에 있습니다.
|
|
|
|
### 기본 조립과 부가 기능
|
|
|
|
기본 조립(`bootJar`)은 web, 관측, `domain-core`·`application-core`·`shared-contract`, support,
|
|
identifier뿐이라 DB·Redis·Kafka 없이 기동합니다.
|
|
|
|
```bash
|
|
cd src
|
|
./gradlew :app-bootstrap:bootRun
|
|
```
|
|
|
|
DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능은 `app-bootstrap/build.gradle`에 주석 처리된
|
|
`runtimeOnly` 한 줄씩으로 있습니다. 줄의 주석을 풀고 필요한 env를 넣으면 켜지고, 줄을 지우면 사라집니다.
|
|
줄마다 필요한 env와 끄는 키는 [src/README.md](src/README.md)의 "기능 추가 = 한 줄 + env" 표에 있습니다.
|
|
|
|
| 프로파일 | 데이터스토어 (persistence-jpa 줄을 넣었을 때) | 스키마 소유자 |
|
|
| --- | --- | --- |
|
|
| `local` | Compose PostgreSQL (`./gradlew :app-bootstrap:bootRunH2`는 줄 없이도 모듈을 자기 classpath에 올려 H2 in-memory로 실행) | Flyway (H2는 Hibernate `create-drop`) |
|
|
| `dev` | PostgreSQL | Flyway |
|
|
| `prod` | PostgreSQL | Flyway |
|
|
|
|
H2 실행은 wiring과 애플리케이션 동작만 검증하고, migration과 vendor 동작은 검증하지 않습니다. 프로파일별 설정은 [src/app-bootstrap/src/main/resources/](src/app-bootstrap/src/main/resources/)의 `application-{local,dev,prod}.yml`이, 상세 설명은 [src/README.md](src/README.md)가 소유합니다.
|
|
|
|
## 새 프로젝트로 시작하기
|
|
|
|
이 저장소를 새 서비스의 출발점으로 쓸 때 핵심 단계는 다음과 같습니다. 전체 체크리스트는 [AGENTS.md](AGENTS.md)의 "템플릿 재사용 체크리스트"에 있습니다.
|
|
|
|
1. [src/settings.gradle](src/settings.gradle)의 `rootProject.name`을 새 서비스 이름으로 바꿉니다.
|
|
2. 패키지 루트 `dev.caskeleton`을 조직·서비스 패키지로 바꿉니다. 소스뿐 아니라 빌드·설정 파일의 참조도 함께 바꿔야 `mainClass`·`group`이 어긋나 `bootstrap`이 깨지지 않습니다.
|
|
|
|
```bash
|
|
cd src
|
|
find . -type f \( -name '*.java' -o -name '*.gradle' -o -name '*.yml' \) -print0 | xargs -0 sed -i 's/dev.caskeleton/com.yourorg.yourservice/g'
|
|
```
|
|
|
|
애플리케이션 이름 등 나머지 rename 단계는 위 체크리스트를 따릅니다.
|
|
|
|
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾸고, 목표 도메인의 엔티티·repository port·유스케이스·adapter를 production 모듈에 추가합니다. 새 업무 기능은 `scripts/new-feature.sh <FeatureName>`으로 만듭니다.
|
|
4. 모듈 이름과 경계는 그대로 유지합니다.
|
|
|
|
검증은 먼저 composition root의 빠른 테스트와 아키텍처 검사를 확인합니다. 루트에서
|
|
`./gradlew test`를 호출하면 등록된 모든 하위 프로젝트의 `test`를 실행하므로 일상적인 로컬
|
|
피드백 명령으로 사용하지 않습니다. 저장소 전체 qualification은 CI 또는 명시적인 `ci` task가
|
|
담당합니다.
|
|
|
|
```bash
|
|
cd src
|
|
./gradlew :app-bootstrap:test
|
|
./gradlew architectureCheck
|
|
```
|
|
|
|
병합 전 저장소 전체 검증이 필요하면 `./gradlew ci`를 실행합니다.
|
|
|
|
## 아키텍처 규칙과 검증
|
|
|
|
애플리케이션이 동작하더라도 아래를 어기면 병합하지 않습니다. HARD-STOP 7개 조건의 정본 로컬
|
|
정책 권위는 [AGENTS.md](AGENTS.md)이며, [CLAUDE.md](CLAUDE.md)는 작업을 시작할 때 읽는 지도입니다.
|
|
일의 종류별 절차는 [docs/work/](docs/work/README.md)에 있습니다.
|
|
|
|
- `domain-core`는 Spring·JPA·Servlet·HTTP·DB·cloud SDK 타입을 import하지 않습니다.
|
|
- controller는 repository를 직접 호출하거나 persistence entity를 반환하지 않습니다.
|
|
- inbound DTO는 `application-core`나 `domain-core`로 들어가지 않습니다.
|
|
- 비즈니스 정책은 mapper·filter·config·settings·controller에 두지 않습니다.
|
|
- 새 외부 시스템 연동은 domain/application port와 adapter 모듈로 표현합니다.
|
|
|
|
이 규칙은 두 축으로 자동 강제합니다. `:app-bootstrap:architectureTest`의 분할된 ArchUnit 규칙들이 컴파일된 소스 의존성을,
|
|
`verifyCleanArchitectureDependencies` 게이트가 JSON registry의 허용 Gradle project edge를
|
|
검사합니다.
|
|
|
|
```bash
|
|
cd src
|
|
./gradlew verifyCleanArchitectureDependencies
|
|
```
|
|
|
|
두 검증 축은 [ci-quality-gates.yml](.github/workflows/ci-quality-gates.yml)의 release gate에 연결되어, 규칙 위반이 병합·릴리스를 막습니다.
|
|
|
|
## 수동 전용 Gradle 태스크
|
|
|
|
아래 태스크는 **어떤 워크플로도 실행하지 않으며, 그게 의도다.** 자동 실행이 틀린 이유를 적어 둔다.
|
|
|
|
여기 적힌 태스크 이름이 실재하는지 검사하던 `verifyReadmeCommands`는 삭제했다. 그건 이 문서의
|
|
```bash 블록을 직접 파싱해 `./gradlew`·`docker compose`·`make` 토큰을 실제 태스크 그래프와 대조하는
|
|
Markdown 명령 파서였고, 그 결과 "README에 무엇을 쓸 수 있는가"가 그 파서가 읽을 수 있는 문법의
|
|
함수가 됐다. 문서와 코드가 어긋나는 것은 결함이지만, 빌드를 실패시켜서 고칠 일은 아니다.
|
|
|
|
```bash
|
|
cd src
|
|
./gradlew :grpc:grpc-testkit:grpcPerformanceTest
|
|
```
|
|
|
|
- `grpcPerformanceTest` — latency percentile·saturation·drain budget을 **측정**한다. 공유 CI
|
|
runner의 측정값은 흔들리고, 흔들리는 게이트는 결국 꺼진다. leaf `build.gradle`이 이 태스크의
|
|
태그를 `test`에서 제외하는 이유도 같다. 성능 회귀가 의심될 때 사람이 이름으로 부른다.
|
|
|
|
|
|
## 더 알아보기
|
|
|
|
- 빌드·검증 게이트·환경 변수 상세: [src/README.md](src/README.md)
|
|
- 모듈 레지스트리(등록 leaf SSOT): [src/config/architecture/modules.json](src/config/architecture/modules.json)
|
|
- 에이전트·기여자 작업 규칙: [AGENTS.md](AGENTS.md) · [CLAUDE.md](CLAUDE.md)
|
|
- release/publish 자동화는 `.github/workflows/release.yml`이 소유하며, release provenance·SBOM·
|
|
이미지 build/push를 해당 workflow의 명시적 권한과 게이트 아래에서 수행합니다.
|
|
- 모듈별 설계 결정: [domain-core](src/domain-core/README.md) · [application-core](src/application-core/README.md) · [adapter:inbound:web](src/adapter/inbound/web/README.md) · [adapter:outbound:persistence-jpa](src/adapter/outbound/persistence-jpa/README.md) · [shared-contract](src/shared-contract/README.md) · [app-bootstrap](src/app-bootstrap/README.md)
|