DongHyeonka 1ab96de01d test(objectstorage): 포트 계약을 포트 소유 leaf에 두고 fake와 adapter가 함께 통과하게 한다
문제: capability 기준 5(docs/manual/10-capabilities.md)는 포트를 가진 모듈의
testFixtures에 포트 계약을 두고 fake와 실제 adapter가 모두 통과하게 한다.
application-objectstorage에는 testFixtures도 fake도 없었다. 포트 수준 동작은 adapter
안의 local-dev 시험으로만 봤고, 포트 인터페이스는 결과와 예외를 적지 않았다.
capability-status는 app-bootstrap 통합 시험이 MinIO로 조립한다고 적었지만 실제로는
local-dev다.

고친 것:
- 포트 여덟의 Javadoc에 결과(APPLIED·REPLAYED·REJECTED 등)와 예외 타입을 적었다.
  IllegalArgumentException은 요청 그대로를, IllegalStateException은 지금 상태에서의
  거절이다. 유스케이스가 감싸 기능 오류로 바꾸고, 설정이 틀린 destination은 조립
  오류(500)로 바꾼다(AGENTS 규칙). 예외 메시지는 구현의 것이라 계약이 단언하지 않는다.
- testFixtures testkit: 계약 셋(ManagedObjectStoragePortContract 관리 게시·조회·
  전송·복구 조회·회수, StagedObjectPublicationPortContract 단계 게시·handoff·중단,
  ObjectScanMaintenancePortContract scan gate), in-memory fake InMemoryObjectStorage,
  destination 설명 ObjectStorageDestinationPolicy.
- fake(이 leaf test)와 adapter routing 구현(local-dev, adapter test contract/LocalDev*)이
  같은 계약을 상속한다. adapter 쪽 destination 설명은 조립된 policySnapshot에서 읽는다.
- adapter에서 계약이 드러낸 것 둘:
  - 실패한 managed 게시를 다시 하면 이번 호출이 게시했는데도 REPLAYED였다(stage 재시도는
    APPLIED). 이제 PUBLISHED로 바꾼 호출 하나만 APPLIED다. 같은 key로 겹친 호출은
    REPLAYED다(ManagedPublicationOutcomeTest가 겹침을 결정적으로 재현한다).
  - 검증한 뒤 중단한 stage를 다시 검증하면 REPLAYED였다. 중단된 operation의 검증을
    거절한다.
- 문서: application-objectstorage AGENTS·README, adapter README 「포트 계약」,
  TESTING_STRATEGY 9.4, capability-status Object storage 증거 칸.

버린 대안: MinIO에서 포트 계약 돌리기. S3 provider는 readiness registry에서 아직 배포
대상이 아니다(docs/registries/object-storage-readiness.yaml). 포트 경로를 MinIO로 묶는
일은 S3를 배포 대상으로 올리는 일과 같이 간다. MinIO에서는 provider 계약이 돈다.
남은 것: adapter 전용 ObjectStorageProviderException이 포트 밖으로 나가 바이트
불일치·consumer 실패는 계약이 unchecked 예외까지만 단언한다(RR9-03-34, 따로 고친다).

검증: desktop, :application-objectstorage:check :adapter:outbound:objectstorage:check
:app-bootstrap:architectureTest architectureCheck -p build-logic test 726건 실패 0.
RED: main에 ManagedPublicationOutcomeTest만 → 실패. 돌연변이: adapter의 회수 재시도를
REPLAYED→APPLIED로 바꾸면 계약 1건이 실패한다.

Refs: RR9-03-31, RR9-03-35, RR9-04-46
2026-11-13 13:49:40 +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%