GraphQL cursor·connection 예외는 Javadoc이 「안정 요청 오류 코드」라면서 플랫폼 거부가 아니라 INTERNAL_ERROR와 ERROR 로그가 된다. STOMP ERROR frame은 code만 싣고, 원인 사슬 어디에 IllegalArgumentException이 있든 BAD_PARAMETER로 본다(다른 전송은 실패 자신만 본다). STOMP broadcast는 모든 인증 세션에 가는데 projector가 무엇을 실어도 되는지 규칙이 없다. maxInputListElements Javadoc은 실제보다 넓은 상한을 약속한다. - 두 예외를 GraphQlPlatformRejection으로 만들고 GRAPHQL_CURSOR_REJECTED· GRAPHQL_CONNECTION_REJECTED를 catalog에 더한다. - STOMP 오류 처리기는 MessagingException 포장을 벗긴 실패 자신만 IAE로 보고, 등록된 코드면 error-category·error-retryable header를 더한다(gRPC trailer와 같은 이름·값). - broadcast 규칙(모든 tenant의 인증 사용자가 읽어도 되는 것만)을 projector Javadoc·README·AGENTS에 적는다. 버린 안: destination을 tenant별로 나누기(projector가 tenant를 모르고, simple broker는 R1 증거라 범위 밖). - maxInputListElements Javadoc을 실제 검사 범위로 좁힌다. 위험: client가 보는 GraphQL 코드와 STOMP header가 바뀐다. docs/upgrade/2026-11-round9-authz.md 12~13행. 검증: desktop :adapter:inbound:graphql:check·systemTest, :adapter:inbound:websocket:check·systemTest rc=0(묶음 전체 실행). Refs: RR9-02-19, RR9-02-31, RR9-03-14, RR9-03-29 BREAKING CHANGE: GraphQL cursor·connection 거부 코드와 STOMP ERROR frame의 error-code(묻힌 IAE)·새 header. docs/upgrade/2026-11-round9-authz.md 12~13행.
13 KiB
adapter:inbound:graphql — inbound GraphQL 어댑터(골격 장치)
등록 정보
- 모듈 ID:
adapter-inbound-graphql - Gradle 경로:
:adapter:inbound:graphql - 이 모듈만 시험(Gradle 경로에서 나온 명령):
./gradlew :adapter:inbound:graphql:test --console=plain - 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은
gradle/libs.versions.toml이 정한다. - registry 정본:
gradle/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 가 여러 기능 package를 같은
방식으로 담는다). GraphQL 표면은 하나의 인바운드 전송 경계이고, 그 내부 분할을 leaf 정체성
SSOT(gradle/modules.json)까지 밀어올리지 않는다는 선택이다.
이는 레지스트리가 닫혀 있어서가 아니다. modules.json 은 확장 가능하다. 자매 플랫폼 messaging 은
한때 정반대 선택을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 그 플랫폼은 2026-11-08 별도 repo
messaging-library로 옮겨 버전으로 받는다(docs/work/reference/related-repos.md). 그래서 이 repo 안에는 비교할 다른
패턴이 없다. GraphQL 내부를 leaf로 나누는 일은 레지스트리에 leaf를 더하는 변경이고, 경계 강제는 지금
아래 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 검사가 이 테스트가 조용히 사라지는 것을 막는다.
책임
- 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 등 구체 기능을 이름으로 알지 않는다. - 있으면 켜진다: 서비스가
src/bootstrap/app/build.gradle에runtimeOnly project(':adapter:inbound:graphql')한 줄로 고른다(기본 조립에는 없다).APP_GRAPHQL_ENABLED=false(app.graphql.enabled)만 끄며, 그때GraphQlActivationEnvironmentPostProcessor가 Spring GraphQL 자동 설정도 exclude 한다. 실제 활성화 시 composition root 는 인증/인가·CORS 정책과 GraphiQL/introspection 운영 설정을 함께 명시해야 한다.
오류 코드 소유
docs/registries/error-codes.yaml은 골격 전체의 OperationalError 정본이다. 전송 계층마다 다른 표현
코드를 모두 받는 registry가 아니다. 그래서 GraphQL은 자기의 유한한 플랫폼 wire 코드 catalog를
GraphQlErrorCode에 둔다.
- GraphQL 플랫폼 mapper는
GraphQlErrorCode.platform(...)을 써야 한다. 등록되지 않은 플랫폼 코드는 바로 실패한다. - application·domain
ApiErrorCode값은 별도 namespace로 남고GraphQlErrorCode.of(...)로 그대로 지나간다. GraphQL은 제품 오류의 이름을 바꾸면 안 된다. 이 길로 wire에 닿는 것은 등록된ApiErrorCode뿐이다 — DataLoader의 키별 실패도 그것을 싣고, 자유 문자열을 싣지 않는다(소유자 결정 2026-09-25). - GraphQL이 가진 새 플랫폼 코드는
GRAPHQL_접두어를 쓴다. 접두어 없는 기존 플랫폼 값은 얼려 둔 옛 wire 계약이고legacyUnprefixedPlatformCodes()가 하나씩 적는다. - 모델만 있는 capability 코드는 그 capability가 출하하는 요청 경로에 닿기 전까지
platformCodes()에 더하지 않는다. 서비스 resolver가 부르는 라이브러리(pagination/의 cursor·connection)의 거부 코드는 더한다. resolver 안에서 던져지면 그 요청의 오류로 wire에 닿기 때문이다.
GraphQlErrorCodeCatalogTest가 출하하는 catalog 전체, 접두어 규칙, application·플랫폼 namespace 분리를
고정한다.
허용
: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-restclient·spring-boot-resttestclient(그 테스트가 부르는TestRestTemplate),spring-boot-starter-graphql-test(GraphQlTester),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—GraphQlPlatformSettings가@ConfigurationProperties이므로ca.spring-configconvention plugin이 주는 패리티 게이트가 이 선언을 요구한다.
금지
- 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 스키마/컨트롤러/매퍼는 그 기능을 가진 서비스가 소유한다. config/graphql.yml밖의 설정 파일 — 이 leaf의 설정 기본값은 그 파일 하나다. 의존성에 support가 없어 공용ModuleDefaultsEnvironmentPostProcessor대신GraphQlActivationEnvironmentPostProcessor가 읽는다(manual 10 기준 7 뒤 예외). 전송 설정spring.graphql.*은 composition-rootapplication.yml에 둔다.
오류 대응 (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를 사용해 안정적 코드로 매핑할 수 있다.
템플릿에는 feature GraphQL schema/controller/resolver 가 없다. 이 leaf 는 health 스키마만 소유한다.
구현된 플랫폼 범위 — 등급으로 말한다
표와 자세한 계약은 README.md 「구현된 플랫폼 범위 — 등급으로 말한다」 절이다. 지킬 것:
- capability마다 그 표의 등급을 쓰고, 현재 등급보다 높게 표현하지 않는다(README·문서·커밋 본문 모두).
테스트
./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 # 실제 HTTP 서버
./gradlew :adapter:inbound:graphql:graphqlDocumentContractTest --console=plain # env-keys registry 대조
graphqlDocumentContractTest 는 document-contract 태그 시험(GraphQlDeploymentModeRegistryParityTest)만 돌린다.
저장소 문서를 읽으므로 test 에서는 돌지 않고 main 단계(leaf mainCheck)에서 돈다. 저장소 루트
(ca.repository.root)는 이 lane 만 받는다.
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 안에서 쓴다.