10장: 프로덕션 운영과 모니터링

type User {
  id: ID!
  name: String!
  
  # 1단계: 새 필드 추가
  displayName: String!
  firstName: String!
  lastName: String!
  
  # 2단계: 기존 필드 Deprecated 표시
  fullName: String! @deprecated(reason: "Use displayName instead. Removal planned for 2026-Q3.")
}

# 1. 스키마 변경 검증 (PR에서 실행)
rover subgraph check my-graph@production \
  --name users \
  --schema ./schema.graphql
 
# 출력 예시:
# Comparing users schema changes against operation history...
# 
# FAIL: Found 2 breaking changes and 1 warning
# - FIELD_REMOVED: User.fullName was removed
#   Used by 23 operations in the last 90 days
# - REQUIRED_INPUT_FIELD_ADDED: CreateUserInput.phone is required
#   Affects all createUser operations
 
# 2. 스키마 배포 (merge 후 실행)
rover subgraph publish my-graph@production \
  --name users \
  --schema ./schema.graphql \
  --routing-url https://users.internal:4001/graphql

name: Schema Check
on:
  pull_request:
    paths:
      - 'schema.graphql'
      - 'src/schema/**'
 
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Rover
        run: |
          curl -sSL https://rover.apollo.dev/nix/latest | sh
          echo "$HOME/.rover/bin" >> $GITHUB_PATH
      
      - name: Check Schema
        env:
          APOLLO_KEY: ${{ secrets.APOLLO_KEY }}
        run: |
          rover subgraph check my-graph@production \
            --name ${{ matrix.subgraph }} \
            --schema ./subgraphs/${{ matrix.subgraph }}/schema.graphql

import { ApolloServer } from '@apollo/server';
import depthLimit from 'graphql-depth-limit';
import { createComplexityRule, simpleEstimator } from 'graphql-query-complexity';
 
const server = new ApolloServer({
  typeDefs,
  resolvers,
  validationRules: [
    // 깊이 제한
    depthLimit(12),
    
    // 복잡도 제한
    createComplexityRule({
      maximumComplexity: 1500,
      estimators: [simpleEstimator({ defaultComplexity: 1 })],
      onComplete: (complexity: number) => {
        if (complexity > 1000) {
          console.warn(`High complexity query: ${complexity}`);
        }
      },
    }),
  ],
});

import { rateLimitDirective } from 'graphql-rate-limit-directive';
 
const { rateLimitDirectiveTypeDefs, rateLimitDirectiveTransformer } =
  rateLimitDirective();
 
const typeDefs = `
  ${rateLimitDirectiveTypeDefs}
  
  type Query {
    posts: [Post!]! @rateLimit(limit: 100, duration: 60)
    search(query: String!): [SearchResult!]! @rateLimit(limit: 30, duration: 60)
  }
  
  type Mutation {
    createPost(input: CreatePostInput!): Post! @rateLimit(limit: 10, duration: 60)
    sendMessage(input: SendMessageInput!): Message! @rateLimit(limit: 60, duration: 60)
  }
`;

import { ApolloServer } from '@apollo/server';
 
const allowedOperations = new Map<string, string>();
// 빌드 타임에 생성된 쿼리 목록 로드
loadPersistedQueries(allowedOperations);
 
const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [
    {
      async requestDidStart() {
        return {
          async didResolveOperation(requestContext) {
            const hash =
              requestContext.request.extensions?.persistedQuery?.sha256Hash;
            
            if (process.env.NODE_ENV === 'production' && !hash) {
              throw new GraphQLError('Only persisted queries are allowed', {
                extensions: { code: 'PERSISTED_QUERY_REQUIRED' },
              });
            }
          },
        };
      },
    },
  ],
});

import { ApolloServer } from '@apollo/server';
import { ApolloServerPluginUsageReporting } from '@apollo/server/plugin/usageReporting';
 
const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [
    ApolloServerPluginUsageReporting({
      sendVariableValues: { none: true }, // 민감 데이터 제외
      sendHeaders: { onlyNames: ['x-request-id'] },
    }),
  ],
});

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { GraphQLInstrumentation } from '@opentelemetry/instrumentation-graphql';
import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
 
const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
  }),
  instrumentations: [
    new HttpInstrumentation(),
    new GraphQLInstrumentation({
      mergeItems: true,
      allowValues: false, // 인자 값 수집 안 함
      depth: 5,
    }),
  ],
});
 
sdk.start();

import { Counter, Histogram, register } from 'prom-client';
 
const queryDuration = new Histogram({
  name: 'graphql_query_duration_seconds',
  help: 'Duration of GraphQL queries',
  labelNames: ['operationName', 'status'],
  buckets: [0.01, 0.05, 0.1, 0.5, 1, 5],
});
 
const resolverErrors = new Counter({
  name: 'graphql_resolver_errors_total',
  help: 'Total number of resolver errors',
  labelNames: ['typeName', 'fieldName', 'errorCode'],
});
 
// Apollo Server 플러그인으로 수집
const metricsPlugin = {
  async requestDidStart() {
    const start = Date.now();
    return {
      async willSendResponse(requestContext: GraphQLRequestContext<Context>) {
        const duration = (Date.now() - start) / 1000;
        const hasErrors = (requestContext.errors?.length ?? 0) > 0;
        queryDuration
          .labels(
            requestContext.operationName ?? 'unknown',
            hasErrors ? 'error' : 'success',
          )
          .observe(duration);
      },
      async didEncounterErrors(requestContext: GraphQLRequestContext<Context>) {
        for (const error of requestContext.errors ?? []) {
          resolverErrors
            .labels(
              error.path?.[0]?.toString() ?? 'unknown',
              error.path?.[1]?.toString() ?? 'unknown',
              (error.extensions?.['code'] as string) ?? 'UNKNOWN',
            )
            .inc();
        }
      },
    };
  },
};

import { GraphQLError } from 'graphql';
 
// 클라이언트 에러: 사용자에게 상세 메시지 전달
class NotFoundError extends GraphQLError {
  constructor(resource: string, id: string) {
    super(`${resource} with ID ${id} not found`, {
      extensions: {
        code: 'NOT_FOUND',
        resource,
        id,
      },
    });
  }
}
 
class ValidationError extends GraphQLError {
  constructor(field: string, message: string) {
    super(message, {
      extensions: {
        code: 'VALIDATION_ERROR',
        field,
      },
    });
  }
}
 
// 서버 에러: 내부 정보 숨기고 일반 메시지 전달
class InternalError extends GraphQLError {
  constructor(originalError: Error) {
    super('An internal error occurred', {
      extensions: {
        code: 'INTERNAL_SERVER_ERROR',
        // 프로덕션에서는 originalError를 로그에만 기록
      },
    });
    console.error('Internal error:', originalError);
  }
}

const server = new ApolloServer({
  typeDefs,
  resolvers,
  formatError: (formattedError, error) => {
    // 프로덕션: 내부 에러 상세 숨기기
    if (process.env.NODE_ENV === 'production') {
      // 알려진 에러 코드만 전달
      const knownCodes = [
        'NOT_FOUND',
        'VALIDATION_ERROR',
        'UNAUTHENTICATED',
        'FORBIDDEN',
        'BAD_USER_INPUT',
      ];
 
      const code = formattedError.extensions?.['code'] as string | undefined;
      if (code && knownCodes.includes(code)) {
        return formattedError;
      }
 
      // 알 수 없는 에러는 일반 메시지로 대체
      return {
        message: 'An unexpected error occurred',
        extensions: { code: 'INTERNAL_SERVER_ERROR' },
      };
    }
 
    // 개발 환경: 전체 에러 정보 반환
    return formattedError;
  },
});