GraphQL 错误处理有哪些最佳实践？

核心回答

GraphQL 错误处理的最佳实践可以归纳为五个关键维度：规范化的错误结构、自定义错误类体系、统一格式化与日志、优雅降级与重试、实时监控与告警。核心原则是——永远不要让客户端收到无法理解的错误，也不要在生产环境中泄露内部实现细节。

为什么 GraphQL 的错误处理和 REST 不一样？

REST 靠 HTTP 状态码传达错误语义，而 GraphQL 无论成功失败都返回 200，错误信息放在响应体的 errors 数组中。这意味着 GraphQL 需要一套独立的错误表达体系，不能照搬 REST 的思维。

标准的 GraphQL 错误响应结构如下：

json
{
  "data": { "user": null },
  "errors": [
    {
      "message": "User not found",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["user"],
      "extensions": {
        "code": "NOT_FOUND",
        "timestamp": "2024-01-01T12:00:00Z"
      }
    }
  ]
}

其中 extensions 是最值得利用的字段——它允许你携带自定义的错误码、时间戳、请求 ID 等上下文，是结构化错误处理的基础。

如何设计自定义错误类体系？

一套清晰的错误类层次结构是所有后续实践的前提。建议按业务语义划分，而非按技术层划分：

javascript
class AppError extends Error {
  constructor(message, code, extensions = {}) {
    super(message);
    this.code = code;
    this.extensions = { ...extensions, timestamp: new Date().toISOString() };
  }
}

class NotFoundError extends AppError {
  constructor(resource, id) {
    super(`${resource} not found`, 'NOT_FOUND', { resource, id });
  }
}

class ValidationError extends AppError {
  constructor(message, field) {
    super(message, 'VALIDATION_ERROR', { field });
  }
}

class AuthError extends AppError {
  constructor(message = 'Authentication required') {
    super(message, 'AUTH_ERROR');
  }
}

class RateLimitError extends AppError {
  constructor(retryAfter) {
    super('Rate limit exceeded', 'RATE_LIMIT', { retryAfter });
  }
}

在 Resolver 中直接抛出语义明确的错误：

javascript
const resolvers = {
  Query: {
    user: async (_, { id }) => {
      const user = await User.findById(id);
      if (!user) throw new NotFoundError('User', id);
      return user;
    }
  }
};

如何统一错误格式化？

自定义错误类定义了"抛什么"，formatError 决定了"返回什么"。两者配合才能确保客户端收到一致且安全的错误响应：

javascript
const formatError = (error) => {
  const original = error.originalError;

  // 自定义业务错误：透传结构化信息
  if (original instanceof AppError) {
    return {
      message: error.message,
      extensions: {
        code: original.code,
        ...original.extensions
      }
    };
  }

  // 生产环境：屏蔽内部错误细节
  if (process.env.NODE_ENV === 'production') {
    return {
      message: 'Internal server error',
      extensions: { code: 'INTERNAL_ERROR' }
    };
  }

  // 开发环境：返回完整堆栈
  return {
    message: error.message,
    extensions: { code: 'INTERNAL_ERROR', stack: error.stack }
  };
};

关键点：生产环境绝不暴露堆栈信息或数据库错误原文，这是 GraphQL 安全的第一条铁律。

怎么处理部分成功和降级？

GraphQL 的一个独特优势是部分成功——某个字段报错不影响其他字段正常返回。利用这一点可以设计降级策略：

javascript
const resolvers = {
  Query: {
    userProfile: async (_, { id }, { dataSources }) => {
      try {
        return await dataSources.userAPI.getUser(id);
      } catch (error) {
        // 优先返回缓存数据
        const cached = await redis.get(`user:${id}`);
        if (cached) return JSON.parse(cached);

        // 缓存也没有则返回降级数据，标记为 fallback
        return { id, name: 'Unknown', isFallback: true };
      }
    }
  }
};

对于批量操作，推荐使用 错误结果类型（Error Result Type）模式，在 Schema 层面表达"部分成功"：

graphql
type UserResult {
  user: User
  errors: [FieldError!]!
  success: Boolean!
}

这样客户端可以明确处理每个字段的错误，而不是面对一个笼统的 errors 数组。

如何实现错误日志与监控？

错误格式化解决的是"客户端看到什么"，日志和监控解决的是"团队看到什么"。推荐使用 Apollo Server 插件机制：

javascript
const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [{
    requestDidStart: () => ({
      didEncounterErrors: (ctx) => {
        ctx.errors.forEach(error => {
          logger.error({
            message: error.message,
            code: error.extensions?.code,
            path: error.path,
            operation: ctx.request.operationName
          });

          // 同步上报到 Sentry
          Sentry.captureException(error, {
            tags: { graphql: true },
            extra: { query: ctx.request.query }
          });
        });
      }
    })
  }]
});

告警方面，建议监控两个指标：错误率（errors / total requests）和 P99 延迟。当错误率超过 5% 或 P99 延迟突增时自动触发告警，这比逐条看日志高效得多。

重试机制怎么设计才合理？

不是所有错误都该重试。只有网络超时、服务暂时不可用等瞬态错误适合重试，业务逻辑错误（如验证失败、资源不存在）重试毫无意义：

javascript
async function withRetry(operation, maxRetries = 3, baseDelay = 1000) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await operation();
    } catch (error) {
      if (!isRetryable(error) || i === maxRetries - 1) throw error;
      await new Promise(r => setTimeout(r, baseDelay * Math.pow(2, i)));
    }
  }
}

function isRetryable(error) {
  const retryable = ['NETWORK_ERROR', 'TIMEOUT', 'SERVICE_UNAVAILABLE'];
  return retryable.includes(error.code);
}

使用指数退避（exponential backoff）而非固定间隔，避免在服务端压力最大时雪崩式重试。

追问：GraphQL 错误处理和 REST 相比有什么本质区别？

GraphQL 统一返回 HTTP 200，错误语义完全由响应体中的 errors 数组承载，支持部分成功——这是最大的区别。REST 每个请求只有一个状态码，要么成功要么失败；GraphQL 一个请求中多个字段可以各自成功或失败，客户端需要逐字段处理错误。这意味着 GraphQL 的错误处理更细粒度，但也要求开发者在 Schema 设计阶段就考虑好错误类型定义，不能事后补救。