@lewinblog/logger-core

一个轻量的日志核心库，设计重点是两件事：

• Logger 负责定义“如何产生日志”
• LogMiddleware 负责定义“日志如何被处理与输出”

核心接口

Logger

Logger 是调用侧使用的统一入口，提供 debug、info、warn、error 四个方法。

import { ConsoleWriter, DefaultLogger, type Logger } from '@lewinblog/logger-core';

const logger: Logger = new DefaultLogger(new ConsoleWriter());
logger.use(new FooWriter()); // 也可以链式追加中间件
logger.info('app.boot', 'started', { env: 'prod' });
logger.error('app.api', new Error('request failed'), { requestId: 'req-1' });

约定说明：

• prefix 用来标识日志来源，建议按模块或场景命名，例如 app.boot、user.login
• msg 是给人直接阅读的消息文本
• extra 是结构化上下文，供中间件做过滤、增强或自定义输出
• error 接收 unknown，这样可以兼容任意异常值，而不强制依赖特定错误类型

LoggerMiddleware

LoggerMiddleware 是日志处理链上的最小扩展单位。每条日志都会按顺序经过中间件的 write 方法。

import { ConsoleWriter, DefaultLogger, type LogEntry, type LoggerMiddleware } from '@lewinblog/logger-core';

class SkipDebugMiddleware implements LoggerMiddleware {
  write(entry: LogEntry): LogEntry | null {
    if (entry.level === 'DEBUG') {
      return null;
    }
    return entry;
  }
}

// 中间件即可作为构造参数传入，也可用 .use() 链式追加
const logger = new DefaultLogger(new SkipDebugMiddleware(), new ConsoleWriter());
// 或：
const logger2 = new DefaultLogger().use(new SkipDebugMiddleware()).use(new ConsoleWriter());

返回约定：

• 返回 entry 或修改后的新对象：继续传给下一个中间件
• 返回 null：终止整条链路，后续中间件不会再执行

设计原理

这个包采用“输入接口 + 中间件管道”的设计：

• Logger 只负责表达日志意图，不关心最终输出到哪里
• LogMiddleware 负责过滤、补充、格式化、转发等处理细节
• LogBuilder 负责把两者串起来，让日志沿着一条可组合的链路流动

这样做的结果是：

• 调用侧 API 很稳定
• 输出策略可以自由组合
• 过滤、格式化、落地控制台或其他目标时不需要改动业务调用代码

内置实现

当前包内置：

• DefaultLogger：把 Logger 调用转换成 LogEntry 并按顺序执行中间件链；支持构造时直接传入中间件
• ConsoleWriter：将日志格式化后输出到控制台；extra 以独立对象参数输出，在开发者工具中可展开查看
• getExceptionExtra / buildErrorMessage：辅助处理错误日志的结构化上下文与文本拼装