Files
clean-architecture-backend-…/src/adapter/inbound/graphql/CLAUDE.md
T
donghyeon-kaandClaude Opus 5.5 25de288ab4 review-followup Wave 3 라운드 2(P25): core 죽은 표면·web·GraphQL·WebSocket·sample 구조, 소유자 결정 32 기록
- 삭제: core 죽은 계약 타입·opstore·rate-limit disabled·GraphQL 병렬 HTTP envelope·sample legacy 포스터 업로드 모드
- durable operation이 `CommandUseCase` 구현, 알림 템플릿 버전·locale 기본값을 설정으로(`APP_NOTIFICATION_PLATFORM_DEFAULT_LOCALE`=ko-KR),
  `GraphQlPlatformAutoConfiguration` 기능별 분해, STOMP broker executor, startup 예외 하나, profile reader ArchUnit 확대
- web 보안 root 분리, sample scan을 sample 패키지로(NEW-10d·S6-#8 — 새 web controller가 sample에 등록되지 않음)
- sample 정렬 이름·요청 파싱 helper·게시 파라미터 record·reconcile은 명시 명령(P14-new-3)
- 통합: P24와 겹친 sample 포스터 설정은 P24 쪽(`PosterImageApiSettings` DISABLED/PUBLICATION 검증) 유지
- 현황표: 소유자 결정 32(fileserver 권한 추가), S1-#6b·S1-#18b·S6-#10a를 P28로

검증: ./gradlew check architectureCheck verifyDependencyLocks verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys
:sample-portfolio:integrationTest :sample-portfolio:systemTest :app-bootstrap:integrationTest --continue 통과(657 task)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-28 17:33:10 +09:00

15 KiB

adapter:inbound:graphql — inbound GraphQL adapter (skeleton machinery)

Registered identity

  • Module ID: adapter-inbound-graphql
  • Gradle path: :adapter:inbound:graphql
  • Focused test (derived from Gradle path): ./gradlew :adapter:inbound:graphql:test --console=plain
  • Runtime baseline: Java 21; repository framework baseline: Spring Boot 4.0.0.
  • Registry SSOT: src/config/architecture/modules.json.

Package root: dev.caskeleton.adapter.inbound.graphql.

코드 주석에서 덜어낸 설계 결정의 근거는 README.md 가 모아둔다 (이 문서는 모듈 규칙 SSOT).

플랫폼 모듈 = sub-package (Gradle 모듈 아님)

GraphQL 플랫폼 설계서는 Stable 16개 + Advanced 12개 "모듈"을 말하지만, 이 구현은 그 28개를 이 leaf 안의 bounded sub-package 로 매핑한다(선례: httpclient leaf 가 366개 java 파일을 같은 방식으로 담는다). GraphQL 표면은 하나의 인바운드 전송 경계이고, 그 내부 분할을 leaf 정체성 SSOT(src/config/architecture/modules.json)까지 밀어올리지 않는다는 선택이다.

이는 레지스트리가 닫혀 있어서가 아니다. modules.json 은 확장 가능하며, 실제로 자매 플랫폼인 messaging 은 정반대 선택을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 개수는 modules.json 이 소유하며 여기서 되풀이하지 않는다 — 산문에 적힌 숫자는 leaf 가 하나 추가되는 순간 낡는다. 즉 이 레포에는 두 패턴이 공존한다:

방식 경계 강제
messaging 레지스트리에 leaf 등록 Gradle 의존 게이트
graphql 단일 leaf 내 sub-package 아래 ArchUnit 테스트 (전송 경계만)

어느 쪽으로 통일할지는 미결 아키텍처 결정이다.

sub-package 사이의 경계(Stable↔Advanced 방향, 모듈 레코드)를 값으로 선언하던 moduleboundary/ 모델과 부팅 때마다 컨트롤러를 리플렉션으로 검사하던 architecture/ 는 2026-09-25 에 삭제했다 (docs/capability-status.md 제거 표). 지금 기계가 지키는 것은 전송 경계 두 가지뿐이다 — GraphQlTransportBoundaryArchitectureTest(ArchUnit, 이 leaf 패키지 대상):

  • resolver(@SchemaMapping 계열·@BatchMapping) 시그니처는 전송 타입만 쓴다. 반환·인자 타입과 그 제네릭 인자에 raw Map, persistence 매핑 타입(@Entity/@Document/@Table 등, 단순명 매칭), domain·outbound adapter·JPA/Hibernate/Spring Data/JDBC/Mongo/AWS/gRPC/Kafka 타입이 오면 실패한다.
  • raw DataFetcher 구현은 scalar·schema·execution 패키지에만 둔다.

두 규칙 모두 위반 fixture 로 실제로 잡히는지 같은 테스트가 확인한다. graphqlStableTest 의 required-class 검사가 이 테스트가 조용히 사라지는 것을 막는다.

Responsibility

  • GraphQL 전송 인프라만: 최소 health 스키마(skeleton.graphqls) + HealthGraphqlController, 프로토콜 에러 매핑(error/GraphQlWireErrorMapper). Spring for GraphQL 이 스키마와 컨트롤러를 자동 합성/바인딩하도록 얹는 얇은 계층이다.
  • 그 위에 GraphQL API 실행 플랫폼(...graphql 하위 sub-package 군)이 스키마 계약·전송 프로파일·실행 정책·비용 한계·DataLoader·페이지네이션·에러/보안 경계·관측을 소유한다. 플랫폼은 여전히 feature-agnostic 이며 정책·계약·검증 기계만 제공한다.
  • feature-agnostic: classpath:graphql/** 스키마와 모든 @Controller @QueryMapping/ @MutationMapping 을 generic 하게 합성한다. WorkLog 등 구체 기능을 이름으로 알지 않는다.
  • 있으면 켜진다: 서비스가 app-bootstrap/build.gradle에 runtimeOnly project(':adapter:inbound:graphql') 한 줄로 고른다(기본 조립에는 없다). APP_GRAPHQL_ENABLED=false(backend.graphql.enabled)만 끄며, 그때 GraphQlActivationEnvironmentPostProcessor가 Spring GraphQL 자동 설정도 exclude 한다. 실제 활성화 시 composition root 는 인증/인가·CORS 정책과 GraphiQL/introspection 운영 설정을 함께 명시해야 한다.

Error-code ownership

docs/registries/error-codes.yaml is the skeleton-wide OperationalError SSOT; it is not a catch-all registry for transport-specific presentation codes. GraphQL therefore keeps its own finite platform wire-code catalogue in GraphQlErrorCode.

  • GraphQL platform mappers must use GraphQlErrorCode.platform(...). An unregistered platform code fails immediately.
  • application/domain ApiErrorCode values remain a separate namespace and pass through with GraphQlErrorCode.of(...); GraphQL must not rename product errors. Only a registered ApiErrorCode reaches the wire this way — a DataLoader per-key failure carries one, never a free string (owner decision 25).
  • new GraphQL-owned platform codes use the GRAPHQL_ prefix. The existing unprefixed platform values are frozen legacy wire contracts and are listed explicitly by legacyUnprefixedPlatformCodes().
  • modelled-only capability codes are not added to platformCodes() until that capability reaches the shipped request path.

GraphQlErrorCodeCatalogTest pins the exact shipped catalogue, the prefix rule and the application/platform namespace split.

Allowed

  • :application-core, :domain-core, :shared-contract. :application-core 는 선언만이 아니라 실제 의존이다 — object 인가의 답하는 계약(dev.caskeleton.application.security.ObjectAccessPolicy)이 거기 살기 때문이다. 이 leaf 가 그 계약을 소유했다면 application 구현체가 인바운드 전송을 컴파일 의존해야 했고, 그건 의존 방향이 뒤집힌다.
  • spring-boot-starter-graphql (Spring Boot BOM 관리 — 버전 명시 없음).
  • test scope 에 한해 spring-boot-starter-web(random-port 전송 테스트용), spring-boot-starter-security(HTTP 인증/CORS qualification 용), io.micrometer:micrometer-core(실제 MeterRegistry 로 metric label cardinality 를 측정).
  • java-test-fixtures — 계약 스위트·통합 fixture·in-memory 스텁은 src/testFixtures/java 가 소유하고 production jar 에 들어가지 않는다.
  • test scope 에 한해 archunit-junit5 — 전송 경계 규칙(GraphQlTransportBoundaryArchitectureTest).

서버는 이 leaf 가 고르지 않는다. production 파일 중 org.springframework.web· org.springframework.http 을 import 하는 것은 하나도 없다(servlet API 는 body 상한 필터만 compileOnly 로 쓴다). 서버 선택은 composition root 의 결정이고, gradle.lockfile 이 이를 고정한다(spring-boot-starter-web·spring-webmvc·spring-webflux·tomcat-embed-* 전부 testCompileClasspath,testRuntimeClasspath 만). 템플릿은 servlet 단일 스택(D4)이라 실행 프로파일(execution-profile)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다.

  • annotationProcessor 로 spring-boot-configuration-processor — GraphQlPlatformProperties 가 @ConfigurationProperties 이므로 ca.spring-config convention plugin이 주는 패리티 게이트가 이 선언을 요구한다.

Forbidden

  • outbound 어댑터(:adapter:outbound:*)에 대한 직접 의존 — 인바운드는 application 아웃바운드 포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS, 일반 ..adapter.inbound.. 규칙이 이 모듈을 자동 커버 — per-module 규칙 추가 불필요).
  • 프로덕션 feature 쿼리/뮤테이션을 스켈레톤에 두는 것 — health 표면만 (web 의 HealthcheckController 와 동일 원칙). feature 스키마/컨트롤러/매퍼는 sample 모듈이 소유한다.
  • 모듈별 yml — 설정은 프레임워크 spring.graphql.* 로 composition-root application.yml 에 산다.

Error mapping (Category → ErrorType)

모든 client 에러는 error/GraphQlWireErrorMapper 하나를 거친다 — 전송 interceptor, 실행 전 pipeline(instrumentation), data fetcher resolver 세 곳이 같은 bean 을 받는다. 순서는 플랫폼 거부 (예외가 구현한 error/GraphQlPlatformRejection) → ApiErrorCarrier(자기 ApiErrorCode) → 등록된 application 매핑(GraphQlExceptionResolver) → IllegalArgumentException=BAD_PARAMETER. 어디에도 안 걸린 예외는 INTERNAL_ERROR 로 가려지고, 같은 executionId 로 ERROR 로그 한 줄이 남는다. client 문구는 shared-contract ClientErrorMessages(Category 별 한국어 표), retryable 은 코드의 값이다. Category → wire category/ErrorType 표는 mapper 의 RENDERINGS 하나뿐이고 README.md에 옮겨 둔다. DataLoader 키 실패는 등록된 ApiErrorCode 만 싣는다(GraphQlBatchLoadException, 소유자 결정 25).

향후 adopter 의 feature 기여 방법

  • 스키마: adopter feature 가 src/main/resources/graphql/*.graphqls 를 두면 classpath:graphql/** 병합으로 합칠 수 있다.
  • 핸들러: adopter 가 @Controller + @QueryMapping/@MutationMapping 빈을 등록하면 자동 바인딩된다.
  • 도메인 예외 매핑: adopter 는 자신의 DataFetcherExceptionResolver 를 추가하거나 ApiErrorCarrier 를 사용해 안정적 코드로 매핑할 수 있다.

현재 sample 에 feature GraphQL schema/controller/resolver 가 있다고 가정하지 않는다. 이 leaf 는 health 스키마만 소유한다.

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

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

Test

cd src
./gradlew :adapter:inbound:graphql:test --console=plain
./gradlew :adapter:inbound:graphql:graphqlTransportQualificationTest --console=plain

테스트 레인:

./gradlew :adapter:inbound:graphql:graphqlStableTest --console=plain   # GraphQlTransportBoundaryArchitectureTest만, skip 금지
./gradlew :adapter:inbound:graphql:systemTest --console=plain          #  23 tests (실제 HTTP 서버)

graphqlStableTest 는 GraphQlTransportBoundaryArchitectureTest 가 실행되지 않거나 skip 되면 실패한다(build.gradle 의 strict lane requires + rejectSkipped). 같은 클래스는 test 에서도 돈다.

아티팩트 게이트

./gradlew :adapter:inbound:graphql:test --tests '*GraphQlProductionClassesTest' --console=plain
./gradlew :adapter:inbound:graphql:verifyGraphQlApiSurface --console=plain
  • GraphQlProductionClassesTest — production 클래스에 testkit/InMemory/ForTests/Fixture/ TestContext 가 하나라도 있으면 실패한다(test 의 일부). 테스트용 request context 헬퍼(testkit/GraphQlRequestContexts)는 src/testFixtures/java 가 소유한다.

  • verifyGraphQlApiSurface — docs/architecture/graphql-api-surface.txt 스냅샷과 실제 public 타입 목록이 다르면 실패한다. 단일 jar 안에서 public 은 모든 adopter 에게 public 이므로, 표면 증가는 리뷰 결정이지 빌드 부산물이 아니다. 승인 후: ./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange.

  • mutation 멱등성 — 저장소에 연결된 적 없는 GraphQlMutationIdempotencyInterceptor·context· fingerprint 와 idempotencyKey extension 허용을 2026-09-25 에 삭제했다. Stable 기본 GraphQlExtensionsPolicy 는 어떤 extension key 도 허용하지 않는다. 요청 재생 멱등성이 필요하면 application IdempotencyExecutor 를 use case 안에서 쓴다.