Blessing-log 库使用文档

简介

Blessing-log 是一个灵活的日志记录库，支持多种日志级别（如 DEBUG、INFO、WARN、ERROR、FATAL），并且允许用户自定义日志格式、输出流以及日志处理逻辑。该库还支持同步和异步日志写入，适用于各种应用场景。

安装

npm install @blessing-worker/blessing-log

快速开始

// 使用默认配置的 logger 实例
import { logger } from '@blessing-worker/blessing-log';
logger.info({
    message: "This is an info log",
    code: {
        file: "example.ts",
        stack: "some stack trace"
    }
});

说明

如果你想使用你自己的配置的logger实例,请看源码中index.ts的最后几行,像实例化默认logger实例那样去实例化你的日志对象

配置选项

Logger 的构造函数接受两个参数：

• defaultOption: LoggerOption - 默认的日志配置选项。
• levelLimit: number - 日志级别限制，低于此级别的日志将不会被记录。

LoggerOption 接口

export interface LoggerOption {
    streams?: Writable[]; // 输出流数组，至少需要一个
    writePre?: (context: LogContext, option: LoggerOption) => LogFunctionReturnType; // 写入前的钩子函数
    writeAfter?: (context: LogContext, option: LoggerOption) => void; // 写入后的钩子函数
    writeErrorHandle?: (err: Error) => void; // 错误处理函数
    formatter?: (context: LogContext) => string; // 日志格式化函数
    isAsync?: boolean; // 是否异步写入
}

默认配置

const blessingLoggerLevelLimit = 0;
const blessingWriteErrorHandler = (err: Error) => {
    console.error('Logger error:', err);
};
const blessingLoggerOption: LoggerOption = {
    streams: [process.stdout],
    writeErrorHandle: blessingWriteErrorHandler,
    isAsync: false
};
export const logger = new Logger(blessingLoggerOption, blessingLoggerLevelLimit);

日志级别

Logger 支持以下日志级别：

| 级别 | 值 | 描述 | |---|---|---| | DEBUG | 5 | 调试信息 | | INFO | 10 | 一般信息 | | WARN | 15 | 警告信息 | | ERROR | 20 | 错误信息 | | FATAL | 25 | 严重错误信息 |

你可以通过 setLevelLimit 方法设置日志级别限制，低于此级别的日志将不会被记录。

logger.setLevelLimit(LogLevel.INFO); // 只记录 INFO 及以上级别的日志

自定义日志函数

你可以通过 addLogFunction 方法添加自定义的日志函数：

logger.addLogFunction({
    name: 'customLog',
    body: (context: LogContext, option?: LoggerOption) => {
        const ctx: LogContext = {
            prefix: '🌟',
            level: chalk.green.bold('CUSTOM'),
            timestamp: new Date()
        };
        return { context: { ...ctx, ...context }, option };
    },
    level: 30 // 自定义日志级别
});

logger.customLog({
    message: "This is a custom log"
});

日志格式化

你可以通过 formatter 选项自定义日志的格式化方式。默认情况下，Logger 使用 JSON.stringify 来格式化日志。

const customFormatter = (context: LogContext) => {
    return `${context.timestamp} [${context.level}] ${context.message}`;
};

logger.setDefaultOption({
    formatter: customFormatter
});

同步与异步写入

Logger 支持同步和异步写入日志。你可以通过 isAsync 选项来控制：

logger.setDefaultOption({
    isAsync: true // 异步写入日志
});

错误处理

如果日志写入过程中发生错误，Logger 会调用 writeErrorHandle 函数来处理错误。

logger.setDefaultOption({
    writeErrorHandle: (err: Error) => {
        console.error('Custom error handler:', err);
    }
});

示例

以下是一个完整的示例，展示了如何使用 Logger 记录不同级别的日志：

import { logger } from './path-to-your-logger';

logger.debug({
    message: "This is a debug log",
    code: {
        file: "example.ts",
        stack: "some stack trace"
    }
});

logger.info({
    message: "This is an info log",
    code: {
        file: "example.ts",
        stack: "some stack trace"
    }
});

logger.warn({
    message: "This is a warn log",
    code: {
        file: "example.ts",
        stack: "some stack trace"
    }
});

logger.error({
    message: "This is an error log",
    code: {
        file: "example.ts",
        stack: "some stack trace"
    }
});

logger.fatal({
    message: "This is a fatal log",
    code: {
        file: "example.ts",
        stack: "some stack trace"
    }
});

总结

Logger 是一个功能强大且灵活的日志记录库，适用于各种应用场景。通过自定义日志级别、格式化函数和输出流，你可以轻松地将 Logger 集成到你的项目中，并根据需要调整日志记录行为。