koatty_logger

koatty_logger

企业级日志组件，专为 koatty 框架设计，具备强大的安全防护和性能优化特性。

✨ 特性

🔒 安全特性

• 路径遍历防护: 防止恶意路径访问系统敏感文件
• 日志注入防护: 自动过滤控制字符，防止日志伪造攻击
• 数据脱敏: 支持敏感字段自动脱敏，保护隐私数据
• 输入验证: 严格验证日志路径和内容的安全性

⚡ 性能优化

• 异步写入: 默认采用异步日志写入，避免阻塞主线程
• 批量写入: 高并发场景下的批量日志写入，显著提升性能
• 内存管理: 智能内存清理，防止内存泄漏
• 递归限制: 防止深层对象导致的性能问题
• 高效克隆: 优化对象克隆算法，提升脱敏性能
• 日志轮转: 基于时间和大小的智能日志轮转

📦 安装

npm install koatty_logger

🚀 快速开始

基础使用（推荐大多数场景）

import { DefaultLogger } from 'koatty_logger';

// 🎉 开箱即用 - 零配置,立即可用
DefaultLogger.info('应用启动成功');
DefaultLogger.warn('警告信息');
DefaultLogger.error('发生错误', new Error('示例错误'));
DefaultLogger.fatal('致命错误');  // ⚡ 新增:同步写入,进程退出时不丢失

// 💡 可选：配置日志级别和文件路径
DefaultLogger.configure({
  minLevel: 'debug',
  logFilePath: './logs/app.log',
  sensFields: new Set(['password', 'token'])
});

// 💡 动态调整配置（运行时）
DefaultLogger.setMinLevel('error');  // 只记录错误
DefaultLogger.enableBuffering();     // 启用高性能缓冲模式
DefaultLogger.disableBuffering();    // 禁用缓冲,实时输出

✨ DefaultLogger 特性：

• ✅ 开箱即用: 零配置,直接调用即可
• ✅ 动态配置: 运行时可随时调整级别、路径、缓冲等
• ✅ 容错降级: 初始化失败自动降级到 console 输出
• ✅ 全局单例: 配置一次,全局生效
• ✅ 便捷 API: 提供丰富的便捷方法,简化使用

高级用法（多实例场景）

适用于微服务、插件系统、复杂架构等需要独立日志器的场景：

import { Logger } from 'koatty_logger';

// 创建独立的日志器实例
const auditLogger = new Logger({
  logLevel: 'info',
  logFilePath: './logs/audit.log',
  buffer: {
    enableBuffer: true,
    maxBufferSize: 500,
    flushInterval: 100
  }
});

const userServiceLogger = new Logger({
  logLevel: 'debug',
  logFilePath: './logs/user-service.log',
  sensFields: new Set(['password', 'ssn'])
});

auditLogger.info('审计日志', { action: 'login', userId: 123 });
userServiceLogger.debug('用户服务日志');

📖 使用建议：

• 大多数场景: 使用 DefaultLogger (简单、便捷、统一)
• 微服务架构: 使用 new Logger() (隔离、独立、灵活)
• 混合使用: 主应用用 DefaultLogger,关键模块用独立 Logger

Fatal 日志级别 (v2.7+)

解决进程退出时日志丢失问题:

// ❌ 问题: 异步日志在进程退出时会丢失
DefaultLogger.error('Critical error');
process.exit(1);  // 日志可能丢失!

// ✅ 解决方案1: 使用 fatal (同步写入)
DefaultLogger.fatal('Critical error');
process.exit(1);  // 日志已写入,不会丢失

// ✅ 解决方案2: 使用 fatalAndExit (推荐)
await DefaultLogger.fatalAndExit('Critical error', 1);

// ✅ 解决方案3: 全局异常处理
process.on('uncaughtException', async (error) => {
  await DefaultLogger.fatalAndExit('Uncaught exception', 1, error);
});

Fatal 特性:

• ⚡ 同步写入 - 确保日志不丢失
• 🎯 最高优先级 - 总是被记录
• 📝 双重输出 - 同时写入文件和 console
• 🚀 立即刷新 - 触发缓冲区刷新

详细文档: Fatal 日志级别指南

详细示例请参考：

• DefaultLogger 综合示例
• Logger 对比示例
• Fatal 日志示例

安全配置

import { Logger } from 'koatty_logger';

const logger = new Logger({
  logLevel: 'info',
  logFilePath: './logs/app.log',
  sensFields: new Set(['password', 'token', 'secret'])
});

// 敏感数据会自动脱敏
logger.info('用户登录', {
  username: 'john',
  password: 'secret123',  // 会被脱敏为 sec***23
  email: '[e-mail]'
});

高级用法

// 异步日志写入（默认行为）
// Winston本身就是异步的，koatty_logger进一步优化了异步处理
logger.info('这条日志会异步写入，不会阻塞主线程');
logger.error('错误日志也是异步的');

// 批量写入模式 vs 异步单条写入模式
const asyncLogger = new Logger({
  logLevel: 'info',
  logFilePath: './logs/async.log'
  // 默认不启用批量写入，使用异步单条写入
});

const bufferedLogger = new Logger({
  logLevel: 'info', 
  logFilePath: './logs/buffered.log',
  buffer: {
    enableBuffer: true,   // 启用缓冲
    maxBufferSize: 100,   // 缓冲区最大100条日志
    flushInterval: 1000,  // 每秒检查一次是否需要刷新
    flushOnLevel: 'error' // error级别立即刷新
  }
});

// 动态管理敏感字段
logger.setSensFields(['creditCard', 'ssn']);
logger.clearSensFields();  // 清空敏感字段
logger.resetSensFields(['newSensitiveField']);  // 重置敏感字段

// 安全的日志文件路径设置
try {
  logger.setLogFilePath('app.log');  // ✅ 安全路径
  logger.setLogFilePath('../../../etc/passwd');  // ❌ 会抛出安全异常
} catch (error) {
  console.error('路径不安全:', error.message);
}

// 高性能缓冲配置
const highPerfLogger = new Logger({
  logLevel: 'info',
  logFilePath: './logs/high-perf.log',
  buffer: {
    enableBuffer: true,   // 启用缓冲
    maxBufferSize: 100,   // 缓冲区最大100条日志
    flushInterval: 1000,  // 每秒检查一次是否需要刷新
    flushOnLevel: 'error' // error级别立即刷新
  }
});

// 缓冲控制
await highPerfLogger.flush();  // 立即异步刷新缓冲区

// 获取统计信息
const stats = highPerfLogger.getStats();
if (stats) {
  console.log('缓冲区大小:', stats.buffer.bufferSize);
  console.log('总日志数:', stats.buffer.totalLogs);
}

// 动态调整缓冲配置
highPerfLogger.configureBuffering({
  maxBufferSize: 200,   // 调整缓冲区大小
  flushInterval: 500    // 调整检查间隔
});

// 优雅关闭（确保所有日志都被写入）
process.on('SIGINT', async () => {
  console.log('正在关闭应用...');
  await highPerfLogger.flush(); // 等待所有日志写入完成
  await highPerfLogger.destroy(); // 释放所有资源
  process.exit(0);
});

// 资源清理
logger.destroy();  // 释放所有资源

🔧 API 文档

Logger 类

构造函数

new Logger(options?: LoggerOpt)

主要方法

方法	描述	特性
info(...args)	输出信息日志	异步写入，自动过滤注入字符
error(...args)	输出错误日志	异步写入，自动过滤注入字符
debug(...args)	输出调试日志	异步写入，自动过滤注入字符
warn(...args)	输出警告日志	异步写入，自动过滤注入字符
setLogFilePath(path)	设置日志文件路径	路径遍历防护
setSensFields(fields)	设置敏感字段	数据脱敏
clearSensFields()	清空敏感字段	内存清理
configureBuffering(config)	配置缓冲功能	高并发性能优化
configureSampling(key, rate)	配置采样率	减少高频日志
setMinLevel(level)	设置最小日志级别	动态级别过滤
getStats()	获取统计信息	监控日志状态
flush()	立即刷新缓冲区	异步操作，返回Promise
destroy()	销毁实例	资源释放，异步刷新剩余日志

配置选项

interface LoggerOpt {
  logLevel?: 'debug' | 'info' | 'warning' | 'error';
  logFilePath?: string;  // 安全验证的日志路径
  sensFields?: Set<string>;  // 敏感字段集合
  // 增强功能配置
  buffer?: BufferConfig;  // 缓冲配置
  sampling?: SamplingConfig;  // 采样配置
  minLevel?: LogLevelType;  // 最小日志级别
}

interface BatchConfig {
  enabled?: boolean;        // 是否启用批量写入
  maxSize?: number;         // 最大缓冲区大小（条目数）
  flushInterval?: number;   // 刷新间隔检查（毫秒）
  maxWaitTime?: number;     // 最大等待时间（毫秒）
}

🛡️ 安全最佳实践

1. 路径安全

// ✅ 推荐：使用相对路径
logger.setLogFilePath('logs/app.log');

// ❌ 避免：绝对路径或路径遍历
logger.setLogFilePath('/var/log/app.log');        // 可能失败
logger.setLogFilePath('../../../sensitive.log');  // 会抛出异常

2. 敏感数据保护

// 设置敏感字段
logger.setSensFields([
  'password', 'token', 'secret', 'key',
  'creditCard', 'ssn', 'phone', 'email'
]);

// 敏感数据会自动脱敏
const userData = {
  name: 'John',
  password: 'mySecret123',  // 会显示为 myS****123
  phone: '1234567890'       // 会显示为 123***7890
};
logger.info('用户数据', userData);

3. 注入防护

日志组件会自动过滤以下危险字符：

• 换行符 (\n, \r)
• 制表符 (\t)
• 控制字符 (\x00-\x1f, \x7f)

4. 异步日志最佳实践

// ✅ 推荐：默认使用异步日志（无需特殊配置）
const logger = new Logger({
  logLevel: 'info',
  logFilePath: './logs/app.log'
  // 默认就是异步写入，性能最优
});

// ✅ 推荐：高并发场景使用批量写入
const highConcurrencyLogger = new Logger({
  batchConfig: {
    enabled: true,
    maxSize: 100,        // 根据应用负载调整
    flushInterval: 1000, // 平衡性能和实时性
    maxWaitTime: 3000    // 确保日志不会丢失
  }
});

// ✅ 推荐：关键操作后手动刷新批量日志
await logger.flush(); // 确保重要日志立即写入

// ✅ 推荐：优雅关闭，等待所有日志写入完成
process.on('SIGTERM', async () => {
  console.log('接收到关闭信号，正在刷新日志...');
  await logger.flush();
  logger.destroy();
  process.exit(0);
});

// ⚠️ 注意：批量模式的权衡
// 缓冲模式：更高性能，但可能延迟写入
// 配置 flushOnLevel 可以让关键日志立即写入
const logger = new Logger({
  buffer: {
    enableBuffer: true,
    flushOnLevel: 'error'  // error 级别立即刷新
  }
});
logger.error('Critical system error'); // 立即刷新

5. 批量写入最佳实践

// ✅ 推荐：应用关闭前手动刷新
process.on('SIGINT', async () => {
  await logger.flush();
  logger.destroy();
  process.exit(0);
});

// ⚠️ 注意：实时性要求高的日志可配置立即刷新
const logger = new Logger({
  buffer: {
    enableBuffer: true,
    flushOnLevel: 'error'  // error 和 warning 立即刷新
  }
});
logger.error('Critical error occurred'); // 立即写入

🚀 增强功能

koatty_logger 的 Logger 类已整合所有增强功能，无需单独使用 EnhancedLogger：

特性概览

• 智能缓冲: 可配置的日志缓冲机制，优化批量写入性能
• 日志采样: 减少高频日志数量，避免日志洪流
• 级别过滤: 运行时动态调整日志级别，灵活控制输出
• 统计监控: 实时统计日志处理情况，便于性能分析

使用增强功能

import { createLogger, Logger } from 'koatty_logger';

// 方式1: 使用工厂函数（推荐）
const logger = createLogger({
  minLevel: 'info',
  buffer: {
    enableBuffer: true,
    maxBufferSize: 100,
    flushInterval: 1000,
    flushOnLevel: 'error'
  },
  sampling: {
    sampleRates: new Map([
      ['high-frequency-api', 0.1],  // 10% 采样率
      ['debug-trace', 0.05]          // 5% 采样率
    ])
  }
});

// 方式2: 直接实例化
const enhancedLogger = new Logger({
  minLevel: 'debug',
  logFilePath: './logs/app.log',
  buffer: {
    enableBuffer: true,
    maxBufferSize: 200,
    flushInterval: 500
  }
});

缓冲配置

const logger = createLogger({
  buffer: {
    enableBuffer: true,        // 启用缓冲
    maxBufferSize: 100,        // 缓冲区最大100条
    flushInterval: 1000,       // 每秒检查一次
    flushOnLevel: 'error'      // error级别立即刷新
  }
});

// 动态调整缓冲配置
logger.configureBuffering({
  maxBufferSize: 200,
  flushInterval: 500
});

// 手动刷新缓冲区
await logger.flush();

// 获取统计信息
const stats = logger.getStats();
console.log('缓冲区大小:', stats.buffer.bufferSize);
console.log('总日志数:', stats.buffer.totalLogs);
console.log('丢弃日志数:', stats.buffer.droppedLogs);
console.log('丢弃率:', stats.buffer.droppedRate);

日志采样

const logger = createLogger({
  sampling: {
    sampleRates: new Map([
      ['api-request', 0.1],      // API请求只记录10%
      ['database-query', 0.05]   // 数据库查询只记录5%
    ])
  }
});

// 使用采样日志方法
logger.InfoSampled('api-request', 'API请求', { url: '/api/users', method: 'GET' });
logger.DebugSampled('database-query', 'SQL查询', { sql: 'SELECT * FROM users' });

// 动态调整采样率
logger.configureSampling('api-request', 0.2);  // 调整为20%

// 查看采样统计
const stats = logger.getStats();
stats.sampling?.forEach((value, key) => {
  console.log(`${key}: 采样率=${value.sampleRate}, 计数=${value.counter}`);
});

级别过滤

const logger = createLogger({
  minLevel: 'info'  // 只记录 info 及以上级别
});

// 这些日志会被过滤掉
logger.Debug('调试信息');  // ❌ 被过滤

// 这些日志会被记录
logger.Info('信息日志');   // ✅ 记录
logger.Warn('警告日志');   // ✅ 记录
logger.Error('错误日志');  // ✅ 记录

// 动态调整日志级别
logger.setLogLevel('debug');  // 现在 debug 日志也会被记录

// 查看当前级别
const stats = logger.getStats();
console.log('当前最小级别:', stats.minLevel);

综合示例

import { createLogger } from 'koatty_logger';

// 生产环境配置
const productionLogger = createLogger({
  minLevel: 'info',
  logFilePath: './logs/production.log',
  sensFields: new Set(['password', 'token', 'creditCard']),
  buffer: {
    enableBuffer: true,
    maxBufferSize: 200,
    flushInterval: 1000,
    flushOnLevel: 'error'
  },
  sampling: {
    sampleRates: new Map([
      ['http-request', 0.1],
      ['cache-hit', 0.01]
    ])
  }
});

// 普通日志
productionLogger.Info('应用启动', { port: 3000 });

// 采样日志（高频场景）
productionLogger.InfoSampled('http-request', '请求处理', {
  method: 'GET',
  url: '/api/users',
  duration: 45
});

// 自动脱敏
productionLogger.Info('用户登录', {
  username: 'john',
  password: 'secret123',  // 会被脱敏
  token: 'abc123xyz'      // 会被脱敏
});

// 获取统计信息
const stats = productionLogger.getStats();
console.log('日志统计:', {
  缓冲区: stats.buffer,
  采样: Object.fromEntries(stats.sampling || new Map()),
  级别: stats.minLevel
});

// 优雅关闭
process.on('SIGTERM', async () => {
  console.log('正在关闭应用...');
  await productionLogger.flush();
  productionLogger.stop();
  process.exit(0);
});

环境变量配置

增强日志器支持以下环境变量：

# 日志级别
export LOG_LEVEL=info            # debug | info | warn | error

# 缓冲配置
export LOG_BUFFER_SIZE=100       # 缓冲区大小
export LOG_FLUSH_INTERVAL=1000   # 刷新间隔（毫秒）
export LOG_FLUSH_ON_LEVEL=error  # 立即刷新的最低级别
export LOG_ENABLE_BUFFER=true    # 启用/禁用缓冲

# 环境配置（自动调整缓冲行为）
export NODE_ENV=development      # 开发环境：自动禁用缓冲，日志实时输出
export NODE_ENV=test             # 测试环境：自动禁用缓冲
export NODE_ENV=production       # 生产环境：启用缓冲，获得最佳性能

使用示例：

# 生产环境（启用批量写入）
NODE_ENV=production LOG_LEVEL=info npm start

# 开发环境（禁用批量写入，实时输出）
NODE_ENV=development LOG_LEVEL=debug npm run dev

# 测试环境（禁用批量写入）
NODE_ENV=test npm test

🔍 测试

# 运行所有测试
npm test

# 运行安全测试
npm test -- --testNamePattern="Security"

# 运行性能测试
npm test -- --testNamePattern="Performance"

📊 性能指标

• 异步写入: 相比同步写入，CPU阻塞时间减少 95%
• 批量写入: 高并发场景下性能提升 200-500%
  • 1000条/秒：性能提升 200%
  • 10000条/秒：性能提升 500%
  • 缓冲区命中率：95%+
• 内存使用: 优化后减少 30% 内存占用
• CPU开销: 脱敏算法优化，减少 40% CPU使用
• 处理速度: 大批量日志处理速度提升 50%

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

BSD-3-Clause License