문제(round8 확인 리뷰 RR8-01-01, 회귀): - GraphQL 매퍼가 원인 사슬의 첫 carrier를 앱이 등록한 매핑보다 먼저 본다. 앱이 GraphQlExceptionResolver에 등록한 실패가 하위 실패(예: PersistenceFailureException)를 원인으로 들면 등록한 코드 대신 carrier 코드로 답한다(ORDER_UNAVAILABLE 대신 DB_UNAVAILABLE). r8-f1 전에는 등록한 코드였다. 소유자 결정 「감싼 carrier를 전송이 읽는 법」은 "바뀌는 응답은 500 INTERNAL_ERROR이던 경우뿐"을 전제로 했다. 고른 방법(소유자 결정 2026-11-07, 리뷰 README 19.4절 ① (a)): - 판정 순서를 플랫폼 거부 → 실패 자신이 carrier → 등록된 application 매핑 → 원인 사슬의 첫 carrier → 거부된 인자 → 가림으로 바꾼다. sharedCodeOf는 실패 자신이 carrier가 아니고 등록 매핑이 있으면 원인 사슬을 보지 않는다. web에서 앱의 도메인 advice가 먼저 받는 것과 같다. - 로그 줄은 어느 단계가 답하든 원인 사슬의 첫 carrier로 정한다(기본값). 등록 매핑이 답해도 그 안의 서버 쪽 carrier는 그 줄(persistence는 분류 한 줄)을 남긴다. 버린 안: 등록 매핑이 답하면 아무 줄도 남기지 않기 (r8-f1 전 동작) — DB 장애의 흔적이 사라진다. - 버린 안: (b) 지금 순서를 두고 문서에 적기 — 앱에 원인 버리기를 강요하고 web과 계속 다르다. (c) 등록 매핑을 실패 자신이 carrier인 경우보다도 먼저 — r8-f1 전에도 없던 변화라 범위가 넓다. - 같은 내용을 GraphQL README·CLAUDE.md, GraphQlExceptionResolver· ApiErrorCarrier.firstIn Javadoc, shared-contract README, 결정 색인, 업그레이드 안내 B-45·B-46에 적었다. 위험·한계: - 실패 자신이 carrier인 타입(예: LockAcquisitionTimeoutException)을 등록한 GraphQL 매핑은 계속 쓰이지 않는다. B-45와 resolver Javadoc에 적었다. - main 대비 GraphQL 응답은 바뀌지 않는다(r8-f1이 아직 main에 없다). 합치지 않은 안내 행 B-45·B-46만 최종 동작으로 고쳤다. 검증(desktop, flock /tmp/claude-gates/heavy.lock, --no-build-cache, 로그 ~/r9-g1-inbound-logs/): - RED(기준3eb3b067+ 테스트만, 트리 7c45e303): :adapter:inbound:graphql:test --tests GraphQlWireErrorMapperTest --tests GraphQlArgumentBindingFailureTest rc=1, 22건 중 1건 실패 aRegisteredFailureThatKeepsACarrierAsItsCauseIsAnsweredWithItsRegisteredCode (기대 [ORDER_UNAVAILABLE, BUSINESS], 실제 [DB_UNAVAILABLE, DEPENDENCY]). 지킴 테스트 둘(실패 자신이 carrier인 등록 타입, 등록 매핑이 답해도 남는 carrier 줄)은 기준에서도 통과. red/R1b-graphql.log - GREEN(이 커밋 트리d00d1f4d): :adapter:inbound:graphql:check :shared-contract:check rc=0, graphql 407·shared-contract 269건 실패 0·skip 0, FROM-CACHE 0. green/A1-check.log - python3 scripts/check-work-docs.py rc=0(이 커밋 트리, 이력 ID 0). Refs: docs/reviews/2026-11-03-rereview/README.md 19절 RR8-01-01, 19.4절 ①
16 KiB
adapter:inbound:graphql — inbound GraphQL adapter (skeleton machinery)
Registered identity
- Module ID:
adapter-inbound-graphql - Gradle path:
:adapter:inbound:graphql - Focused test (derived from Gradle path):
./gradlew :adapter:inbound:graphql:test --console=plain - Runtime baseline: Java 21; repository framework baseline: Spring Boot 4.0.0.
- Registry SSOT:
src/config/architecture/modules.json.
Package root: dev.caskeleton.adapter.inbound.graphql.
코드 주석에서 덜어낸 설계 결정의 근거는 README.md 가 모아둔다 (이 문서는 모듈 규칙 SSOT).
플랫폼 모듈 = sub-package (Gradle 모듈 아님)
GraphQL 플랫폼 설계서는 Stable 16개 + Advanced 12개 "모듈"을 말하지만, 이 구현은 그 28개를 이
leaf 안의 bounded sub-package 로 매핑한다(선례: httpclient leaf 가 366개 java 파일을 같은
방식으로 담는다). GraphQL 표면은 하나의 인바운드 전송 경계이고, 그 내부 분할을 leaf 정체성
SSOT(src/config/architecture/modules.json)까지 밀어올리지 않는다는 선택이다.
이는 레지스트리가 닫혀 있어서가 아니다. modules.json 은 확장 가능하며, 실제로 자매
플랫폼인 messaging 은 정반대 선택을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 개수는
modules.json 이 소유하며 여기서 되풀이하지 않는다 — 산문에 적힌 숫자는 leaf 가 하나 추가되는 순간
낡는다. 즉 이 레포에는 두 패턴이 공존한다:
| 방식 | 경계 강제 | |
|---|---|---|
| messaging | 레지스트리에 leaf 등록 | Gradle 의존 게이트 |
| graphql | 단일 leaf 내 sub-package | 아래 ArchUnit 테스트 (전송 경계만) |
어느 쪽으로 통일할지는 미결 아키텍처 결정이다.
sub-package 사이의 경계(Stable↔Advanced 방향, 모듈 레코드)를 값으로 선언하던 moduleboundary/
모델과 부팅 때마다 컨트롤러를 리플렉션으로 검사하던 architecture/ 는 2026-09-25 에 삭제했다
(docs/capability-status.md 제거 표). 지금 기계가 지키는 것은 전송 경계 두 가지뿐이다 —
GraphQlTransportBoundaryArchitectureTest(ArchUnit, 이 leaf 패키지 대상):
- resolver(
@SchemaMapping계열·@BatchMapping) 시그니처는 전송 타입만 쓴다. 반환·인자 타입과 그 제네릭 인자에 rawMap, persistence 매핑 타입(@Entity/@Document/@Table등, 단순명 매칭), domain·outbound adapter·JPA/Hibernate/Spring Data/JDBC/Mongo/AWS/gRPC/Kafka 타입이 오면 실패한다. - raw
DataFetcher구현은scalar·schema·execution패키지에만 둔다.
두 규칙 모두 위반 fixture 로 실제로 잡히는지 같은 테스트가 확인한다. graphqlStableTest 의
required-class 검사가 이 테스트가 조용히 사라지는 것을 막는다.
Responsibility
- GraphQL 전송 인프라만: 최소 health 스키마(
skeleton.graphqls) +HealthGraphqlController, 프로토콜 에러 매핑(error/GraphQlWireErrorMapper). Spring for GraphQL 이 스키마와 컨트롤러를 자동 합성/바인딩하도록 얹는 얇은 계층이다. - 그 위에 GraphQL API 실행 플랫폼(
...graphql하위 sub-package 군)이 스키마 계약·전송 프로파일·실행 정책·비용 한계·DataLoader·페이지네이션·에러/보안 경계·관측을 소유한다. 플랫폼은 여전히 feature-agnostic 이며 정책·계약·검증 기계만 제공한다. - feature-agnostic:
classpath:graphql/**스키마와 모든@Controller@QueryMapping/@MutationMapping을 generic 하게 합성한다. WorkLog 등 구체 기능을 이름으로 알지 않는다. - 있으면 켜진다: 서비스가
app-bootstrap/build.gradle에runtimeOnly project(':adapter:inbound:graphql')한 줄로 고른다(기본 조립에는 없다).APP_GRAPHQL_ENABLED=false(app.graphql.enabled)만 끄며, 그때GraphQlActivationEnvironmentPostProcessor가 Spring GraphQL 자동 설정도 exclude 한다. 실제 활성화 시 composition root 는 인증/인가·CORS 정책과 GraphiQL/introspection 운영 설정을 함께 명시해야 한다.
Error-code ownership
docs/registries/error-codes.yaml is the skeleton-wide OperationalError SSOT; it is not a
catch-all registry for transport-specific presentation codes. GraphQL therefore keeps its own finite
platform wire-code catalogue in GraphQlErrorCode.
- GraphQL platform mappers must use
GraphQlErrorCode.platform(...). An unregistered platform code fails immediately. - application/domain
ApiErrorCodevalues remain a separate namespace and pass through withGraphQlErrorCode.of(...); GraphQL must not rename product errors. Only a registeredApiErrorCodereaches the wire this way — a DataLoader per-key failure carries one, never a free string (owner decision 2026-09-25). - new GraphQL-owned platform codes use the
GRAPHQL_prefix. The existing unprefixed platform values are frozen legacy wire contracts and are listed explicitly bylegacyUnprefixedPlatformCodes(). - modelled-only capability codes are not added to
platformCodes()until that capability reaches the shipped request path.
GraphQlErrorCodeCatalogTest pins the exact shipped catalogue, the prefix rule and the
application/platform namespace split.
Allowed
:application-core,:domain-core,:shared-contract.:application-core는 선언만이 아니라 실제 의존이다 — object 인가의 답하는 계약(dev.caskeleton.application.security.ObjectAccessPolicy)이 거기 살기 때문이다. 이 leaf 가 그 계약을 소유했다면 application 구현체가 인바운드 전송을 컴파일 의존해야 했고, 그건 의존 방향이 뒤집힌다.spring-boot-starter-graphql(Spring Boot BOM 관리 — 버전 명시 없음).- test scope 에 한해
spring-boot-starter-web(random-port 전송 테스트용),spring-boot-starter-security(HTTP 인증/CORS qualification 용),io.micrometer:micrometer-core(실제MeterRegistry로 metric label cardinality 를 측정). java-test-fixtures— 계약 스위트·통합 fixture·in-memory 스텁은src/testFixtures/java가 소유하고 production jar 에 들어가지 않는다.- test scope 에 한해
archunit-junit5— 전송 경계 규칙(GraphQlTransportBoundaryArchitectureTest).
서버는 이 leaf 가 고르지 않는다. production 파일 중 org.springframework.web·
org.springframework.http 을 import 하는 것은 하나도 없다(servlet API 는 body 상한 필터만
compileOnly 로 쓴다). 서버 선택은 composition root 의 결정이고, gradle.lockfile 이 이를
고정한다(spring-boot-starter-web·spring-webmvc·spring-webflux·tomcat-embed-* 전부
testCompileClasspath,testRuntimeClasspath 만). 템플릿은 servlet 단일 스택이라 실행
프로파일(execution-profile)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다.
annotationProcessor로spring-boot-configuration-processor—GraphQlPlatformProperties가@ConfigurationProperties이므로ca.spring-configconvention plugin이 주는 패리티 게이트가 이 선언을 요구한다.
Forbidden
- outbound 어댑터(
:adapter:outbound:*)에 대한 직접 의존 — 인바운드는 application 아웃바운드 포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnitINBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS, 일반..adapter.inbound..규칙이 이 모듈을 자동 커버 — per-module 규칙 추가 불필요). - 프로덕션 feature 쿼리/뮤테이션을 스켈레톤에 두는 것 — health 표면만 (web 의
HealthcheckController와 동일 원칙). feature 스키마/컨트롤러/매퍼는 sample 모듈이 소유한다. - 모듈별
yml— 설정은 프레임워크spring.graphql.*로 composition-rootapplication.yml에 산다.
Error mapping (Category → ErrorType)
모든 client 에러는 error/GraphQlWireErrorMapper 하나를 거친다 — 전송 interceptor, 실행 전
pipeline(instrumentation), data fetcher resolver 세 곳이 같은 bean 을 받는다. 순서는 플랫폼 거부
(예외가 구현한 error/GraphQlPlatformRejection) → 실패 자신이 ApiErrorCarrier면 그 ApiErrorCode → 등록된
application 매핑(GraphQlExceptionResolver) → 원인 사슬의 첫 carrier → IllegalArgumentException·인자 binder의
BindException=BAD_PARAMETER(2026-11-07 소유자 결정). 등록 매핑이 원인 사슬의 carrier보다 먼저라, 앱이 등록한
실패는 하위 실패를 원인으로 들어도 등록한 코드로 답한다. 실패 자신이 carrier인 타입은 등록해도 쓰이지 않는다. 어디에도 안
걸린 예외는 INTERNAL_ERROR 로 가려지고, 같은 executionId 로 ERROR 로그 한 줄이 남는다. client 문구는
shared-contract ClientErrorMessages(Category 별 한국어 표), retryable 은 코드의 값이다. Category →
wire category/ErrorType 표는 mapper 의 RENDERINGS 하나뿐이고 README.md에 옮겨 둔다.
DataLoader 키 실패는 등록된 ApiErrorCode 만 싣는다(GraphQlBatchLoadException, 2026-09-25 소유자 결정).
향후 adopter 의 feature 기여 방법
- 스키마: adopter feature 가
src/main/resources/graphql/*.graphqls를 두면classpath:graphql/**병합으로 합칠 수 있다. - 핸들러: adopter 가
@Controller+@QueryMapping/@MutationMapping빈을 등록하면 자동 바인딩된다. - 도메인 예외 매핑: adopter 는 자신의
DataFetcherExceptionResolver를 추가하거나ApiErrorCarrier를 사용해 안정적 코드로 매핑할 수 있다.
현재 sample 에 feature GraphQL schema/controller/resolver 가 있다고 가정하지 않는다. 이 leaf 는 health 스키마만 소유한다.
구현된 플랫폼 범위 — 등급으로 말한다
"구현됐다" 는 네 가지 서로 다른 사실을 한 단어로 덮는다. 그래서 capability 마다 아래 등급을 쓰고, 현재 등급보다 높게 표현하지 않는다.
| 등급 | 의미 |
|---|---|
modelled |
정책·계약 객체가 있고 단위 테스트가 있다. 요청 경로에는 없다. |
wired |
Spring 실행 경로에 연결돼 있고, 실제 endpoint 테스트가 그 사실을 증명한다. |
integration-verified |
실제 외부 시스템(datastore/broker) 과의 통합 증거가 있다. |
production-verified |
실부하·장애 시나리오 증거가 있다. |
| Capability | 등급 | 증거 |
|---|---|---|
| 실행 파이프라인 / 인가 / cost 예산 | wired |
systemTest/runtime/GraphQlPlatformExecutionPathTest (random-port, 거부 시 resolver 호출 0회) |
depth/complexity 제한 (cost/) |
wired |
같은 테스트의 depth/alias/complexity 케이스 |
preparsed document cache (execution/) |
wired |
GraphQlPreparsedDocumentAdapter + 같은 테스트의 캐시 hit 케이스 |
커스텀 scalar (scalar/) |
wired |
같은 테스트의 scalar coercion 케이스 |
요청 크기 (http/, body limit filter) |
wired |
runtime/GraphQlPlatformWebInterceptorRequestBoundsTest(auto-configured interceptor 로 byte·shape·extension 거부), http/GraphQlRequestBoundsTest |
관측 tag cardinality (observation/) |
wired |
runtime/GraphQlRequestObservationConventionAdapter 가 Spring 의 ExecutionRequestObservationConvention 을 구현해 Boot 의 GraphQlObservationAutoConfiguration 이 이 컨벤션을 가져간다. autoconfigure/GraphQlObservationWiringTest(프레임워크가 실제로 해석), runtime/GraphQlRequestObservationConventionAdapterTest(실제 MeterRegistry 에 임의 이름 10,000개 → series 1개) |
object 인가 (security/) |
modelled |
답하는 계약은 중립 dev.caskeleton.application.security.ObjectAccessPolicy 가 소유하고 이 leaf 는 ApplicationObjectAuthorization 매핑만 가진다. 실행 경로에 연결하는 configuration 은 없다 |
DataLoader/batching (dataloader/) |
wired |
runtime/GraphQlBatchLoaderRegistrationTest (실제 graphql-java 실행 + Spring BatchLoaderRegistry, 50 parent → 3 downstream 호출), dataloader/GraphQlBatchContractTest |
요청 deadline (maxExecutionTime) |
wired |
systemTest/runtime/GraphQlRequestDeadlineTest(virtual thread: deadline 근처 REQUEST_TIMEOUT, 하위 필드 미실행), GraphQlRequestDeadlineOnRequestThreadTest(요청 스레드: 느린 resolver 가 끝난 뒤 응답 — 한계). 이미 도는 resolver 는 끊지 않는다(README 「요청 deadline」) |
| per-parent fetch(N+1) 신호 | wired |
systemTest/runtime/GraphQlPerParentFetchTest(일반 @SchemaMapping 자식 → WARN 1줄 + graphql.per.parent.fetch, registrar 자식 → 조용함). 거부하지 않는다 |
cursor 서명·connection (pagination/), fetch profile (fetch/) |
라이브러리 | 요청 경로에 없다. 서비스가 직접 호출한다 — README "라이브러리 API". autoconfigure/GraphQlPolicyRequestPathTest 가 auto-configuration 이 codec·key ring 을 만들지 않음을 고정 |
| 실부하·장애 | 미달성 | 증거 없음 |
여전히 미구현인 것:
- feature GraphQL schema/resolver — 이 leaf 는 health 표면만 소유한다(변경 없음).
- 실부하 성능/장애 시나리오 증거 — 없다. 시나리오 카탈로그와 릴리스 게이트(
release/,advanced/release/)와 스키마 호환성 비교기(compat/)는 호출하는 곳이 없어 2026-09-25 에 삭제했다. - 실제 datastore 통합 증거 — 없다.
advanced/**(SSE·RSocket·federation·incremental·HTTP GET·persisted operation·subscription replay 등)는 바인딩되지 않는 feature flag gate 뒤의 모델뿐이어서 2026-09-25 에 삭제했다 (docs/capability-status.md제거 표). 다시 필요하면 Spring GraphQL/graphql-java SPI 를 구현하는 형태로 새로 만든다.
Test
cd src
./gradlew :adapter:inbound:graphql:test --console=plain
./gradlew :adapter:inbound:graphql:graphqlTransportQualificationTest --console=plain
테스트 레인:
./gradlew :adapter:inbound:graphql:graphqlStableTest --console=plain # GraphQlTransportBoundaryArchitectureTest만, skip 금지
./gradlew :adapter:inbound:graphql:systemTest --console=plain # 23 tests (실제 HTTP 서버)
graphqlStableTest 는 GraphQlTransportBoundaryArchitectureTest 가 실행되지 않거나 skip 되면
실패한다(build.gradle 의 strict lane requires + rejectSkipped). 같은 클래스는 test 에서도 돈다.
아티팩트 게이트
./gradlew :adapter:inbound:graphql:test --tests '*GraphQlProductionClassesTest' --console=plain
./gradlew :adapter:inbound:graphql:verifyGraphQlApiSurface --console=plain
-
GraphQlProductionClassesTest— production 클래스에testkit/InMemory/ForTests/Fixture/TestContext가 하나라도 있으면 실패한다(test의 일부). 테스트용 request context 헬퍼(testkit/GraphQlRequestContexts)는src/testFixtures/java가 소유한다. -
verifyGraphQlApiSurface—docs/architecture/graphql-api-surface.txt스냅샷과 실제 public 타입 목록이 다르면 실패한다. 단일 jar 안에서public은 모든 adopter 에게 public 이므로, 표면 증가는 리뷰 결정이지 빌드 부산물이 아니다. 승인 후:./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange. -
mutation 멱등성 — 저장소에 연결된 적 없는
GraphQlMutationIdempotencyInterceptor·context· fingerprint 와idempotencyKeyextension 허용을 2026-09-25 에 삭제했다. Stable 기본GraphQlExtensionsPolicy는 어떤 extension key 도 허용하지 않는다. 요청 재생 멱등성이 필요하면 applicationIdempotencyExecutor를 use case 안에서 쓴다.