DongHyeonka 2d274a6842
pr / done (pull_request) Canceled after 0s
refactor(application)!: 시스템 쓰기와 운영자 연산을 유스케이스 계약 안으로 옮긴다
시스템이 부르는 쓰기가 유스케이스 계약 밖에 있다. fileserver 정리·맞추기,
알림 claim·발송·lease 회복·맞추기·provider event replay는 capability도
트랜잭션 선언도 없는 서비스를 worker가 바로 부르고, 그 worker와 조립은
outbound adapter 안에 있다. 알림 운영자 연산 넷은 permission 없이 서비스
하나에 모여 있고 재시도 시각은 상수다. web stream bridge는 outbound가
구현한 replay 포트를 바로 읽는다. fileserver 관리 HTTP 기본값은
controller가 정한다.

고른 방법: 시스템 쓰기는 @SystemInvoked 유스케이스로 나누고 composition
worker 설정이 new로 만든다(bean 아님). 알림 worker와 fileserver 정리 조립은
composition으로 옮기고, 맞추기의 재시도·포기 시점은 유스케이스가 정한다.
운영자 연산은 platform.admin의 유스케이스 클래스 넷과 notification-admin:*
permission이다(port.in 인터페이스는 port.in과 admin의 cycle을 만들어 두지
않는다). replay 읽기는 조회 유스케이스 둘을 거치고 포트는
LiveEventReplayQueryPort로 이름을 바꾼다. 아키텍처 규칙 둘: 사용자 전송은
저장·id 포트를 쥐지 못하고, inbound는 application 서비스·coordinator를
interface로도 쥐지 못한다. 재시도 시각은 설정, 관리 기본값은 command
팩터리다. 재시도 시각의 규칙은 policy의 값 RetryTiming 하나가 갖고 설정은
그 값을 만든다. retry·routing 값들은 서버가 만드는 값이라 잘못된 값을
IllegalStateException으로 거절한다(manual 06). 모듈 기본값이 role notification-admin에 운영자 permission
넷을 준다(fileserver의 ROLE_FILE_ADMIN과 같다). 버린 대안: 서비스에
@UseCaseCapability만 달기(사용자와 시스템이 같은 진입점을 나눠 써서 권한
규칙이 막지 못한다), 운영자 서비스 삭제, 설정에서 policy를 만들어 버리며
검증하기(규칙이 바뀐 policy bean과 상관없이 남는다).

위험·한계: 공개 타입·생성자·bean 이름·아키텍처 규칙이 바뀐다. 파생
서비스가 할 일은 docs/upgrade/2026-11-round9-application.md 1~3·5·6행이다.
claim·fence 커밋 위에 쌓았다.

검증: PR 본문의 desktop 결과.

Refs: RR9-05-06, RR9-05-07, RR9-05-08, RR9-05-10, RR9-05-19
BREAKING CHANGE: NotificationAdminService·NotificationAdminApplicationService가 없어지고 운영자 연산은 platform.admin의 RedriveDeliveryUseCase 등이다(permission notification-admin:*). 알림 worker가 composition:notification-platform으로 옮기고 ReconciliationJobWorker·ProviderEventReplayWorker는 유스케이스가 됐다. MessagingReplayBridge 생성자가 조회 유스케이스를 받고 LiveEventReplayPort는 LiveEventReplayQueryPort다. 사용자 전송이 저장·id 포트나 application 서비스 interface를 쥐면 architectureTest가 실패한다. 운영자 요청 record 이름이 *Request로 바뀌고 DefaultNotificationRetryPolicy 생성자가 RetryTiming을 받는다. RetryBackoff·RetryBudget·RetryContext·RetryDecision.RetryAfter·RouteCandidate·RoutingContext·RoutingDecision·EligibilityResult가 잘못된 값에 IllegalStateException을 던진다.
2026-11-13 16:37:03 +09:00

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
gradle/ wrapper, 버전 카탈로그 libs.versions.toml, 모듈 registry modules.json, 시험 컨테이너 이미지 목록 container-images.properties gradle/README.md
build-logic/ 빌드 규칙(convention plugin, registry 검사) build-logic/README.md
config/ 코드 검사 도구 설정(checkstyle, spotbugs) —
Dockerfile, .env.example 릴리스 이미지(빌드 context는 저장소 루트), env 계약 docs/build.md
docs/ 문서. 매뉴얼·계약·운영 문서·결정 기록·기록 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
.gitea/ workflow(pr·main·release)와 공용 action docs/work/reference/gates.md
.github/ CODEOWNERS, PR 양식, 의존성 취약점 정책 .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를 모른다.

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를 쓴다. 첫 실행 진입점은 하나다.

scripts/bootstrap-local.sh

이 스크립트는 네 단계를 차례로 돈다: 컴파일, PostgreSQL 기동, 앱 이미지 빌드와 기동, GET /api/healthcheck 확인. 단계마다 bootstrap N/4 줄을 찍고, 실패하면 그 단계에서 멈춘다. 쓰는 compose 파일은 루트의 compose.yaml 하나다.

성공하면 이 명령이 HTTP 200을 돌려준다.

curl -fsS http://localhost:8080/api/healthcheck

내릴 때는 저장소 루트에서 --profile '*'를 붙인다. 붙이지 않으면 profile로 띄운 db 같은 서비스가 남는다.

docker compose --profile '*' down

환경 변수는 .env(로컬 실행 입력)와 .env.example(배포 환경 변수의 복사·검증 계약)에 있다. 키 목록과 설명은 docs/build.md와 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 「기능 추가 = 한 줄 + env」 표.
  • 기능마다 조립·검증 상태: docs/capability-status.md.
  • capability 모듈이 지켜야 하는 규칙과 완료 기준 7개: docs/manual/10-capabilities.md.

뒷단 서비스는 compose.yaml의 profile로 고른다(docker compose --profile redis up -d --wait). profile 목록은 그 파일 머리에 있다.

문서 지도

모든 문서 폴더의 지도는 docs/README.md다. 무엇을 하려는지에 따라 여기서 시작한다.

하려는 일 시작할 곳
이 저장소에서 일하기(새 기능, 개선, 조사, 문서, 운영, 일 나누기) 작업 매뉴얼 docs/work/README.md. 지도는 AGENTS.md
새 업무 기능 만들기 개발 매뉴얼 docs/manual/README.md와 생성 명령 scripts/new-feature.sh
계약 확인하기(HTTP, 오류 코드, env 키, 메트릭, 헤더) 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, app-bootstrap).

검증

명령은 저장소 루트에서 돌린다. 일상 피드백은 바꾼 leaf 하나와 아키텍처 검사다. leaf의 Gradle 경로는 registry의 gradle_path에서 읽는다.

./gradlew :app-bootstrap:check --console=plain
./gradlew architectureCheck --console=plain

./gradlew test는 모든 leaf의 test를 돌리므로 일상 명령으로 쓰지 않는다. PR·main·태그 단계에서 무엇이 도는지, 바꾼 것에 맞춰 무엇을 더 돌릴지는 docs/work/reference/gates.md가 정한다. 게이트 태스크 하나하나의 설명은 docs/build.md 「build.gradle — 빌드 / 검증 게이트」다.

문서를 고쳤으면 저장소 루트에서 python3 scripts/check-docs.py를 돌린다. 규칙은 docs/README.md 「문서 검사」다.

새 서비스로 시작하기

이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 이 목록이 템플릿 재사용 체크리스트의 정본이다.

  1. settings.gradle의 rootProject.name을 새 서비스 이름으로 바꾼다.

  2. 패키지 루트 dev.caskeleton을 서비스 패키지로 바꾼다. Java 소스만이 아니라 AutoConfiguration.imports·spring.factories·빌드 스크립트·설정 파일·생성 명령 템플릿, SpotBugs 제외 목록(config/spotbugs/), 루트 build.gradle과 build-logic의 group, registry와 공개 API 스냅숏(docs/registries/, docs/architecture/, docs/notification/api-surface-snapshot.txt)도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다. build-logic 자신의 패키지(dev.caskeleton.buildlogic)는 앱 패키지가 아니라 그대로 둬도 된다.

    git grep -l -e 'dev\.caskeleton' -- src scripts config build.gradle docs/registries docs/architecture docs/notification
    git grep -l -e '"dev\.caskeleton"' -- build-logic/src/main
    

    SpotBugs 목록을 빼먹으면 qualityCheck가, 스냅숏을 빼먹으면 각 leaf check의 API surface 검사가 실패한다.

  3. CaSkeletonApplication을 새 애플리케이션 이름으로 바꾼다.

  4. 새 업무 기능은 scripts/new-feature.sh <FeatureName>으로 만들고 docs/manual/README.md 순서대로 채운다. 모듈 이름과 경계는 그대로 둔다.

  5. 쓰는 capability의 runtimeOnly 줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다.

  6. 라이브러리 패키지 dev.cakit.*은 바꾸지 않는다. 별도 repo에서 받는 라이브러리의 패키지이고, 2번이 바꾸는 dev.caskeleton과 이름이 겹치지 않게 정했다. 라이브러리 목록은 관련 저장소다.

  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 「링크 검사」)로 찾아 고친다. 템플릿을 upstream으로 두고 merge해 받으면 그 폴더에서 충돌이 날 수 있다(docs/upgrade/2026-11-docs-records.md).

이름을 바꾼 뒤에는 위 「검증」의 두 명령과 ./gradlew :app-bootstrap:test --console=plain을 돌린다.

규칙과 기여

  • 규칙의 정본이자 일을 시작할 때 읽는 지도는 AGENTS.md다. 「HARD-STOP」 조건을 어기면 동작하더라도 병합하지 않는다. Claude Code 세션은 CLAUDE.md가 이 파일을 가져온다.
  • 일의 종류별 절차는 docs/work/README.md다.
  • 각 모듈의 지역 규칙은 가장 가까운 src/**/AGENTS.md다.
  • 커밋 정책과 메시지 형식은 docs/work/README.md 「커밋」이다. PR은 .github/pull_request_template.md 양식을 채운다.
S
Description
No description provided
Readme
46 MiB
Languages
Java 97.6%
Python 1.1%
Shell 0.9%
Go Template 0.3%