- 결정 16: `ca-skeleton.*`·`backend.graphql` 등 → `app.*`(APP_* env 키 이름 유지), selector 키 상수 하나(`CapabilitySelectors`), 바인딩만 되던 `streaming-idle` 삭제 - `StrictSettingsBinder`가 env 오타까지 거부 — 모든 capability(graphql·websocket·mongo는 edge 제약으로 파일만 strict), httpclient 리플렉션 `HttpClientEnvironmentKeys` 삭제 - persistence-jpa가 `APP_DATASOURCE_PASSWORD` secret 요구를 기여(bootstrap이 JPA 스위치를 읽지 않음), Redis ACL fixture에서 pub/sub 권한 제거 - 결함 수정: SMTP 설정 env 이름 충돌(P20-new-1), `bindExcept`가 system env까지 filter(P20-new-2), graphql 빈 deployment-mode 메시지(P20-new-6) - 통합: P30과 충돌 11건(P30의 명시적 bean 구조 유지), P30 코드의 옛 키를 app.*로, persistence-jpa 포맷 - 현황표: 소유자 결정 36(persistence-jpa 설정은 플랫폼 키만 app.persistence-jpa.*로, 공유 기능 트리 예외), 재개 문서에 일시 정지 상태 Wave 3 종료 검증: check · ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck · architectureCheck verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest · integrationCheck · -p build-logic test · -p optional-platforms ci · :app-bootstrap:qualificationBootJar releaseCheck 통과 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
15 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 키
-
제공:
/graphqlHTTP 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.yamlSSOT):APP_GRAPHQL_DEPLOYMENT_MODE(runtime profile과 맞는 값: local→LOCAL, dev→DEV, prod→PRODUCTION_INTERNAL|PRODUCTION_PUBLIC). production mode는GraphQlAuthorizationPolicybean도 필요하다. 나머지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 을 받는다). 순서:
- 플랫폼 거부 — 플랫폼 예외가
error/GraphQlPlatformRejection(wire code·sharedCategory· 필요하면 wire category/constraint)을 구현한다.instanceof사슬로 등록하던 두 번째 목록은 없다. ApiErrorCarrier— 자기ApiErrorCode로 매핑. shared-contract 의MappingException·AdapterDisabledException·PersistenceFailureException(JPA 예외 포함)·DependencyFailureException, application 의 멱등성 예외, DataLoader 키 실패(GraphQlBatchLoadException, 등록된ApiErrorCode만 — 소유자 결정 25)가 모두 여기로 온다.- 등록된 application 매핑(
GraphQlExceptionResolver). IllegalArgumentException→BAD_PARAMETER(REQUEST,BAD_REQUEST) — web·gRPC·STOMP 와 같다.- 나머지는
INTERNAL_ERROR로 가려지고 같은 executionId 로 ERROR 로그 한 줄이 남는다.
- client 문구: shared-contract
ClientErrorMessages(Category 별 한국어 문구 표 하나, 소유자 결정 11). 예외 메시지는 절대 나가지 않는다. - retryable: 코드의
retryable()이다(category 에서 계산하지 않는다). 플랫폼 자체 코드만 wire category 기본값을 쓴다. - 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
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 제거 표).
요청 단위 DB 트랜잭션을 열지 않는다
GraphQL 한 요청은 여러 root field 를 담을 수 있고, 각 root 는 자기 use case 를 호출한다.
요청 전체를 하나의 트랜잭션으로 묶으면 커넥션을 요청 수명만큼 점유하고 부분 실패 의미론이
무너진다. mutation/GraphQlMutationContractValidator.rejectRequestWideTransaction 이 이를
계약으로 강제한다.
커서는 HMAC 서명된 버전 있는 keyset
pagination/HmacGraphQlCursorCodec 은 offset 이 아니라 keyset payload 를 담고, 버전과 서명을
붙인다. 비교는 MessageDigest.isEqual 로 상수 시간이다. 클라이언트가 커서를 조작해 다른
tenant/정렬 축으로 넘어가는 것을 막기 위함이며, 키 회전은 GraphQlCursorKeyRing 이 담당한다.
DataLoader 는 요청 스코프, 캐시 키는 actor·tenant 지문으로 격리
dataloader/GraphQlDataLoaderRequestRegistry 는 요청마다 새 인스턴스를 만든다. 전역 캐시는
tenant 간 데이터 누출 경로가 된다. security/GraphQlBatchContext.cacheScope() 는 raw tenant id 가
아니라 sha256 지문을 캐시 스코프에 쓴다(로그·메트릭에 tenant 원문이 새지 않도록).
관측은 저-카디널리티 강제
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 통합 증거도 없다.