Lepton API 参考：日志系统接口

Lepton API 参考：日志系统接口

【免费下载链接】Lepton 💻 Democratizing Snippet Management (macOS/Win/Linux) 项目地址: https://gitcode.com/gh_mirrors/le/Lepton

Lepton 应用内置了基于 Winston 的日志系统，为开发者提供了完善的日志记录功能。通过日志接口，你可以追踪应用运行状态、调试问题及监控关键操作。本文将详细介绍日志系统的初始化配置、级别控制和常用接口。

日志系统架构

Lepton 的日志系统采用 Winston 作为核心日志库，实现了多级别日志记录、文件输出和控制台打印功能。日志系统在应用启动阶段完成初始化，并通过全局变量暴露给整个应用使用。

关键实现文件：

• 日志初始化：main.js
• 配置读取：configs/defaultConfig.js
• 日志工具类：app/utilities/notifier/index.js

初始化配置

日志系统在应用启动时通过 initGlobalLogger() 函数完成初始化，该函数位于主进程入口文件中，主要完成以下工作：

function initGlobalLogger () {
  logger.level = nconf.get('logger:level')
  const appFolder = app.getPath('userData')
  const logFolder = path.join(app.getPath('userData'), 'logs')
  if (!fs.existsSync(logFolder)) {
    fs.mkdirSync(logFolder)
  }
  const logFile = new Date().toISOString().replace(/:/g, '.') + '.log'
  const logFilePath = path.join(logFolder, logFile)
  logger.add(logger.transports.File, {
      json: false,
      exitOnError: false,
      filename: logFilePath,
      timestamp: true })
  global.logger = logger
  global.logFilePath = logFilePath
}

默认配置参数可通过 .leptonrc 文件修改，配置路径解析逻辑见 main.js 的 getConfigPath() 函数：

function getConfigPath() {
  if (process && process.env && process.env.XDG_CONFIG_HOME) {
    return path.join(process.env.XDG_CONFIG_HOME, '.leptonrc'
  } else {
    return path.join(app.getPath('home'), '.leptonrc')
  }       
}

日志级别控制

Lepton 日志系统支持 Winston 定义的 6 个日志级别，按严重程度从低到高排序：

1. debug: 调试信息，用于开发阶段追踪代码执行流程
2. info: 普通信息，记录应用正常运行状态
3. warn: 警告信息，表示可能存在的问题但不影响应用运行
4. error: 错误信息，记录应用运行时错误
5. verbose: 详细信息，提供更深入的系统运行状态描述
6. silly: 冗余信息，用于极端详细的调试场景

级别配置通过 logger.level 属性设置，默认值可在配置文件中修改：

// 读取配置文件设置日志级别
logger.level = nconf.get('logger:level')

常用日志接口

基础日志方法

日志系统通过全局 logger 对象暴露接口，支持不同级别的日志记录：

// 记录信息日志
logger.info(`\n\n----- ${appInfo.name} v${appInfo.version} ${os.platform()}-----\n`)

// 记录调试日志
logger.debug('-----> registering login-page-ready listener')

// 记录错误日志
logger.error('[.leptonrc] Please correct the mistakes in your configuration file: [%s].\n' + error, configFilePath)

上下文日志记录

在实际开发中，建议为日志添加上下文标识，方便日志过滤和分析：

// 配置相关日志
logger.info(`[conf] Looking for .leptonrc at ${getConfigPath()}`)

// 自动更新相关日志
logger.debug('[autoUpdater] update-available. ' + mainWindow)

// 信号发送相关日志
logger.info('[signal] sending auto-login signal')

日志文件管理

日志文件默认存储在用户数据目录下的 logs 文件夹中，采用日期命名：

const logFile = new Date().toISOString().replace(/:/g, '.') + '.log'
const logFilePath = path.join(logFolder, logFile)

你可以通过全局变量 logFilePath 获取当前日志文件路径：

console.log('当前日志文件路径:', global.logFilePath)

使用场景示例

应用启动流程记录

// 应用启动信息
logger.info(`\n\n----- ${appInfo.name} v${appInfo.version} ${os.platform()}-----\n`)

// 配置加载过程
logger.info(`[conf] Looking for .leptonrc at ${getConfigPath()}`)
logger.info('[conf] The resolved configuration is ...')
for (const key of Object.getOwnPropertyNames(defaultConfig)) {
  logger.info(`"${key}": ${JSON.stringify(nconf.get(key))}`)    
}

错误处理与调试

// 配置文件错误处理
try {
  nconf.file({ file: configFilePath })
} catch (error) {
  logger.error('[.leptonrc] Please correct the mistakes in your configuration file: [%s].\n' + error, configFilePath)
}

// 自动更新错误处理
autoUpdater.on('error', data => {
  logger.debug('[autoUpdater] error ' + JSON.stringify(data))
})

用户操作追踪

// 窗口关闭事件
app.on('window-all-closed', () => {
  logger.info('The app window is closed')
  if (process.platform !== 'darwin') app.quit()
  mainWindow = null
})

// 登录流程
ipcMain.on('login-page-ready', () => {
  logger.info('[signal] sending auto-login signal')        
  mainWindow.webContents.send('auto-login')
  ipcMain.removeAllListeners('login-page-ready')
})

最佳实践

1. 日志级别使用规范

   • 使用 debug 级别记录开发调试信息，生产环境可禁用
   • 使用 info 级别记录用户关键操作和系统状态变化
   • 使用 warn 级别记录可能导致问题的异常情况
   • 使用 error 级别记录影响功能的错误

2. 日志内容规范

   • 包含明确的上下文标识（如 [conf]、[autoUpdater]）
   • 记录关键参数但避免敏感信息
   • 错误日志应包含完整的错误堆栈信息

3. 性能考量

   • 避免在循环中记录大量日志
   • 复杂对象序列化前考虑使用 JSON.stringify() 的 replacer 参数过滤不必要字段
   • 生产环境适当提高日志级别，减少日志输出量

总结

Lepton 日志系统提供了灵活而强大的日志记录功能，通过合理使用不同级别的日志接口，你可以有效追踪应用运行状态、诊断问题和优化性能。日志系统的配置参数可以通过配置文件自定义，以适应不同环境和需求。

完整实现代码请参考：

• main.js - 日志系统初始化和主进程日志使用
• configs/defaultConfig.js - 日志默认配置
• app/utilities/notifier/index.js - 渲染进程日志工具

【免费下载链接】Lepton 💻 Democratizing Snippet Management (macOS/Win/Linux) 项目地址: https://gitcode.com/gh_mirrors/le/Lepton