Files
clean-architecture-backend-…/src/adapter/inbound/graphql/README.md
T
DongHyeonka ee5b4e1b7e fix(inbound): 인자 변환 실패는 원인의 carrier와 상관없이 거부로 본다
문제(round8 리뷰 01 「Declined to judge」, 리뷰 README 19.4절 ④):
- 결정 「감싼 carrier를 전송이 읽는 법」이 인자 변환 단계까지 덮는지
  정해지지 않았다. STOMP advice는 @DestinationVariable·@Header의
  ConversionFailedException과 받은 메시지가 실린
  MessageConversionException의 원인에 carrier가 있으면 거부 WARN 한 줄
  대신 그 carrier의 줄(5xx면 ERROR와 예외)을 남긴다. web은 같은 실패에
  원인을 보지 않고 BAD_PARAMETER·VALIDATION_FAILED로 답한다.

고른 방법(소유자 결정 2026-11-07, ④ (a)):
- 인자 변환 단계는 carrier를 보지 않는다. StompHandlerFailureLog가 거부
  판정(clientRefusalOf)을 원인 사슬의 carrier 검색보다 먼저 한다.
  응답 프레임은 그대로다(handler 경로는 프레임을 보내지 않는다).
- web은 지금 동작이 결정과 같아 코드를 바꾸지 않았다. 경로 변수 변환기와
  Jackson creator가 carrier를 던지는 지킴 테스트 둘을 더하고,
  handleTypeMismatch·handleHttpMessageNotReadable Javadoc에 이유를 적었다.
- GraphQL @Argument binder는 변환기가 던진 실패를 binding result에 담고
  BindException의 원인으로 싣지 않아, carrier를 던져도 BAD_PARAMETER다.
  실제 binder 경로 지킴 테스트 하나와 매퍼 Javadoc·README 한 줄.
- 버린 안: (b) 세 전송의 변환 단계가 원인의 carrier를 먼저 본다 — 요청
  형식 오류의 코드가 변환기 구현에 따라 바뀐다.

위험·한계:
- 바뀌는 것은 STOMP 로그 줄뿐이다. 템플릿에는 carrier를 던지는 변환기가
  없다. 안내 B-46에 적었다.
- GraphQL 지킴 테스트는 Spring for GraphQL 2.0.5 binder의 동작에 기댄다.
  binder가 원인을 싣게 바뀌면 그 테스트가 실패한다.

검증(desktop, flock, --no-build-cache, 로그 ~/r9-g1-inbound-logs/):
- RED(기준 3eb3b067 + 테스트만, 트리 4feb83c6): :adapter:inbound:websocket:test
  --tests StompHandlerFailureLogTest rc=1, 13건 중 2건 실패. 두 경우 모두
  기대 WARN "request refused as VALIDATION_FAILED|BAD_PARAMETER by
  <변환 예외>", 실제 ERROR "persistence failure classified as
  DB_UNAVAILABLE ...". red/R2c-websocket.log
- 지킴(RED 없음 — 지금 동작이 결정과 같다): web TransportErrorHandlingTest
  12건(red/R3c-web-guard.log)과 GraphQlArgumentBindingFailureTest
  (트리 7c45e303, red/R1b-graphql.log)가 기준 커밋에서 통과. 변이:
  handleTypeMismatch가 원인의 carrier를 먼저 보게 바꾸면 12건 중 1건
  (경로 변수) 실패, 400 대신 503. red/R7c-web-guard-mutant.log
- GREEN(이 커밋 트리 1a5b4a8f): :adapter:inbound:websocket:check
  :adapter:inbound:web:check :adapter:inbound:graphql:check
  :shared-contract:check rc=0, websocket 107·web 343·graphql 408·
  shared-contract 269건 실패 0·skip 0, FROM-CACHE 0. green2/B1-check.log
- testQualityCheck 첫 실행(green/D16)에서 이 커밋의 테스트 record 둘
  (Signup, `if (email != null)`)이 SpotBugs NP_LOAD_OF_KNOWN_NULL_VALUE로
  걸려 `!email.isEmpty()`로 고쳤다. 고친 테스트로 RED·지킴·변이를 다시
  돌렸고(위 R2c·R3c·R7c), 마지막 트리에서 web·websocket spotbugsTest가
  실행되어 통과했다(green2/D16).

Refs: docs/reviews/2026-11-03-rereview/README.md 19.4절 ④, round8/01-transport-errors.md 「Declined to judge」
2026-11-07 08:22:59 +09:00

27 KiB

adapter-graphql — 설계 결정 참조

인바운드 GraphQL 어댑터 스켈레톤 머시너리 모듈. 패키지 루트: dev.caskeleton.adapter.inbound.graphql.

허용/금지 의존, 모듈 규칙, 설정 knob, 테스트 명령 같은 모듈 규칙은 CLAUDE.md 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 설계 결정의 근거를 모아둔 참조용 기록이다.


왜 스켈레톤에 health 스키마 + 컨트롤러만 두는가

Spring for GraphQL 은 schema-first 다. 빈 스키마로는 부팅이 실패하므로 스켈레톤은 src/main/resources/graphql/skeleton.graphqls 에 최소 스키마(type Query { _health: String! })를 싣고, HealthGraphqlController 가 그 필드를 상태 토큰(UP)으로 resolve 한다. web 어댑터의 HealthcheckController 와 동일 원칙 — 스켈레톤은 RPC/쿼리 0개의 feature 로도 health 표면만으로 부팅한다. 프로덕션 feature 쿼리/뮤테이션을 스켈레톤에 두지 않는다.

기능(feature)은 어떻게 기여하는가 — machinery/feature 분리

스켈레톤은 WorkLog 를 이름으로 알지 못한다. 향후 composition root 가 이 모듈을 classpath 에 명시적으로 채택하고 feature 를 추가하면 Spring for GraphQL 이 다음 두 축으로 합성할 수 있다:

  • 스키마: classpath:graphql/**/*.graphqls 를 전부 병합한다. sample 모듈의 향후 worklog.graphqls 같은 feature 스키마는 스켈레톤의 skeleton.graphqls 와 합쳐진다.
  • resolver(핸들러): 컨텍스트의 모든 @Controller 의 @QueryMapping/@MutationMapping 메서드를 바인딩한다. 향후 feature 의 GraphQL controller 는 스켈레톤을 수정하지 않고 등록할 수 있다.

제공하는 것 · 추가할 한 줄 · env 키

  • 제공: /graphql HTTP endpoint(Spring for GraphQL), 플랫폼 정책(실행 프로파일·비용 한계· DataLoader·에러/보안 경계·관측), 최소 health 스키마. 설정 기본값 config/graphql.yml을 모듈이 직접 읽는다(GraphQlActivationEnvironmentPostProcessor, 우선순위 가장 낮음).

  • 추가할 한 줄(기본 조립에는 없다):

    // app-bootstrap/build.gradle
    runtimeOnly project(':adapter:inbound:graphql')  // GraphQL
    

    이 줄을 지우면 endpoint, 플랫폼 bean, 설정 기본값이 모두 함께 빠진다.

  • 켜기와 끄기: 모듈이 있으면 켜진다. APP_GRAPHQL_ENABLED=false로만 끈다. 끄면 이 모듈의 bean과 Spring GraphQL 자신의 자동 설정(org.springframework.boot.graphql.*)이 함께 빠져 /graphql이 열리지 않는다.

  • 필요한 env 키(docs/registries/env-keys.yaml SSOT): APP_GRAPHQL_DEPLOYMENT_MODE(runtime profile과 맞는 값: local→LOCAL, dev→DEV, prod→PRODUCTION_INTERNAL|PRODUCTION_PUBLIC). production mode는 GraphQlAuthorizationPolicy bean도 필요하다. 나머지 APP_GRAPHQL_*는 기본값으로 동작한다.

sample-portfolio 에 feature GraphQL 스키마/controller 가 있다는 뜻은 아니며, leaf 자체는 최소 health 스키마로 독립 기동할 수 있다.

에러 매핑 — web GlobalExceptionHandler / gRPC 인터셉터의 GraphQL 형제

전역 docs/registries/error-codes.yaml은 shared OperationalError 계약의 SSOT다. GraphQL transport가 직접 만드는 presentation code까지 그 표에 섞지 않는다. 대신 GraphQlErrorCode.platformCodes()가 shipped GraphQL platform code의 유한 catalog를 소유한다. platform mapper는 반드시 platform(...)을 사용하고, application/domain ApiErrorCode만 of(...) 경로로 그대로 통과시킨다. 새 GraphQL-owned code는 GRAPHQL_ prefix를 사용하며, 기존 unprefixed code는 wire compatibility 때문에 동결된 legacy 목록으로 관리한다.

모든 client 에러는 error/GraphQlWireErrorMapper 하나를 거친다(전송 interceptor, 실행 전 instrumentation, data fetcher resolver 세 곳이 같은 bean 을 받는다). 순서:

  1. 플랫폼 거부 — 플랫폼 예외가 error/GraphQlPlatformRejection(wire code·shared Category· 필요하면 wire category/constraint)을 구현한다. instanceof 사슬로 등록하던 두 번째 목록은 없다.
  2. 실패 자신이 ApiErrorCarrier — 그 ApiErrorCode 로 매핑. shared-contract 의 MappingException· AdapterDisabledException·PersistenceFailureException(JPA 예외 포함)·DependencyFailureException, application 의 멱등성·락 예외, DataLoader 키 실패(GraphQlBatchLoadException, 등록된 ApiErrorCode 만 — 소유자 결정 25)가 모두 여기로 온다. 이런 타입을 GraphQlExceptionResolver에 등록해도 쓰이지 않는다.
  3. 등록된 application 매핑(GraphQlExceptionResolver). 앱이 그 실패 타입에 내린 결정이라 원인 사슬의 carrier보다 먼저다. 앱이 등록한 실패가 하위 실패(예: PersistenceFailureException)를 원인으로 들어도 등록한 코드로 답한다. web 에서 앱의 도메인 advice 가 먼저 받는 것과 같다(소유자 결정 2026-11-07, 재리뷰 RR8-01-01).
  4. 원인 사슬의 첫 carrier(ApiErrorCarrier.firstIn, web·gRPC·STOMP와 같은 함수) — 등록되지 않은 예외가 감싼 carrier 를 그 코드로 매핑(재리뷰 RR7-01-05).
  5. IllegalArgumentException과 인자 binder의 BindException → BAD_PARAMETER(REQUEST, BAD_REQUEST) — web·gRPC·STOMP 와 같다. BindException은 @Argument 값이 파라미터 타입으로 바뀌지 않을 때 Spring 이 컨트롤러 전에 던진다(web 의 경로 변수 변환 실패와 같은 답, 소유자 결정 2026-11-07). 변환기가 던진 실패는 binding result 에 남고 원인으로 실리지 않아, 변환기가 carrier 를 던져도 답은 BAD_PARAMETER다(인자 변환 단계는 carrier 를 보지 않는다, 소유자 결정 2026-11-07). 로그도 같은 WARN 한 줄 request refused as BAD_PARAMETER by <예외 타입> (executionId=<id>) 이고, 입력값이 들 수 있는 메시지 (BindException은 rejected value [...])는 남기지 않는다.
  6. 나머지는 INTERNAL_ERROR 로 가려지고 같은 executionId 로 ERROR 로그 한 줄이 남는다.

로그 줄은 어느 단계가 답하든 원인 사슬의 첫 carrier 로 정한다. 등록 매핑이 답한 실패도 그 안의 서버 쪽 carrier (예: DB 연결 실패)는 그 carrier 의 줄(persistence 는 분류만)을 남긴다. 4xx carrier 는 남기지 않는다.

  • client 문구: shared-contract ClientErrorMessages(Category 별 한국어 문구 표 하나, 소유자 결정 11). 예외 메시지는 절대 나가지 않는다.
  • retryable: 코드의 retryable() 이다(category 에서 계산하지 않는다). 플랫폼 자체 코드만 wire category 기본값을 쓴다. 그래서 공유 코드의 값을 바꾸면 이 wire 도 바뀐다: 처리 중 중복 IDEMPOTENT_IN_FLIGHT 는 2026-11-01 리뷰(02-01)부터 retryable: true 다 — 같은 키로 다시 보내면 서버가 판정한다(docs/web/http-contract.md §2). GraphQlWireErrorMapperTest 가 고정한다(재리뷰 RR-02-06).
  • REQUEST_TIMEOUT 은 web 과 이름만 같다. 여기의 category 는 GraphQL wire 전용 6값 어휘(TIMEOUT)이고, web 의 같은 이름 코드는 HTTP 503·operational category TRANSIENT_DEPENDENCY 다 (docs/web/http-contract.md §4). 둘 다 retryable: true 다.
  • body 크기 초과: PAYLOAD_TOO_LARGE(web 과 같은 코드). 문서 모양 거부(GRAPHQL_DOCUMENT_SHAPE_REJECTED)는 별도 코드.

shared Category → GraphQL 렌더링 표(GraphQlWireErrorMapper.RENDERINGS, 하나뿐):

Category wire category GraphQL ErrorType
VALIDATION REQUEST BAD_REQUEST
AUTH AUTHORIZATION UNAUTHORIZED
AUTHZ AUTHORIZATION FORBIDDEN
NOT_FOUND BUSINESS NOT_FOUND
CONFLICT BUSINESS BAD_REQUEST
RATE_LIMIT BUSINESS BAD_REQUEST
TRANSIENT_DEPENDENCY DEPENDENCY INTERNAL_ERROR
PERMANENT_DEPENDENCY INTERNAL INTERNAL_ERROR
DATA_INTEGRITY INTERNAL INTERNAL_ERROR
INTERNAL INTERNAL INTERNAL_ERROR

의존성 버전 — strict locking

gRPC 와 달리 spring-graphql / graphql-java 는 Spring Boot BOM 이 관리한다. 그래서 이 모듈은 버전 명시도, 모듈 스코프 platform import 도 필요 없다 — build.gradle 은 BOM-managed 좌표만 선언하고, per-module gradle.lockfile 이 strict locking 으로 정확한 버전을 고정한다.

설정 — 프레임워크 spring.graphql.* + 플랫폼 app.graphql.*

전송 계층 설정(path, graphiql, introspection, schema location)은 프레임워크 spring.graphql.* 가 소유한다. composition-root application.yml 에서 설정하며 모듈별 yml 은 없다.

플랫폼 정책은 spring.graphql.* 로 표현할 수 없다 — cost/page 한계, preparsed 캐시 경계, 관측 label 로 허용할 operation 이름은 전부 이 leaf 의 결정이다. 그래서 GraphQlPlatformProperties 가 app.graphql prefix 로 @ConfigurationProperties 를 바인딩한다(spring.graphql.platform.* 이 아니다 — 그 prefix 는 존재한 적이 없다).

app:
  graphql:
    deployment-mode: PRODUCTION_INTERNAL
    validation-policy-version: v1          # preparsed 캐시 키의 일부
    console:
      graphiql-enabled: false
      introspection-enabled: false
    limits:
      maximum-page-size: 100
      maximum-complexity: 10000
      preparsed-cache-entries: 1000
      preparsed-cache-weight: 10000000
      preparsed-cache-expire-after-access: 30m
      per-parent-fetch-warning-threshold: 10   # 아래 「N+1」 절
    observed-operation-names: []           # 비우면 모든 operation 이름이 `other` 로 접힌다

이 모듈의 config/graphql.yml이 위 wired 설정을 APP_GRAPHQL_*로 노출한다. APP_GRAPHQL_ENABLED와 APP_GRAPHQL_DEPLOYMENT_MODE 외에도 execution profile, console, page/complexity, preparsed-cache 한계와 관측 operation allowlist가 같은 property tree로 들어간다.

production mode는 env만으로 완성되지 않는다. 애플리케이션 좌표를 스켈레톤이 알 수 없으므로 명시적인 GraphQlAuthorizationPolicy bean이 반드시 필요하며, 이것은 의도된 fail-closed 계약이다. cursor 서명은 설정 키가 없다 — 아래 라이브러리 API로 서비스가 직접 조립한다.

observed-operation-names 가 비어 있는 것이 기본값이자 안전한 값이다. operation 이름은 문법만 검증될 뿐 개수가 제한되지 않으므로, 원본을 그대로 metric label 로 쓰면 정상 클라이언트 하나가 metrics 백엔드를 무너뜨릴 수 있다(observation/GraphQlOperationNameCardinality).

GraphqlHttpBoundaryQualificationTest 는 실제 random-port MVC HTTP 서버 위에서 test-only SecurityFilterChain 과 CORS allowlist 를 조합해 인증, origin, GraphiQL 비활성화, introspection 비활성화, 오류 redaction 을 검증한다. 이 테스트 구성은 production 정책 bean 이 아니다. 실제 composition root 는 이 leaf 를 채택할 때 인증/인가 및 CORS 정책을 함께 제공하고 spring.graphql.graphiql.enabled=false, spring.graphql.schema.introspection.enabled=false 를 운영 설정으로 명시해야 한다.


GraphQL API 실행 플랫폼 — 설계 결정의 근거

위 스켈레톤 머시너리 위에, GraphQL 설계 문서(Stable 48 Task / Advanced 19 Task)의 내용을 이 leaf 의 sub-package 로 구현했다. 아래는 그 과정에서 내린 되돌리기 어려운 결정과 근거다.

설계서의 "모듈"을 Gradle 모듈로 만들지 않은 이유

설계서는 Stable 16 + Advanced 12 = 28개 Gradle 모듈을 전제한다. 구현 시점의 레지스트리 (src/config/architecture/modules.json)는 19개 leaf 였고, 28개를 추가하는 것은 레지스트리· settings.gradle fail-closed 검증·의존 게이트를 동시에 건드리는 변경이다. GraphQL 표면은 하나의 인바운드 전송 경계이므로 그 내부 분할을 레포 전역 SSOT 까지 밀어올리지 않기로 하고, 모듈 = bounded sub-package 로 매핑했다(선례: httpclient leaf 가 366개 java 파일을 같은 방식으로 담는다).

정직하게 기록해 둘 반례: 이후 main 에 통합된 자매 플랫폼 messaging 은 정반대로 24개 leaf 를 레지스트리에 등록했다(현재 총 43개 leaf). 즉 레지스트리는 닫혀 있지 않았고, "확장하면 게이트가 깨진다"는 전제는 과했다. 두 플랫폼이 서로 다른 패턴을 쓰고 있으므로 어느 쪽으로 통일할지는 미결 아키텍처 결정이다.

sub-package 경계를 값으로 선언하던 moduleboundary/ 모델(소스 텍스트 스캐너 포함)은 2026-09-25 에 삭제했다. 두 플랫폼 중 어느 패턴으로 통일할지 정할 때 다시 설계한다.

전송 경계 규칙은 빌드 때 ArchUnit 으로 검사한다

예전에는 architecture/ 가 부팅할 때마다 모든 @Controller 를 리플렉션으로 검사했다. 지금은 GraphQlTransportBoundaryArchitectureTest 가 빌드 때 두 가지를 검사한다: resolver 시그니처(제네릭 인자 포함)에 raw Map·persistence 매핑 타입·domain/driver 타입이 없을 것, raw DataFetcher 구현은 scalar·schema·execution 에만 있을 것. ArchUnit 은 test 의존성이라 production classpath 에는 여전히 JPA/Spring Data 가 없다 — persistence 애노테이션은 단순명으로 매칭한다. 이 leaf 패키지만 검사하므로 adopter 의 컨트롤러는 adopter 가 같은 규칙을 가져가야 한다.

부분 실패는 200, 요청 실패는 4xx

HTTP 응답은 Spring GraphQL handler가 만든다. 검증 통과 후 발생한 필드 에러는 HTTP 200 + partial data 다. GraphQL over HTTP 초안의 status 294 는 쓰지 않는다. 이 leaf 가 따로 두던 HTTP 전송 모델(GraphQlHttpStatusMapper, GraphQlHttpProfile 등)은 요청 경로에 없어서 2026-09-25 에 삭제했다(docs/capability-status.md 제거 표).

목록을 돌려주는 필드는 클라이언트가 어떻게 물어도 원소 수만큼 곱한다

복잡도 점수(cost/GraphQlDocumentComplexityScorer)는 실행 전에 매긴다. 목록 필드의 하위 비용에 곱하는 수는 이렇게 정한다.

필드 곱하는 수
page 필드 — 스키마에 first/last 인자가 있거나 catalog 에 connection=true 로 등록 리터럴 → 요청 변수 → 연산의 변수 기본값 → 스키마 인자 기본값 순서로 찾은 page. 없으면 기본 page 크기(defaultPageSize). 찾은 값은 모두 maximum-page-size 로 검사하고, first·last 를 둘 다 주면 큰 쪽
page 인자가 없는 일반 list catalog 의 GraphQlFieldCostDescriptor.estimatedListSize, 선언이 없으면 기본 page 크기. [[T]] 는 차원마다 한 번
page 필드가 돌려준 connection 객체 바로 안의 list(edges·nodes) 곱하지 않는다. connection 이 이미 page 만큼 곱했다

2026-11-01 리뷰(03-01) 전에는 인자가 값으로 보일 때만 곱했다. items(first: 20) 은 410 점, items 는 40 점, list 4단 중첩은 100 점이었고 query($n: Int = 100000) 은 상한 검사 없이 통과했다. 예산(기본 10,000)과 page 상한(기본 100)이 목록 필드가 생기는 순간 꺼져 있었다.

도입하는 서비스에 미치는 영향. 크기를 선언하지 않은 일반 list 는 이제 원소 20 개로 계산된다. 작은 고정 목록(예: 태그 몇 개)이 예산을 많이 먹으면 GraphQlCostCatalog 빈에 new GraphQlFieldCostDescriptor("Item.tags", base, weight, false, 5) 처럼 추정 크기를 선언한다. 점수가 커지는 쪽으로만 바뀌므로, 이전에 통과하던 깊은 목록 쿼리가 GRAPHQL_COMPLEXITY_EXCEEDED 로 거부될 수 있다.

고른 방법과 버린 대안.

  • 변수 기본값은 연산 문서의 VariableDefinition 기본값을 직접 읽는다. graphql-java 의 ValuesResolver.coerceVariableValues 로 강제 변환한 값을 쓰는 방법은 버렸다. 그 호출은 잘못된 변수에서 예외를 던지므로, 지금 실행 단계가 내는 변수 오류가 비용 단계에서 다른 모양으로 나오게 된다. page 크기에 필요한 것은 Int 하나라서 직접 읽는 쪽이 오류 계약을 건드리지 않는다.
  • 일반 list 의 크기는 스키마 지시어(@listSize 등)가 아니라 기존 cost catalog 에 선언한다. 비용 정책이 이미 catalog 한 곳에 있고, 지시어는 스키마 파일과 SDL 처리 경로를 하나 더 만든다.
  • graphql-java 기본 MaxQueryComplexityInstrumentation 은 쓰지 않는다. 그것도 list 배수를 모르는 필드 개수 합이라 같은 구멍이 남고, 점수가 두 벌이 된다.
  • 점수가 long 을 넘으면 Long.MAX_VALUE 에서 멈춘다(포화 산술). 목록마다 곱하면 적대적인 문서 몇 단으로 long 끝에 닿는데, 그때 ArithmeticException 이 내부 오류로 새지 않고 예산 초과로 거부되게 하기 위해서다.

요청 단위 DB 트랜잭션을 열지 않는다

GraphQL 한 요청은 여러 root field 를 담을 수 있고, 각 root 는 자기 use case 를 호출한다. 요청 전체를 하나의 트랜잭션으로 묶으면 커넥션을 요청 수명만큼 점유하고 부분 실패 의미론이 무너진다. mutation/GraphQlMutationContractValidator.rejectRequestWideTransaction 이 이를 계약으로 강제한다.

커서는 HMAC 서명된 버전 있는 keyset

pagination/HmacGraphQlCursorCodec 은 offset 이 아니라 keyset payload 를 담고, 버전과 서명을 붙인다. 비교는 MessageDigest.isEqual 로 상수 시간이다. 클라이언트가 커서를 조작해 다른 tenant/정렬 축으로 넘어가는 것을 막기 위함이며, 키 회전은 GraphQlCursorKeyRing 이 담당한다.

DataLoader 는 요청 스코프, 캐시 키는 actor·tenant 지문으로 격리

요청 스코프는 Spring 이 준다. runtime/GraphQlBatchLoaderRegistrar.register 는 loader 를 Spring 의 BatchLoaderRegistry 에 등록하고, Spring 은 실행마다 새 DataLoaderRegistry 를 만든다. 그래서 loader 캐시는 그 요청이 끝나면 함께 사라지고, 한 호출자가 받은 행이 다음 호출자에게 가지 않는다 (GraphQlBatchLoaderRegistrationTest.oneRequestsCacheIsNotHandedToTheNext). 전역 캐시는 tenant 간 데이터 누출 경로가 된다. 각 chunk 는 dataloader/GraphQlBatchContext 를 받고, 그 cacheScope() 는 raw tenant id 가 아니라 actor·tenant 의 sha256 지문이다(로그·메트릭에 tenant 원문이 새지 않도록).

요청마다 새로 만든다고 설명하던 GraphQlDataLoaderRequestRegistry 와 GraphQlDataLoaderFactory.newRequestRegistry() 는 어느 요청 경로에도 연결되지 않아 2026-11-02 에 삭제했다(리뷰 03-04).

플랫폼 context 없이 batch 가 불리면(transport interceptor 미배선) GraphQlPlatformContextMissingException 으로 거부한다. wire 는 INTERNAL_ERROR + constraint: PLATFORM_CONTEXT, 로그는 WARN 한 줄이다. instrumentation 이 context 없는 요청을 거부할 때와 같은 constraint 다. 예전에는 REQUEST_TIMEOUT 으로 나가서 조립 오류가 "느리다"로 보였고 클라이언트가 재시도했다(리뷰 03-05).

N+1 — list 부모 아래 자식 필드는 GraphQlBatchLoaderRegistrar.register 로

플랫폼의 batch 보호(chunk 크기, 요청 deadline 으로 줄인 batch 예산, actor·tenant scope)는 GraphQlBatchLoaderRegistrar.register 로 등록한 loader 에만 붙는다. 조립 예시는 복사본을 두지 않고 컴파일·실행되는 테스트 소스를 가리킨다: src/systemTest/java/.../example/OrderCustomerBatchLoading.java. 세 부분이다 — loader 이름의 GraphQlBatchPolicy 를 담은 GraphQlBatchPolicyRegistry bean, 생성자에서 registrar.register(batchLoaders, CUSTOMER_BY_ID, (ids, batch) -> customers.findByIds(ids)) 한 번, 자식 필드 @SchemaMapping 은 environment.getDataLoader(...).load(key) 만 한다. GraphQlPerParentFetchTest 가 이 예시로 부모 8개 → downstream 1번을 확인한다.

같은 일을 하는 다른 길과의 차이:

방법 부모 N개일 때 downstream 호출 chunk·deadline·tenant scope
GraphQlBatchLoaderRegistrar.register batch 당 1번(policy 의 maxBatchSize 로 chunk) 적용
Spring @BatchMapping 1번 미적용 — 크기 상한·deadline·tenant 지문이 없다
부모마다 부르는 일반 @SchemaMapping N번 미적용

adopter 가 잊었을 때를 위해 runtime/GraphQlPerParentFetchInstrumentation 이 실행을 센다. 한 요청에서 같은 필드 좌표가 DataLoader 를 거치지 않고(환경에서 DataLoader·registry 를 꺼내지 않고) resolver 를 app.graphql.limits.per-parent-fetch-warning-threshold(기본 10)번보다 많이 부르면 그 좌표로 WARN 한 줄과 graphql.per.parent.fetch observation(태그 graphql.schema.coordinate) 하나를 남긴다. 거부하지는 않는다 — 부모마다 부르는 resolver 가 싼지는 adopter 만 안다. property 읽기 같은 trivial fetcher 는 세지 않는다. 기본 10 은 기본 page 크기 20 보다 작아서 기본 page 아래의 N+1 은 잡히고, 보통 문서가 alias 로 root 를 몇 번 부르는 정도로는 울리지 않는 값이다. metric 은 애플리케이션의 ObservationRegistry 로 나가며(Actuator 가 있으면 timer 로 집계), 없으면 WARN 만 남는다.

버린 대안: 카탈로그에 등록되지 않은 list 자식 필드를 기동 때 경고 — 모든 list 필드를 adopter 가 카탈로그에 등록해야 의미가 생겨 비용에 비해 효과가 작다. 재검토 조건: sample 에 GraphQL feature 가 들어오면 그 코드가 위 예시를 대신한다.

요청 deadline — 무엇이 끊기고 무엇이 안 끊기나

GraphQlClientPolicy.maxExecutionTime(기본 10초)으로 만든 GraphQlDeadline 하나를 다음이 읽는다.

  • runtime/GraphQlPlatformWebInterceptor: deadline 까지 남은 시간으로 응답에 timer 를 건다. 시간이 지나면 클라이언트는 REQUEST_TIMEOUT(category TIMEOUT)을 받고, Spring 이 실행을 cancel 해서 graphql-java 가 다음 필드를 더 dispatch 하지 않는다.
  • runtime/GraphQlDeadlineInstrumentation: deadline 이 지난 뒤에는 non-trivial resolver 를 부르지 않고 그 필드를 REQUEST_TIMEOUT 으로 실패시킨다.
  • GraphQlCostBudgetHandler: deadline 이 이미 지났으면 실행을 시작하지 않는다.
  • GraphQlBatchExecutor: registrar 로 등록한 batch 예산을 남은 시간으로 줄이고, chunk 사이에서 멈춘다.

한계(테스트로 고정). 이미 돌고 있는 resolver 는 끊지 않는다. 그 스레드는 resolver 가 끝날 때까지 돌고, 그 안의 DB·HTTP 호출은 각 client 의 timeout 이 끊는다 — JPA/Mongo/HTTP client 에 deadline 을 넘겨주는 장치는 없다. 응답이 deadline 에 바로 나가는지는 resolver 가 어느 스레드에서 도는지에 달렸다.

실행 스레드 클라이언트가 응답을 받는 때 테스트
virtual thread 켬(템플릿 기본 SPRING_THREADS_VIRTUAL_ENABLED=true): Spring 이 blocking controller 를 executor 에서 부른다 deadline 근처 GraphQlRequestDeadlineTest
virtual thread 끔: blocking controller 가 요청 스레드에서 돈다 느린 resolver 가 끝난 뒤. 그 아래 필드는 실행되지 않는다 GraphQlRequestDeadlineOnRequestThreadTest

고른 방법과 버린 대안: deadline 은 플랫폼 interceptor 안에서 요청 context 의 GraphQlDeadline 값 그대로 건다. Spring 의 TimeoutWebGraphQlInterceptor 는 GraphQL 본문 없는 HTTP 408 로 끝나 플랫폼 REQUEST_TIMEOUT 코드를 잃고, 자기 duration 을 따로 받아 deadline 과 갈라질 수 있어 쓰지 않았다. resolver 마다 deadline 을 검사하게 하는 방법은 adopter 가 기억해야 하는 숨은 규칙이 되어 버렸다. 예산을 좁히기만 하던 execution/GraphQlTimeoutPolicy 는 main 호출자가 없었고 같은 계산이 GraphQlBatchExecutor.effectiveBudget 에 있어 삭제했다(리뷰 03-02).

관측은 저-카디널리티 강제

observation/GraphQlMetricCardinalityPolicy 는 operation name·필드 좌표처럼 유한 집합만 태그로 허용하고, 변수·인자·actor id 는 GraphQlSensitiveAttributeFilter 가 걸러낸다. GraphQL 은 카디널리티 폭발이 쉬운 전송이라 이 게이트가 없으면 메트릭 백엔드가 먼저 죽는다.

라이브러리 API — 서비스의 어댑터 leaf에서 implementation으로 받아 직접 호출

아래 타입은 auto-configuration 이 빈으로 만들지 않는다. 서비스가 자기 GraphQL 어댑터 leaf 에서 implementation project(':adapter:inbound:graphql') 로 받아 resolver 안에서 직접 생성·호출한다 (AGENTS.md capability 규칙의 라이브러리형 예외). 켜는 설정 키는 없다.

기능 진입점 테스트
Relay connection 조립 pagination/GraphQlConnectionAssembler, GraphQlConnectionPolicy, GraphQlConnectionRequest pagination/GraphQlConnectionAssemblerTest
서명된 keyset cursor pagination/HmacGraphQlCursorCodec + GraphQlCursorKeyRing.of(Map<String, byte[]>) — 키 material 은 서비스가 secret 저장소에서 넣는다 pagination/HmacGraphQlCursorCodecTest
selection set → fetch profile fetch/GraphQlFetchProfileRegistry, GraphQlFetchProfileClassifier fetch/GraphQlFetchProfileRegistryTest, fetch/GraphQlFetchProfileClassifierTest
객체 단위 인가 security/ApplicationObjectAuthorization (GraphQlObjectAuthorizationPort 구현, application-core ObjectAccessPolicy 호출) security/ApplicationObjectAuthorizationTest
mutation 결과 payload mutation/GraphQlMutationResultMapper, GraphQlBusinessResult, GraphQlMutationPayload mutation/GraphQlMutationResultMapperTest

autoconfigure/GraphQlPolicyRequestPathTest 가 auto-configuration 이 cursor codec·key ring 을 만들지 않는다는 사실을 고정한다.

예전 advanced/**(SSE, RSocket, federation, incremental delivery, HTTP GET, persisted operation, subscription replay 등)는 모든 진입점이 바인딩되지 않는 feature flag gate 를 거쳤고 Spring GraphQL/graphql-java SPI 를 구현한 타입이 없어 2026-09-25 에 삭제했다.

아직 구현하지 않은 범위

feature GraphQL schema/resolver 는 여전히 이 leaf 밖이다(스켈레톤은 health 표면만 소유). 실부하 성능 증거와 실 datastore 통합 증거도 없다.