문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
143 lines
12 KiB
Markdown
143 lines
12 KiB
Markdown
# ca-skeleton — Clean Architecture Spring Boot 백엔드 템플릿
|
|
|
|
ca-skeleton은 Java 21과 Spring Boot로 만든 Gradle 멀티모듈 백엔드 템플릿이다. 새 서비스를 만드는 개발자가 이 저장소를 복사하고, 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 그대로 둔다. 사람과 AI 세션이 같은 규칙(`AGENTS.md`)과 같은 절차(`docs/work/`)로 일한다. 라이브러리 버전은 `gradle/libs.versions.toml`이 정한다.
|
|
|
|
## 프로젝트 구조
|
|
|
|
저장소 루트가 Gradle 루트다. 빌드 도구와 빌드 파일은 루트에, 코드는 `src/`에 둔다. 허용 목록 밖의 최상위 항목은 `scripts/check-repo-layout.py`가 PR에서 막는다.
|
|
|
|
| 폴더·파일 | 하는 일 | 먼저 읽을 곳 |
|
|
| --- | --- | --- |
|
|
| `src/` | 계층별 앱 코드. leaf(Gradle 프로젝트)만 있다 | 아래 표 |
|
|
| `settings.gradle`, `build.gradle`, `gradlew` | Gradle 빌드. 단계 태스크(`prCheck`·`mainCheck` 등)와 registry를 읽는 settings | [docs/build.md](docs/build.md) |
|
|
| `gradle/` | wrapper, 버전 카탈로그 `libs.versions.toml`, 모듈 registry `modules.json`, 시험 컨테이너 이미지 목록 `container-images.properties` | [gradle/README.md](gradle/README.md) |
|
|
| `build-logic/` | 빌드 규칙(convention plugin, registry 검사) | [build-logic/README.md](build-logic/README.md) |
|
|
| `config/` | 코드 검사 도구 설정(checkstyle, spotbugs) | — |
|
|
| `Dockerfile`, `.env.example` | 릴리스 이미지(빌드 context는 저장소 루트), env 계약 | [docs/build.md](docs/build.md) |
|
|
| `docs/` | 문서. 매뉴얼·계약·운영 문서·결정 기록·기록 | [docs/README.md](docs/README.md) |
|
|
| `scripts/` | Gradle 밖 스크립트. 첫 실행, 새 기능 생성, 검증 진입점, 저장소 배치·문서 검사 | `scripts/bootstrap-local.sh`, `scripts/new-feature.sh`, `scripts/verify.sh` |
|
|
| `compose.yaml` | 개발 환경. 앱 컨테이너와 뒷단 서비스(profile로 고른다) | 파일 머리의 profile 표 |
|
|
| `compose/` | `compose.yaml`이 마운트하는 보조 파일(Keycloak realm, Redis ACL, MinIO 초기화) | [compose/redis/acl/README.md](compose/redis/acl/README.md) |
|
|
| `.gitea/` | workflow(`pr`·`main`·`release`)와 공용 action | [docs/work/reference/gates.md](docs/work/reference/gates.md) |
|
|
| `.github/` | CODEOWNERS, PR 양식, 의존성 취약점 정책 | [.github/dependency-vulnerability-policy.md](.github/dependency-vulnerability-policy.md) |
|
|
|
|
`src/` 아래 폴더는 계층이다. 같은 계층의 leaf는 그 계층 폴더 아래에 있다. leaf 목록·폴더·Gradle path·허용 의존은 registry `gradle/modules.json`이 정한다. Gradle path는 폴더와 다르다(`:application-core`는 `src/application/core`, `:composition:outbox-relay`는 `src/bootstrap/outbox-relay`).
|
|
|
|
| 폴더 | 책임 | 기본 조립에 들어가나 |
|
|
| --- | --- | --- |
|
|
| `src/domain/core/` | 도메인 모델, 불변식, 도메인 이벤트, port. framework·transport·DB 타입을 쓰지 않는다 | 들어간다 |
|
|
| `src/application/core/` | command, 유스케이스, application 정책, 트랜잭션 port. inbound DTO와 persistence entity를 받지 않는다 | 들어간다 |
|
|
| `src/application/fileserver/`, `src/application/notification/`, `src/application/objectstorage/` | capability(부가 기능) 하나의 application 계층 | 그 capability를 켤 때 |
|
|
| `src/shared-contract/` | 저장소 전체의 운영 계약(오류 코드, 로그 키, 런타임 환경). 업무 개념은 두지 않는다 | 들어간다 |
|
|
| `src/adapter/inbound/` | HTTP·gRPC·GraphQL·WebSocket·메시징 수신 경계. DTO, 검증, 인증, 오류 매핑 | `web`만 들어간다 |
|
|
| `src/adapter/outbound/` | port 뒤의 구현: 영속성(JPA·MongoDB), Redis, 메시징, 알림, 객체 저장소, 파일 서버, HTTP client, identifier, 공용 기반(support) | `support`·`identifier`만 들어간다 |
|
|
| `src/bootstrap/app/` | Spring Boot 진입점과 조립 루트(composition root, 모든 모듈을 엮는 곳) | 들어간다 |
|
|
| `src/bootstrap/` 의 나머지 | 조립만 하는 `composition:*` leaf: 서비스 런타임 배선, outbox relay, 멱등성 executor, durable operation, 알림·파일 서버 플랫폼 | `service-runtime`·`outbox-relay`·`idempotency`·`durable-operation`이 들어간다. 뒤의 셋은 필요한 port가 생기기 전에는 아무것도 만들지 않는다 |
|
|
|
|
의존은 항상 바깥에서 안으로 흐른다. adapter가 core의 port에 의존하고, core는 adapter를 모른다.
|
|
|
|
```text
|
|
app-bootstrap ─▶ adapter:inbound:* ─▶ application-core ─▶ domain-core
|
|
app-bootstrap ─▶ adapter:outbound:* ─▶ application-core ─▶ domain-core
|
|
모든 런타임 모듈 ─▶ shared-contract
|
|
```
|
|
|
|
불변식: 도메인 규칙은 `domain-core`와 `application-core`에만 있고, 기술 선택(웹, DB, 메시징)은 adapter에만 있다.
|
|
|
|
## 시작하기
|
|
|
|
전제는 Temurin 21(`.tool-versions`에 고정)과 Docker Engine 또는 Docker Desktop이다. Gradle은 저장소의 wrapper를 쓴다. 첫 실행 진입점은 하나다.
|
|
|
|
```bash
|
|
scripts/bootstrap-local.sh
|
|
```
|
|
|
|
이 스크립트는 네 단계를 차례로 돈다: 컴파일, PostgreSQL 기동, 앱 이미지 빌드와 기동, `GET /api/healthcheck` 확인. 단계마다 `bootstrap N/4` 줄을 찍고, 실패하면 그 단계에서 멈춘다. 쓰는 compose 파일은 루트의 `compose.yaml` 하나다.
|
|
|
|
성공하면 이 명령이 HTTP 200을 돌려준다.
|
|
|
|
```bash
|
|
curl -fsS http://localhost:8080/api/healthcheck
|
|
```
|
|
|
|
내릴 때는 저장소 루트에서 `--profile '*'`를 붙인다. 붙이지 않으면 profile로 띄운 `db` 같은 서비스가 남는다.
|
|
|
|
```bash
|
|
docker compose --profile '*' down
|
|
```
|
|
|
|
환경 변수는 `.env`(로컬 실행 입력)와 `.env.example`(배포 환경 변수의 복사·검증 계약)에 있다. 키 목록과 설명은 [docs/build.md](docs/build.md)와 [docs/registries/env-keys.yaml](docs/registries/env-keys.yaml)이다.
|
|
|
|
## 기능 켜고 끄기
|
|
|
|
기본 조립(`bootJar`)은 web, 운영 관측(actuator·metrics·tracing·로그), core들, `support`·`identifier`뿐이다. 그래서 DB·Redis·Kafka 없이 뜬다. `./gradlew :app-bootstrap:bootRun`으로 바로 실행할 수 있다.
|
|
|
|
DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src/bootstrap/app/build.gradle`에 주석 처리된 `runtimeOnly` 한 줄씩으로 있다.
|
|
|
|
- 켜기: 그 줄의 주석을 풀고 필요한 env 키를 넣는다. 모듈이 classpath에 있으면 켜진다.
|
|
- 끄기: 줄을 지운다. 기능·설정·의존성이 함께 빠진다. 줄을 둔 채 끄려면 그 모듈의 `enabled` 키를 `false`로 둔다.
|
|
- 줄마다 필요한 env 키와 끄는 키: [docs/build.md](docs/build.md) 「기능 추가 = 한 줄 + env」 표.
|
|
- 기능마다 조립·검증 상태: [docs/capability-status.md](docs/capability-status.md).
|
|
- capability 모듈이 지켜야 하는 규칙과 완료 기준 7개: [docs/manual/10-capabilities.md](docs/manual/10-capabilities.md).
|
|
|
|
뒷단 서비스는 `compose.yaml`의 profile로 고른다(`docker compose --profile redis up -d --wait`). profile 목록은 그 파일 머리에 있다.
|
|
|
|
## 문서 지도
|
|
|
|
모든 문서 폴더의 지도는 [docs/README.md](docs/README.md)다. 무엇을 하려는지에 따라 여기서 시작한다.
|
|
|
|
| 하려는 일 | 시작할 곳 |
|
|
| --- | --- |
|
|
| 이 저장소에서 일하기(새 기능, 개선, 조사, 문서, 운영, 일 나누기) | 작업 매뉴얼 [docs/work/README.md](docs/work/README.md). 지도는 [AGENTS.md](AGENTS.md) |
|
|
| 새 업무 기능 만들기 | 개발 매뉴얼 [docs/manual/README.md](docs/manual/README.md)와 생성 명령 `scripts/new-feature.sh` |
|
|
| 계약 확인하기(HTTP, 오류 코드, env 키, 메트릭, 헤더) | [docs/web/http-contract.md](docs/web/http-contract.md), `docs/registries/` |
|
|
| 기능 운영하기(설정, 장애 대응) | 영역 운영 문서(`docs/jpa/`, `docs/redis/` 등), 장애 코드별 런북 `docs/runbooks/` |
|
|
| 왜 이렇게 정했는지 보기 | 결정 기록 `docs/adr/` |
|
|
| 예전 설계·계획·리뷰 찾기 | 기록 `docs/design/`, `docs/history/`, `docs/reviews/`. 쓴 때의 글이고 지금 동작은 각 머리 블록의 「현재 정본」을 읽는다 |
|
|
| 템플릿 변경을 파생 서비스에 받기 | `docs/upgrade/` |
|
|
|
|
각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 `AGENTS.md`와 README에 있다(예: [domain-core](src/domain/core/README.md), [app-bootstrap](src/bootstrap/app/README.md)).
|
|
|
|
## 검증
|
|
|
|
명령은 저장소 루트에서 돌린다. 일상 피드백은 바꾼 leaf 하나와 아키텍처 검사다. leaf의 Gradle 경로는 registry의 `gradle_path`에서 읽는다.
|
|
|
|
```bash
|
|
./gradlew :app-bootstrap:check --console=plain
|
|
./gradlew architectureCheck --console=plain
|
|
```
|
|
|
|
`./gradlew test`는 모든 leaf의 `test`를 돌리므로 일상 명령으로 쓰지 않는다. PR·main·태그 단계에서 무엇이 도는지, 바꾼 것에 맞춰 무엇을 더 돌릴지는 [docs/work/reference/gates.md](docs/work/reference/gates.md)가 정한다. 게이트 태스크 하나하나의 설명은 [docs/build.md](docs/build.md) 「build.gradle — 빌드 / 검증 게이트」다.
|
|
|
|
문서를 고쳤으면 저장소 루트에서 `python3 scripts/check-docs.py`를 돌린다. 규칙은 [docs/README.md](docs/README.md) 「문서 검사」다.
|
|
|
|
## 새 서비스로 시작하기
|
|
|
|
이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 이 목록이 템플릿 재사용 체크리스트의 정본이다.
|
|
|
|
1. `settings.gradle`의 `rootProject.name`을 새 서비스 이름으로 바꾼다.
|
|
2. 패키지 루트 `dev.caskeleton`을 서비스 패키지로 바꾼다. Java 소스만이 아니라 `AutoConfiguration.imports`·`spring.factories`·빌드 스크립트·설정 파일·생성 명령 템플릿도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다.
|
|
|
|
```bash
|
|
git grep -l 'dev\.caskeleton' -- src scripts
|
|
```
|
|
|
|
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾼다.
|
|
4. 새 업무 기능은 `scripts/new-feature.sh <FeatureName>`으로 만들고 [docs/manual/README.md](docs/manual/README.md) 순서대로 채운다. 모듈 이름과 경계는 그대로 둔다.
|
|
5. 쓰는 capability의 `runtimeOnly` 줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다.
|
|
6. 라이브러리 패키지 `dev.cakit.*`은 바꾸지 않는다. 별도 repo에서 받는 라이브러리의 패키지이고, 2번이 바꾸는 `dev.caskeleton`과 이름이 겹치지 않게 정했다. 라이브러리 목록은 [관련 저장소](docs/work/reference/related-repos.md)다.
|
|
7. Docker 이미지 이름과 애플리케이션 이름(`spring.application.name`)을 새 서비스 기준으로 바꾼다.
|
|
8. `.env.example`, `.env.local.example`, `application.yml`의 예시 값을 새 서비스의 실행 요구에 맞춘다. 운영 모듈에는 그 서비스의 entity, repository port, use case, adapter만 더한다.
|
|
9. README와 운영 문서를 새 서비스 설명으로 고친다.
|
|
|
|
복사한 뒤 지워도 되는 것은 템플릿의 기록(`docs/design/`, `docs/history/`, `docs/reviews/`)이다. 서비스의 지금 동작을 설명하지 않는다. 지우면 그 기록을 가리키던 살아 있는 문서가 깨지므로 `python3 scripts/check-docs.py`와 링크 검사([docs/work/reference/gates.md](docs/work/reference/gates.md) 「링크 검사」)로 찾아 고친다. 템플릿을 upstream으로 두고 merge해 받으면 그 폴더에서 충돌이 날 수 있다(`docs/upgrade/2026-11-docs-records.md`).
|
|
|
|
이름을 바꾼 뒤에는 위 「검증」의 두 명령과 `./gradlew :app-bootstrap:test --console=plain`을 돌린다.
|
|
|
|
## 규칙과 기여
|
|
|
|
- 규칙의 정본이자 일을 시작할 때 읽는 지도는 [AGENTS.md](AGENTS.md)다. 「HARD-STOP」 조건을 어기면 동작하더라도 병합하지 않는다. Claude Code 세션은 [CLAUDE.md](CLAUDE.md)가 이 파일을 가져온다.
|
|
- 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다.
|
|
- 각 모듈의 지역 규칙은 가장 가까운 `src/**/AGENTS.md`다.
|
|
- 커밋 정책과 메시지 형식은 [docs/work/README.md](docs/work/README.md) 「커밋」이다. PR은 [.github/pull_request_template.md](.github/pull_request_template.md) 양식을 채운다.
|