GraphQL Yoga 日志记录与调试指南

前言

在开发 GraphQL 服务时，良好的日志记录和调试能力是保障服务稳定运行的关键。GraphQL Yoga 提供了完善的日志系统，帮助开发者监控服务运行状态、排查问题。本文将详细介绍 GraphQL Yoga 的日志功能，包括日志级别配置、自定义日志实现等实用技巧。

日志级别详解

GraphQL Yoga 采用四级日志系统，按重要性从高到低依次为：

1. error - 仅记录意外错误
2. warn - 包含 error 级别，增加记录弃用警告
3. info - 包含 warn 级别，增加系统状态信息
4. debug - 包含 info 级别，增加详细处理过程

默认日志级别

默认情况下，GraphQL Yoga 会记录 info、warn 和 error 级别的日志，debug 级别需要显式开启。

启用调试日志

在开发环境中，我们经常需要查看更详细的日志信息。有两种方式可以启用 debug 日志：

通过环境变量

在支持 process.env 的 JavaScript 环境（如 Node.js）中，可以设置 DEBUG 环境变量为 1：

DEBUG=1 node server.js

通过代码配置

import { createYoga } from 'graphql-yoga'

const yoga = createYoga({
  schema,
  logging: 'debug'  // 显式启用 debug 日志
})

自定义日志级别

根据实际需求，可以调整日志级别。例如在生产环境中，可能只需要记录警告和错误：

const yoga = createYoga({
  schema,
  logging: 'warn'  // 只记录 warn 和 error 级别
})

实现自定义日志处理器

GraphQL Yoga 允许完全自定义日志处理器，方便集成到现有日志系统中：

const yoga = createYoga({
  schema,
  logging: {
    debug(...args) {
      // 自定义 debug 日志处理
    },
    info(...args) {
      // 自定义 info 日志处理
    },
    warn(...args) {
      // 自定义 warn 日志处理
    },
    error(...args) {
      // 自定义 error 日志处理
    }
  }
})

高级日志控制

对于更精细的日志控制，可以使用 Envelop 的 useLogger 插件：

import { useLogger } from 'graphql-yoga'

const yoga = createYoga({
  schema,
  plugins: [
    useLogger({
      logFn: (eventName, args) => {
        // 可以捕获执行开始/结束、订阅开始/结束等事件
        // args 包含执行参数或结果
      }
    })
  ]
})

最佳实践建议

1. 生产环境建议使用 warn 或 error 级别
2. 开发环境可以启用 debug 级别获取详细日志
3. 考虑将日志集成到现有监控系统中
4. 敏感信息不应记录在日志中

结语

GraphQL Yoga 的日志系统提供了灵活而强大的监控能力。通过合理配置日志级别和自定义日志处理器，开发者可以轻松掌握服务运行状态，快速定位问题。希望本文能帮助您更好地利用 GraphQL Yoga 的日志功能构建稳定的 GraphQL 服务。