Files
clean-architecture-backend-…/src/adapter/inbound/graphql/README.md
T
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.

고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
  :composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
  이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
  boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
  project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
  gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
  config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
  (getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
  훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
  rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
  src/를 붙인다. notification API surface의 application-notification 소스
  루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
  건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
  폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
  registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
  써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
  env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
  verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
  check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
  operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
  다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
  capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
  docs/upgrade/2026-11-relayout.md를 더한다.

위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.

검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.

BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
2026-11-11 22:15:42 +09:00

31 KiB

adapter-graphql — 설계 결정 참조

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

허용/금지 의존, 모듈 규칙, 설정 knob, 테스트 명령 같은 모듈 규칙은 AGENTS.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 를 전부 병합한다. 서비스가 더하는 order.graphqls 같은 feature 스키마는 스켈레톤의 skeleton.graphqls 와 합쳐진다.
  • resolver(핸들러): 컨텍스트의 모든 @Controller 의 @QueryMapping/@MutationMapping 메서드를 바인딩한다. 향후 feature 의 GraphQL controller 는 스켈레톤을 수정하지 않고 등록할 수 있다.

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

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

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

    // src/bootstrap/app/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_*는 기본값으로 동작한다.

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

정직하게 기록해 둘 반례: 이후 main 에 통합된 자매 플랫폼 messaging 은 정반대로 자기 leaf 를 레지스트리에 하나씩 등록했다(지금의 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 가 카탈로그에 등록해야 의미가 생겨 비용에 비해 효과가 작다. 재검토 조건: 템플릿에 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 안에서 직접 생성·호출한다 (docs/manual/10-capabilities.md 「판단」의 라이브러리형 예외). 켜는 설정 키는 없다.

기능 진입점 테스트
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 통합 증거도 없다.

지역 규칙에서 옮긴 표와 계약

이 절의 표와 계약은 지역 규칙 AGENTS.md에 있던 것을 2026-11-07에 옮겼다(지역 규칙은 200줄 이하). 규칙이 바뀌면 이 절과 AGENTS.md를 같은 변경에서 고친다.

구현된 플랫폼 범위 — 등급으로 말한다

"구현됐다" 는 네 가지 서로 다른 사실을 한 단어로 덮는다. 그래서 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 를 구현하는 형태로 새로 만든다.