GraphQL 错误处理与可观测性：从 errors[] 到链路追踪

{
  "data": { "user": null },
  "errors": [
    {
      "message": "User not found",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["user"]
    }
  ],
  "extensions": {
    "requestId": "req_01HZ..."
  }
}

// 业务错误：抛出带有明确 code 的 GraphQLError
throw new GraphQLError('Insufficient balance', {
  extensions: { code: 'INSUFFICIENT_BALANCE', field: 'amount' },
});

// 系统错误：包装下游异常，保留内部信息但不上抛给客户端
catch (err) {
  logger.error('payment service failed', { err, requestId });
  throw new GraphQLError('Payment service temporarily unavailable', {
    extensions: { code: 'UPSTREAM_UNAVAILABLE', retryable: true },
  });
}

import { GraphQLError } from 'graphql';
// Apollo Server 4 中推荐直接用 GraphQLError + extensions
throw new GraphQLError('Insufficient balance', {
  extensions: { code: 'RULE_INSUFFICIENT_BALANCE', http: { status: 422 } },
});

// errors/ValidationError.ts
import { GraphQLError } from 'graphql';

interface FieldIssue {
  field: string;
  code: string;
  message: string;
}

export class ValidationError extends GraphQLError {
  constructor(issues: FieldIssue[]) {
    super('Validation failed', {
      extensions: {
        code: 'VALIDATION_FAILED',
        issues,
      },
    });
  }
}

throw new ValidationError([
  { field: 'email', code: 'EMAIL_INVALID', message: '邮箱格式不正确' },
  { field: 'password', code: 'PASSWORD_TOO_SHORT', message: '密码至少 8 位' },
]);

import { unwrapResolverError } from '@apollo/server/errors';

const server = new ApolloServer({
  typeDefs,
  resolvers,
  formatError: (formattedError, error) => {
    // 系统错误的内部 stack 只进日志
    const unwrapped = unwrapResolverError(error);
    if (unwrapped instanceof Error && (unwrapped as any).internal) {
      logger.error('internal error', { err: unwrapped });
    }
    return {
      message: formattedError.message,
      path: formattedError.path,
      extensions: {
        code: formattedError.extensions?.code ?? 'INTERNAL_ERROR',
        field: formattedError.extensions?.field,
        issues: formattedError.extensions?.issues,
        requestId: reqContext.requestId,
      },
    };
  },
});

import { z } from 'zod';

const createUserSchema = z.object({
  email: z.string().email('邮箱格式不正确'),
  password: z.string().min(8, '密码至少 8 位'),
  nickname: z.string().min(1, '昵称不能为空').max(20, '昵称最长 20 字'),
});

export async function createUser(_root, args, ctx) {
  const parsed = createUserSchema.safeParse(args.input);
  if (!parsed.success) {
    const issues = parsed.error.issues.map((issue) => ({
      field: issue.path.join('.'),
      code: `VALIDATION_${issue.code.toUpperCase()}`,
      message: issue.message,
    }));
    throw new ValidationError(issues); // 一次返回全部字段问题
  }
  // ... 业务逻辑
}

type Order {
  id: ID!
  # 若 items 抛错，整个 Order 变 null
  items: [OrderItem!]!
}

type Order {
  id: ID!
  status: OrderStatus!
  # 推荐强列表
  items: [OrderItem!]!
  # 次级字段允许失败降级
  shipping: ShippingInfo
}

type ShippingInfo {
  carrier: String!
  trackingNo: String
  estimatedDelivery: String
}

// Apollo Client：正确处理 partial data
const { data, error } = useQuery(GET_ORDER, { errorPolicy: 'all' });
// errorPolicy: 'all' 让 errors 不阻塞 data 的返回

if (data?.order) {
  renderOrder(data.order);            // 渲染可用的部分
  if (error) {
    renderInlineWarning(error);       // 同时提示局部失败
  }
} else {
  renderErrorState(error);            // 整体失败
}

// middleware/request-logger.ts
export function logRequest(context) {
  const { requestId, operationName, query, variables, errors, latency } = context;
  logger.info('graphql.request', {
    requestId,
    operationName,
    query: operationName === undefined ? query : undefined, // 变量化查询不记全量
    variables: sanitize(variables), // 脱敏密码、token
    errorCodes: errors?.map((e) => e.extensions?.code),
    latencyMs,
    userId: context.user?.id,
  });
}

import { trace, context, SpanStatusCode } from '@opentelemetry/api';
import { RequestHandler } from 'express';

export const traceMiddleware: RequestHandler = (req, res, next) => {
  const tracer = trace.getTracer('graphql-server');
  return tracer.startActiveSpan('graphql.request', (span) => {
    span.setAttribute('http.method', req.method);
    const requestId = req.headers['x-request-id'] as string ?? crypto.randomUUID();
    span.setAttribute('graphql.requestId', requestId);
    res.locals.requestId = requestId;

    // 将 traceId 透传给下游
    const propagationHeaders = {};
    propagation.inject(context.active(), propagationHeaders);
    res.locals.propagationHeaders = propagationHeaders;

    res.on('finish', () => {
      span.setStatus(res.statusCode >= 500 ? SpanStatusCode.ERROR : SpanStatusCode.OK);
      span.end();
    });
    next();
  });
};

// apollo/link/errorHandler.ts
import { onError } from '@apollo/client/link/error';

export const errorLink = onError(({ graphQLErrors, networkError, operation }) => {
  if (graphQLErrors) {
    for (const err of graphQLErrors) {
      const code = err.extensions?.code;
      switch (code) {
        case 'UNAUTHORIZED':
          redirectToLogin();
          return;
        case 'FORBIDDEN':
          notify('没有权限执行此操作');
          return;
        case 'VALIDATION_FAILED':
          // 交由表单组件读取 issues 渲染
          return;
        default:
          notify(err.message);
      }
    }
  }
  if (networkError) {
    notify('网络异常，请稍后重试');
  }
});

// 重试策略：指数退避 + 抖动
const retryDelay = (attempt: number) => Math.min(1000 * 2 ** attempt, 10_000) + Math.random() * 300;

mutation PayOrder($input: PayOrderInput!) {
  payOrder(input: $input) {
    order {
      id
      status
    }
  }
}