Files
clean-architecture-backend-…/src/adapter/inbound/graphql/AGENTS.md
T
DongHyeonka 01caee3c01
pr / done (pull_request) Canceled after 0s
fix(graphql)!: cursor·connection 거부와 STOMP 오류 frame을 등록된 코드로 답한다
GraphQL cursor·connection 예외는 Javadoc이 「안정 요청 오류 코드」라면서
플랫폼 거부가 아니라 INTERNAL_ERROR와 ERROR 로그가 된다. STOMP ERROR
frame은 code만 싣고, 원인 사슬 어디에 IllegalArgumentException이 있든
BAD_PARAMETER로 본다(다른 전송은 실패 자신만 본다). STOMP broadcast는 모든
인증 세션에 가는데 projector가 무엇을 실어도 되는지 규칙이 없다.
maxInputListElements Javadoc은 실제보다 넓은 상한을 약속한다.

- 두 예외를 GraphQlPlatformRejection으로 만들고 GRAPHQL_CURSOR_REJECTED·
  GRAPHQL_CONNECTION_REJECTED를 catalog에 더한다.
- STOMP 오류 처리기는 MessagingException 포장을 벗긴 실패 자신만 IAE로
  보고, 등록된 코드면 error-category·error-retryable header를 더한다(gRPC
  trailer와 같은 이름·값).
- broadcast 규칙(모든 tenant의 인증 사용자가 읽어도 되는 것만)을
  projector Javadoc·README·AGENTS에 적는다. 버린 안: destination을
  tenant별로 나누기(projector가 tenant를 모르고, simple broker는 R1
  증거라 범위 밖).
- maxInputListElements Javadoc을 실제 검사 범위로 좁힌다.

위험: client가 보는 GraphQL 코드와 STOMP header가 바뀐다.
docs/upgrade/2026-11-round9-authz.md 12~13행.

검증: desktop :adapter:inbound:graphql:check·systemTest,
:adapter:inbound:websocket:check·systemTest rc=0(묶음 전체 실행).

Refs: RR9-02-19, RR9-02-31, RR9-03-14, RR9-03-29
BREAKING CHANGE: GraphQL cursor·connection 거부 코드와 STOMP ERROR frame의
  error-code(묻힌 IAE)·새 header. docs/upgrade/2026-11-round9-authz.md 12~13행.
2026-11-13 12:24:54 +09:00

13 KiB

adapter:inbound:graphql — inbound GraphQL 어댑터(골격 장치)

등록 정보

  • 모듈 ID: adapter-inbound-graphql
  • Gradle 경로: :adapter:inbound:graphql
  • 이 모듈만 시험(Gradle 경로에서 나온 명령): ./gradlew :adapter:inbound:graphql:test --console=plain
  • 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 gradle/libs.versions.toml이 정한다.
  • registry 정본: gradle/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 가 여러 기능 package를 같은 방식으로 담는다). GraphQL 표면은 하나의 인바운드 전송 경계이고, 그 내부 분할을 leaf 정체성 SSOT(gradle/modules.json)까지 밀어올리지 않는다는 선택이다.

이는 레지스트리가 닫혀 있어서가 아니다. modules.json 은 확장 가능하다. 자매 플랫폼 messaging 은 한때 정반대 선택을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 그 플랫폼은 2026-11-08 별도 repo messaging-library로 옮겨 버전으로 받는다(docs/work/reference/related-repos.md). 그래서 이 repo 안에는 비교할 다른 패턴이 없다. GraphQL 내부를 leaf로 나누는 일은 레지스트리에 leaf를 더하는 변경이고, 경계 강제는 지금 아래 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 검사가 이 테스트가 조용히 사라지는 것을 막는다.

책임

  • 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 등 구체 기능을 이름으로 알지 않는다.
  • 있으면 켜진다: 서비스가 src/bootstrap/app/build.gradle에 runtimeOnly project(':adapter:inbound:graphql') 한 줄로 고른다(기본 조립에는 없다). APP_GRAPHQL_ENABLED=false(app.graphql.enabled)만 끄며, 그때 GraphQlActivationEnvironmentPostProcessor가 Spring GraphQL 자동 설정도 exclude 한다. 실제 활성화 시 composition root 는 인증/인가·CORS 정책과 GraphiQL/introspection 운영 설정을 함께 명시해야 한다.

오류 코드 소유

docs/registries/error-codes.yaml은 골격 전체의 OperationalError 정본이다. 전송 계층마다 다른 표현 코드를 모두 받는 registry가 아니다. 그래서 GraphQL은 자기의 유한한 플랫폼 wire 코드 catalog를 GraphQlErrorCode에 둔다.

  • GraphQL 플랫폼 mapper는 GraphQlErrorCode.platform(...)을 써야 한다. 등록되지 않은 플랫폼 코드는 바로 실패한다.
  • application·domain ApiErrorCode 값은 별도 namespace로 남고 GraphQlErrorCode.of(...)로 그대로 지나간다. GraphQL은 제품 오류의 이름을 바꾸면 안 된다. 이 길로 wire에 닿는 것은 등록된 ApiErrorCode뿐이다 — DataLoader의 키별 실패도 그것을 싣고, 자유 문자열을 싣지 않는다(소유자 결정 2026-09-25).
  • GraphQL이 가진 새 플랫폼 코드는 GRAPHQL_ 접두어를 쓴다. 접두어 없는 기존 플랫폼 값은 얼려 둔 옛 wire 계약이고 legacyUnprefixedPlatformCodes()가 하나씩 적는다.
  • 모델만 있는 capability 코드는 그 capability가 출하하는 요청 경로에 닿기 전까지 platformCodes()에 더하지 않는다. 서비스 resolver가 부르는 라이브러리(pagination/의 cursor·connection)의 거부 코드는 더한다. resolver 안에서 던져지면 그 요청의 오류로 wire에 닿기 때문이다.

GraphQlErrorCodeCatalogTest가 출하하는 catalog 전체, 접두어 규칙, application·플랫폼 namespace 분리를 고정한다.

허용

  • :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-restclient·spring-boot-resttestclient(그 테스트가 부르는 TestRestTemplate), spring-boot-starter-graphql-test(GraphQlTester), 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 단일 스택이라 실행 프로파일(execution-profile)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다.

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

금지

  • 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 스키마/컨트롤러/매퍼는 그 기능을 가진 서비스가 소유한다.
  • config/graphql.yml 밖의 설정 파일 — 이 leaf의 설정 기본값은 그 파일 하나다. 의존성에 support가 없어 공용 ModuleDefaultsEnvironmentPostProcessor 대신 GraphQlActivationEnvironmentPostProcessor가 읽는다(manual 10 기준 7 뒤 예외). 전송 설정 spring.graphql.*은 composition-root application.yml에 둔다.

오류 대응 (Category → ErrorType)

모든 client 에러는 error/GraphQlWireErrorMapper 하나를 거친다 — 전송 interceptor, 실행 전 pipeline(instrumentation), data fetcher resolver 세 곳이 같은 bean 을 받는다. 순서는 플랫폼 거부 (예외가 구현한 error/GraphQlPlatformRejection) → 실패 자신이 ApiErrorCarrier면 그 ApiErrorCode → 등록된 application 매핑(GraphQlExceptionResolver) → 원인 사슬의 첫 carrier → IllegalArgumentException·인자 binder의 BindException=BAD_PARAMETER(2026-11-07 소유자 결정). 등록 매핑이 원인 사슬의 carrier보다 먼저라, 앱이 등록한 실패는 하위 실패를 원인으로 들어도 등록한 코드로 답한다. 실패 자신이 carrier인 타입은 등록해도 쓰이지 않는다. 어디에도 안 걸린 예외는 INTERNAL_ERROR 로 가려지고, 같은 executionId 로 ERROR 로그 한 줄이 남는다. client 문구는 shared-contract ClientErrorMessages(Category 별 한국어 표), retryable 은 코드의 값이다. Category → wire category/ErrorType 표는 mapper 의 RENDERINGS 하나뿐이고 README.md에 옮겨 둔다. DataLoader 키 실패는 등록된 ApiErrorCode 만 싣는다(GraphQlBatchLoadException, 2026-09-25 소유자 결정).

향후 adopter 의 feature 기여 방법

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

템플릿에는 feature GraphQL schema/controller/resolver 가 없다. 이 leaf 는 health 스키마만 소유한다.

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

표와 자세한 계약은 README.md 「구현된 플랫폼 범위 — 등급으로 말한다」 절이다. 지킬 것:

  • capability마다 그 표의 등급을 쓰고, 현재 등급보다 높게 표현하지 않는다(README·문서·커밋 본문 모두).

테스트

./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          # 실제 HTTP 서버
./gradlew :adapter:inbound:graphql:graphqlDocumentContractTest --console=plain   # env-keys registry 대조

graphqlDocumentContractTest 는 document-contract 태그 시험(GraphQlDeploymentModeRegistryParityTest)만 돌린다. 저장소 문서를 읽으므로 test 에서는 돌지 않고 main 단계(leaf mainCheck)에서 돈다. 저장소 루트 (ca.repository.root)는 이 lane 만 받는다.

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 안에서 쓴다.