DongHyeonka e69c321eca fix(graphql)!: GraphQL 지표에 플랫폼 tag를 붙이고 key 묶음을 고정한다
GraphQlResolverObservationConvention·GraphQlDataLoaderObservationConvention
bean이 있지만 Spring for GraphQL observation에 붙지 않는다. 그래서
graphql.datafetcher·graphql.dataloader timer는 Spring 기본 tag
(graphql.field.name, graphql.loader.name, graphql.error.type)를 달고,
플랫폼이 정한 schema 좌표·resolver 무게·batch 크기 tag는 아무 지표에도
없다. 두 convention의 tag 이름도 뜻과 맞지 않는다: 무게를
graphql.operation.type으로, batch 크기를 graphql.complexity.bucket으로
단다. graphql.request는 오류가 없거나 복잡도를 세기 전에 끝난 요청에서
error.type·graphql.complexity.bucket을 빼는데, Prometheus registry는
이름이 같고 key 묶음이 다른 meter를 버린다. 먼저 등록된 쪽만 남고
성공이나 실패 한쪽이 /actuator/prometheus에서 사라진다.

Spring의 DataFetcherObservationConvention·DataLoaderObservationConvention을
구현한 adapter 둘(runtime 패키지)을 두고 GraphQlObservationConfiguration이
@ConditionalOnMissingBean으로 등록한다. resolver는 부모 타입과 field
이름으로 schema 좌표(Type.field)를 만들고, 좌표로 이름 붙일 수 없는
field(_Service.sdl 같은 federation field)는 unnamed와 기본 무게로 같은
key를 단다. DataLoader는 등록한 loader 이름, 또는 Spring이
@BatchMapping loader에 붙이는 schema 좌표(Book.author)를 이름으로 쓰고,
둘 다 아니면 unknown이다. graphql.request는 오류가 없으면
error.type=NONE, 복잡도를 세지 않았으면 graphql.complexity.bucket=unknown을
단다. tag 이름을 graphql.resolver.weight·graphql.batch.size.bucket으로
고치고 cardinality 허용 목록, metrics.yaml 세 행(Micrometer가 다는 error
tag 포함), 공개 API 스냅숏을 맞춘다. 응답 path와 batch key는 싣지 않는다.

버린 안: Spring 기본 convention을 두고 registry만 그 tag로 적기. 플랫폼
convention이 죽은 코드로 남고, field 이름만으로는 타입이 다른 같은 이름
field를 가를 수 없다. 기본 convention을 감싸 tag만 더하는 안은
graphql.error.type이 Micrometer의 error tag와 같은 값을 한 번 더 싣는다.

위험: 세 timer의 tag가 바뀐다. 옛 tag로 거른 대시보드·경보는 비고,
docs/upgrade/2026-11-round9-followups.md 1~4행이 옮기는 법을 적는다.
클래스 이름으로 등록한 loader는 unknown 하나로 묶인다. 자기
DataFetcherObservationConvention·DataLoaderObservationConvention bean을
둔 서비스는 그 bean이 그대로 쓰인다.

검증: desktop :adapter:inbound:graphql:check :adapter:inbound:graphql:systemTest
:adapter:inbound:graphql:verifyGraphQlApiSurface, scripts/verify.sh pr.

BREAKING CHANGE: graphql.datafetcher·graphql.dataloader timer의 tag가
graphql.schema.coordinate·graphql.outcome·graphql.resolver.weight와
graphql.dataloader.name·graphql.outcome·graphql.batch.size.bucket으로
바뀐다. graphql.request는 error.type=NONE·graphql.complexity.bucket=unknown을
단다. 두 convention의 tag key도 바뀐다.
Refs: round9 그룹 A 범위 밖 후속 1
2026-11-13 19:30:12 +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%