@spike.hmc/h-logger

标准化日志 SDK，基于 Winston 开发。

特性

• 🚀 零配置: 开箱即用，包含合理的默认设置。
• 🎨 美化打印: 为开发环境提供美观、带颜色的控制台输出。
• 📂 日志轮转: 每日自动轮转日志文件，并支持自动清理旧文件。
• 🔄 Pino 兼容: 同时支持 log.info(msg, meta) 和 log.info(meta, msg) 两种调用方式。
• 🧵 异步上下文: 使用 AsyncLocalStorage 自动注入 taskId 等上下文元数据。
• 📊 丰富格式化: 内置表格、树形结构和任务进度格式化工具。
• 🛡️ 类型安全: 完全使用 TypeScript 编写。

安装

npm install @spike.hmc/h-logger

快速上手

基础日志记录

import { log } from '@spike.hmc/h-logger';

// 标准记录
log.info('应用已启动');
log.warn('内存占用较高', { usage: '85%' });
log.error('处理请求失败', new Error('数据库连接超时'));

// Pino 风格记录 (元数据在前)
log.info({ userId: 123 }, '用户已登录');

初始化配置

你可以在应用启动时自定义日志行为：

import { log } from '@spike.hmc/h-logger';

log.init({
  serviceName: 'my-service',
  level: 'debug',
  pretty: true,        // 是否开启美化打印 (默认: true)
  toFile: true,        // 是否写入文件 (默认: true)
  logsDir: './my-logs' // 日志保存目录 (默认: './logs')
});

进阶用法

异步上下文管理

使用 withContext 或 withContextAsync 在特定的执行范围内自动注入元数据。

import { log } from '@spike.hmc/h-logger';

async function handleRequest(requestId: string) {
  await log.withContextAsync({ taskId: requestId }, async () => {
    // 该代码块内的所有日志都会自动包含 taskId
    log.info('正在处理请求'); // 输出: [INFO] [requestId] 正在处理请求
    
    await someAsyncOperation();
    
    log.info('请求处理完成');
  });
}

丰富的格式化工具

SDK 提供了专门的格式化工具，用于处理常见的日志展示场景。

表格和树形结构

import { createFormatters, log } from '@spike.hmc/h-logger';

const formatters = createFormatters(true); // true 表示开启颜色

// 1. 表格格式化
const headers = ['ID', '名称', '状态'];
const rows = [
  ['1', 'Bitcoin', 'Active'],
  ['2', 'Ethereum', 'Pending']
];
const tableLines = formatters.table.format(headers, rows);
tableLines.forEach(line => log.raw.info(line));

// 2. 树形/步骤格式化
const tree = formatters.tree;
log.info(tree.formatStep(1, 3, '验证输入'));
log.info(tree.formatStep(2, 3, '获取数据'));
log.info(tree.formatChildNode('子任务: 检查缓存'));
log.info(tree.formatStep(3, 3, '完成处理'));

// 3. 任务状态区块
formatters.tree.formatTaskStart('TRANSACTION_001', { chainId: 1 }).forEach(l => log.raw.info(l));
// ... 执行任务 ...
formatters.tree.formatTaskComplete('TRANSACTION_001', 1250).forEach(l => log.raw.info(l));

原始日志记录

如果你想绕过标准格式化或上下文注入：

log.raw.info('一条不带上下文或额外格式化的原始消息');

配置项说明

| 选项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | serviceName | string | 取自 package.json | 服务的名称 | | level | string | 'info' | 最低显示的日志级别 | | pretty | boolean | true | 使用人性化且带颜色的输出 | | toFile | boolean | true | 是否将日志写入轮转文件 | | logsDir | string | './logs' | 日志文件的保存目录 |

日志级别

支持的级别（按优先级排序）：

• fatal (映射至 error)
• error
• warn
• info
• debug
• trace (映射至 silly)

许可

MIT