Files
clean-architecture-backend-…/docs/architecture/graphql-api-surface.txt
T
DongHyeonka e69c321eca fix(graphql)!: GraphQL 지표에 플랫폼 tag를 붙이고 key 묶음을 고정한다
GraphQlResolverObservationConvention·GraphQlDataLoaderObservationConvention
bean이 있지만 Spring for GraphQL observation에 붙지 않는다. 그래서
graphql.datafetcher·graphql.dataloader timer는 Spring 기본 tag
(graphql.field.name, graphql.loader.name, graphql.error.type)를 달고,
플랫폼이 정한 schema 좌표·resolver 무게·batch 크기 tag는 아무 지표에도
없다. 두 convention의 tag 이름도 뜻과 맞지 않는다: 무게를
graphql.operation.type으로, batch 크기를 graphql.complexity.bucket으로
단다. graphql.request는 오류가 없거나 복잡도를 세기 전에 끝난 요청에서
error.type·graphql.complexity.bucket을 빼는데, Prometheus registry는
이름이 같고 key 묶음이 다른 meter를 버린다. 먼저 등록된 쪽만 남고
성공이나 실패 한쪽이 /actuator/prometheus에서 사라진다.

Spring의 DataFetcherObservationConvention·DataLoaderObservationConvention을
구현한 adapter 둘(runtime 패키지)을 두고 GraphQlObservationConfiguration이
@ConditionalOnMissingBean으로 등록한다. resolver는 부모 타입과 field
이름으로 schema 좌표(Type.field)를 만들고, 좌표로 이름 붙일 수 없는
field(_Service.sdl 같은 federation field)는 unnamed와 기본 무게로 같은
key를 단다. DataLoader는 등록한 loader 이름, 또는 Spring이
@BatchMapping loader에 붙이는 schema 좌표(Book.author)를 이름으로 쓰고,
둘 다 아니면 unknown이다. graphql.request는 오류가 없으면
error.type=NONE, 복잡도를 세지 않았으면 graphql.complexity.bucket=unknown을
단다. tag 이름을 graphql.resolver.weight·graphql.batch.size.bucket으로
고치고 cardinality 허용 목록, metrics.yaml 세 행(Micrometer가 다는 error
tag 포함), 공개 API 스냅숏을 맞춘다. 응답 path와 batch key는 싣지 않는다.

버린 안: Spring 기본 convention을 두고 registry만 그 tag로 적기. 플랫폼
convention이 죽은 코드로 남고, field 이름만으로는 타입이 다른 같은 이름
field를 가를 수 없다. 기본 convention을 감싸 tag만 더하는 안은
graphql.error.type이 Micrometer의 error tag와 같은 값을 한 번 더 싣는다.

위험: 세 timer의 tag가 바뀐다. 옛 tag로 거른 대시보드·경보는 비고,
docs/upgrade/2026-11-round9-followups.md 1~4행이 옮기는 법을 적는다.
클래스 이름으로 등록한 loader는 unknown 하나로 묶인다. 자기
DataFetcherObservationConvention·DataLoaderObservationConvention bean을
둔 서비스는 그 bean이 그대로 쓰인다.

검증: desktop :adapter:inbound:graphql:check :adapter:inbound:graphql:systemTest
:adapter:inbound:graphql:verifyGraphQlApiSurface, scripts/verify.sh pr.

BREAKING CHANGE: graphql.datafetcher·graphql.dataloader timer의 tag가
graphql.schema.coordinate·graphql.outcome·graphql.resolver.weight와
graphql.dataloader.name·graphql.outcome·graphql.batch.size.bucket으로
바뀐다. graphql.request는 error.type=NONE·graphql.complexity.bucket=unknown을
단다. 두 convention의 tag key도 바뀐다.
Refs: round9 그룹 A 범위 밖 후속 1
2026-11-13 19:30:12 +09:00

172 lines
12 KiB
Plaintext

# GraphQL leaf public API surface — every public top-level type in src/main/java.
# A public type in a single-jar leaf is reachable from every adopter's code, so
# additions are reviewed rather than discovered. `api` is the intended external
# surface; the rest are candidates to become internal when this leaf is split into
# capability artifacts.
# Update only after review with:
# ./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange
# types: 163
dev.caskeleton.adapter.inbound.graphql.HealthGraphqlController
dev.caskeleton.adapter.inbound.graphql.api.GraphQlClientProfile
dev.caskeleton.adapter.inbound.graphql.api.GraphQlOperationId
dev.caskeleton.adapter.inbound.graphql.api.GraphQlOperationName
dev.caskeleton.adapter.inbound.graphql.api.GraphQlSchemaCoordinate
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlActivationEnvironmentPostProcessor
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlDeploymentMode
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformAutoConfiguration
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformConfigurationException
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformRuntime
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformSettings
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformStartupValidator
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRetiredSafetyAxis
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRootAutoConfiguration
dev.caskeleton.adapter.inbound.graphql.context.ActorRef
dev.caskeleton.adapter.inbound.graphql.context.GraphQlCommandAttribution
dev.caskeleton.adapter.inbound.graphql.context.GraphQlDeadline
dev.caskeleton.adapter.inbound.graphql.context.GraphQlIdentityFingerprinter
dev.caskeleton.adapter.inbound.graphql.context.GraphQlRequestContext
dev.caskeleton.adapter.inbound.graphql.context.TenantContext
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlComplexityCalculator
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlComplexityRejectedException
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlComplexityResult
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlCostCatalog
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlDocumentComplexityScorer
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlDocumentShape
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlDocumentShapeAnalyzer
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlFieldCostDescriptor
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlResolverWeight
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlStructuralLimitException
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlStructuralLimitPolicy
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlStructuralLimits
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchChunker
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchContext
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchErrorPolicy
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchExecutor
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchLoadException
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchObservation
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchPolicy
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchPolicyRegistry
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchResult
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchResultMapper
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchTimeoutException
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchValue
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlDataLoaderFactory
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlDataLoaderName
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlMissingKeyException
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlMissingKeyPolicy
dev.caskeleton.adapter.inbound.graphql.error.GraphQlErrorCategory
dev.caskeleton.adapter.inbound.graphql.error.GraphQlErrorCode
dev.caskeleton.adapter.inbound.graphql.error.GraphQlErrorContext
dev.caskeleton.adapter.inbound.graphql.error.GraphQlExceptionResolver
dev.caskeleton.adapter.inbound.graphql.error.GraphQlInternalErrorMasker
dev.caskeleton.adapter.inbound.graphql.error.GraphQlPlatformRejection
dev.caskeleton.adapter.inbound.graphql.error.GraphQlWireError
dev.caskeleton.adapter.inbound.graphql.error.GraphQlWireErrorMapper
dev.caskeleton.adapter.inbound.graphql.error.GraphQlWireErrors
dev.caskeleton.adapter.inbound.graphql.execution.BoundedPreparsedDocumentProvider
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlAnonymousOperationException
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionPipeline
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionPipelineException
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionPipelineValidator
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionStage
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlOperationSelection
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlPreparsedCacheKey
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlPreparsedCacheMetrics
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlPreparsedCachePolicy
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlRequestCancelledException
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlFetchProfile
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlFetchProfileClassifier
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlFetchProfileName
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlFetchProfileRegistry
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlFetchProfileRule
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlFetchProfileValidationException
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlSelectionCoordinate
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlSelectionSetView
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlSelectionSignature
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlUnmappedSelectionException
dev.caskeleton.adapter.inbound.graphql.http.GraphQlExtensionsPolicy
dev.caskeleton.adapter.inbound.graphql.http.GraphQlHttpContractException
dev.caskeleton.adapter.inbound.graphql.http.GraphQlHttpOutcome
dev.caskeleton.adapter.inbound.graphql.http.GraphQlJsonStructurePolicy
dev.caskeleton.adapter.inbound.graphql.http.GraphQlJsonValues
dev.caskeleton.adapter.inbound.graphql.http.GraphQlRequestFormatException
dev.caskeleton.adapter.inbound.graphql.http.GraphQlRequestSize
dev.caskeleton.adapter.inbound.graphql.http.GraphQlRequestTooLargeException
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlBatchMutationItemResult
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlBusinessResult
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlExpectedVersion
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationContractException
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationContractValidator
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationCoordinate
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationPayload
dev.caskeleton.adapter.inbound.graphql.mutation.GraphQlMutationResultMapper
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlDataLoaderObservationConvention
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlMetricCardinalityPolicy
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlObservationContractException
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlObservationNames
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlOperationNameCardinality
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlRequestObservationConvention
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlResolverObservationConvention
dev.caskeleton.adapter.inbound.graphql.observation.GraphQlSensitiveAttributeFilter
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlConnection
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlConnectionAssembler
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlConnectionException
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlConnectionPolicy
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlConnectionRequest
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlCursorCodec
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlCursorException
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlCursorFraming
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlCursorKeyRing
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlCursorKeyset
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlCursorPayload
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlCursorScope
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlCursorVersion
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlEdge
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlKeysetWindow
dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlPageInfo
dev.caskeleton.adapter.inbound.graphql.pagination.HmacGraphQlCursorCodec
dev.caskeleton.adapter.inbound.graphql.policy.GraphQlClientPolicy
dev.caskeleton.adapter.inbound.graphql.policy.GraphQlOperationType
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlBatchLoaderRegistrar
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlCostBudgetHandler
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlDataFetcherExceptionResolver
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlDataLoaderObservationConventionAdapter
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlDeadlineInstrumentation
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlDocumentAuthorizationHandler
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlExecutionChain
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlExecutionContext
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlExecutionHandler
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlExecutionRequest
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlOperationSelectionHandler
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlPerParentFetchInstrumentation
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlPlatformInstrumentation
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlPlatformWebInterceptor
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlPreparsedDocumentAdapter
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlPrincipalResolver
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlRequestObservationConventionAdapter
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlResolverObservationConventionAdapter
dev.caskeleton.adapter.inbound.graphql.runtime.servlet.GraphQlRequestBodyLimitFilter
dev.caskeleton.adapter.inbound.graphql.scalar.BigDecimalScalar
dev.caskeleton.adapter.inbound.graphql.scalar.DateScalar
dev.caskeleton.adapter.inbound.graphql.scalar.GraphQlDecimalBounds
dev.caskeleton.adapter.inbound.graphql.scalar.GraphQlScalarWiringConfigurer
dev.caskeleton.adapter.inbound.graphql.scalar.InstantScalar
dev.caskeleton.adapter.inbound.graphql.scalar.LongScalar
dev.caskeleton.adapter.inbound.graphql.scalar.UuidScalar
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlScalarDefinition
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlScalarManifest
dev.caskeleton.adapter.inbound.graphql.schema.GraphQlScalarPolicy
dev.caskeleton.adapter.inbound.graphql.security.ApplicationObjectAuthorization
dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthenticatedPrincipal
dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthenticationContextFactory
dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthenticationException
dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthorizationDecision
dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthorizationDeniedException
dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthorizationInterceptor
dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthorizationPolicy
dev.caskeleton.adapter.inbound.graphql.security.GraphQlBatchContext
dev.caskeleton.adapter.inbound.graphql.security.GraphQlContextPropagator
dev.caskeleton.adapter.inbound.graphql.security.GraphQlObjectAuthorizationPort
dev.caskeleton.adapter.inbound.graphql.security.GraphQlTenantIsolationException
dev.caskeleton.adapter.inbound.graphql.security.GraphQlTenantIsolationPolicy