Files
clean-architecture-backend-…/src/adapter/inbound/graphql/README.md
T
DongHyeonka 6e992970ca fix!: r9 확인 리뷰가 찾은 결함 25건을 고친다
문제: r9 커밋(45d2a478)을 영역 4개로 다시 리뷰해 결함 25건을 찾았다
(Important 2, Minor 23, round6/01~04). Important 둘: r9가 @Configuration을
사용자 전송에서 통째로 빼서 설정 안의 RouterFunction·DataFetcher가
@SystemCaller를 불러도 잡히지 않는 회귀, 그리고 가이드대로 만든
CREATE INDEX CONCURRENTLY 마이그레이션이 Flyway 기본 트랜잭션 잠금과 서로
기다려 끝나지 않는 것(이전부터). 그 밖에 시작을 거절당한 같은 attempt가
기록 만료까지 503을 받는 것, gRPC 취소 판정과 raw status 설명의 로그 유출,
STOMP의 IAE ERROR 기록, 아무것도 잡지 못하던 shared-contract 패키지 규칙,
workflow 판독기의 거짓 통과 모양(-v·조건부 exit·Windows 기본 셸·요청형
trigger 등).

방법: 영역별 4묶음이 실패 테스트를 먼저 확인하고 고쳤다(재리뷰 README 17절).
- 설정과 그 중첩 클래스는 요청 처리기 타입에 의존하면 사용자 전송으로 센다.
- Flyway PostgreSQL 잠금을 세션 수준으로(transactional-lock=false), 직접
  만드는 Flyway는 FlywaySchemaPolicy 하나로. 버린 대안: CIC를 마이그레이션에서
  금지하고 운영 절차로.
- 같은 attempt로 다시 claim하면 lease가 지난 claim을 넘겨받는다. 옛 revision의
  늦은 시작이 ALREADY를 받아 이중 실행되던 것도 막았다.
- 네 전송이 IAE를 ServerFailureLog의 같은 WARN 한 줄로 남긴다.
- workflow 판독기가 세지 않는 이유를 셋으로 나누고 문서 5곳을 같은 말로.

위험·한계: Flyway 세션 잠금은 transaction-mode PgBouncer 뒤에서 깨진다
(Hikari 직접 연결 전제, 가이드에 적음). 배포 마이그레이션 도구도 같은 값을
써야 한다(업그레이드 안내). 같은 attempt를 두 호출이 동시에 쓰는 것은
저장소가 가려내지 않는다(호출자 계약으로 문서화).

검증: 묶음별 RED·GREEN은 로컬(노트북 빌드 금지 지시 전)에서, 지시 뒤에
바뀐 01 A5 fixture의 RED와 02 늦은 시작 revision 검사의 RED, 03 동시 인덱스
검사기 GREEN은 desktop에서 확인했다. 합친 트리를 desktop에서 돌려 모두 첫
실행 통과: :ci :verifyDependencyLocks --warning-mode=fail, sample check,
두 빌드 verifyStrictLaneStages --dry-run, :mainCheck, :integrationCheck,
-p optional-platforms ci integrationCheck performanceCheck, :performanceCheck,
:releaseCheck, compose 18 lane, -p build-logic check javadoc(README 17.2절).

Refs: docs/reviews/2026-11-03-rereview/README.md 17절
BREAKING CHANGE: Flyway PostgreSQL 잠금이 세션 수준이 되어 배포 도구에도
flyway.postgresql.transactional.lock=false가 필요하다. GraphQL·gRPC가 IAE를
WARN 한 줄로 남긴다. shared-contract 패키지 규칙이 실제로 검사한다.
2026-11-05 21:26:50 +09:00

25 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)가 모두 여기로 온다.
  3. 등록된 application 매핑(GraphQlExceptionResolver).
  4. IllegalArgumentException → BAD_PARAMETER(REQUEST, BAD_REQUEST) — web·gRPC·STOMP 와 같다. 로그도 같은 WARN 한 줄 request refused as BAD_PARAMETER by <예외 타입> (executionId=<id>) 이고, 입력값이 들 수 있는 메시지는 남기지 않는다.
  5. 나머지는 INTERNAL_ERROR 로 가려지고 같은 executionId 로 ERROR 로그 한 줄이 남는다.
  • 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 통합 증거도 없다.