문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가 Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다. @SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히 prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고, GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로 나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역 발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다. 방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를 먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이 기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록, @SystemInvoked bean은 기동 실패, complete 단계 실패는 IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도 SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도 행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도 내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제 지표(redis.lane.*) 기준으로 고쳤다. 위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이 브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류 디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어 파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은 기동을 막는다. httpclient failure-injection lane의 main 단계 중복 실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다. 검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci integrationCheck performanceCheck, :performanceCheck, :releaseCheck (-PgitRevision), verify-compose-profile-contracts(18 lane) 통과. 첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다. Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절 BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호 첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드 IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은 static·의존 없음이어야 한다.
355 lines
25 KiB
Markdown
355 lines
25 KiB
Markdown
# adapter-graphql — 설계 결정 참조
|
|
|
|
인바운드 GraphQL 어댑터 **스켈레톤 머시너리** 모듈. 패키지 루트:
|
|
`dev.caskeleton.adapter.inbound.graphql`.
|
|
|
|
허용/금지 의존, 모듈 규칙, 설정 knob, 테스트 명령 같은 **모듈 규칙**은
|
|
[CLAUDE.md](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`, 우선순위 가장 낮음).
|
|
- 추가할 한 줄(기본 조립에는 없다):
|
|
|
|
```groovy
|
|
// 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 와 같다.
|
|
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 는 존재한 적이 없다).
|
|
|
|
```yaml
|
|
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`](src/systemTest/java/dev/caskeleton/adapter/inbound/graphql/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 통합 증거도 없다.
|