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>
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()를 GraphQLErrorType으로 매핑한다(아래 표). 정확한code/category는 errorextensions{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 제품 표면을 채택할 때 별도 설계·테스트와 함께 추가해야 한다.