Files
clean-architecture-backend-…/src/adapter/inbound/graphql
DongHyeonkaandClaude Opus 5 5f10b791d3 chore: record pre-existing uncommitted repository state
Snapshot of the in-flight state that already existed, identically, in both
this worktree and the main checkout before this session began: the initial
HTTP Client platform implementation (previously untracked), the redis-lab
removal, and the JPA / object-storage / notification integration work.

Kept separate from this session's HTTP Client review response, which lands
in the following commit, so the two bodies of work stay reviewable apart.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-11 16:48:43 +09:00
..

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 는 스켈레톤을 수정하지 않고 등록할 수 있다.

현재 app-bootstrap 과 sample-portfolio 의 production runtime 은 이 leaf 를 의존하지 않는다. 즉 이 모듈은 classpath opt-in 이며, 현재 sample 에 feature GraphQL 스키마/controller 가 있다는 뜻이 아니다. leaf 자체는 최소 health 스키마로 독립 기동할 수 있다.

에러 매핑 — web GlobalExceptionHandler / gRPC 인터셉터의 GraphQL 형제

GraphqlExceptionResolver 는 DataFetcherExceptionResolverAdapter 를 확장해, 데이터 페처가 동기적으로 던진 예외 중 안정적 ApiErrorCode 를 실은 것(전송-중립 hook ApiErrorCarrier 구현)을 GraphQLError 로 변환한다. 데이터 페처는 web 컨트롤러처럼 "그냥 던지기만" 하고, 이 resolver 가 와이어 계약을 단일 소유한다.

  • ErrorType 분류: errorCode().category() 를 GraphQL ErrorType 으로 매핑한다(아래 표). 정확한 code/category 는 error extensions{code, category} 로 실어 클라이언트가 switch 하게 한다(gRPC 가 status trailer 에 싣는 것과 동형).
  • ApiErrorCode 추출: shared-contract 의 PersistenceFailureException / DependencyFailureException(outbound 어댑터에서 올라온 분류된 실패)과 feature 예외(자신의 도메인 ApiErrorCode 를 실은 것)를 단일 instanceof ApiErrorCarrier 분기로 인식한다.
  • leak 방지: 인식된 코드는 안정적 code 문자열만 error message/extensions 로 노출하고, raw 예외 메시지(SQLState/업스트림 세부를 담을 수 있음)는 절대 클라이언트에 내보내지 않는다.
  • 비-ApiErrorCarrier 예외는 null 을 반환해 다른 DataFetcherExceptionResolver 빈(예: sample 의 도메인 예외 resolver)과 Spring 기본 처리로 넘긴다.

Category → ErrorType 표(설계 스펙 Error Mapping SSOT):

Category GraphQL ErrorType
VALIDATION BAD_REQUEST
AUTH UNAUTHORIZED
AUTHZ FORBIDDEN
NOT_FOUND NOT_FOUND
CONFLICT BAD_REQUEST
RATE_LIMIT BAD_REQUEST
TRANSIENT_DEPENDENCY INTERNAL_ERROR
PERMANENT_DEPENDENCY INTERNAL_ERROR
DATA_INTEGRITY INTERNAL_ERROR
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.*

이 모듈은 자체 @ConfigurationProperties 를 두지 않는다. path, graphiql, introspection, schema location 은 프레임워크 spring.graphql.* 로 composition-root application.yml 에서 설정한다 (모듈별 yml 없음). 정말 필요한 knob 이 생기기 전까지 커스텀 설정 클래스는 두지 않는다.

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 를 운영 설정으로 명시해야 한다.

아직 구현하지 않은 P2 범위

이 leaf 와 현재 sample 에는 feature GraphQL schema/resolver, query depth/cost 제한, persisted operation, DataLoader/batching, subscription 이 구현되어 있지 않다. 이 항목들은 실제 GraphQL 제품 표면을 채택할 때 별도 설계·테스트와 함께 추가해야 한다.