功能说明
createLogger 生成一个输出行分隔 JSON 的轻量日志器,适合被日志采集器直接解析。每条日志包含时间戳、级别、消息以及通过 base 和 child 绑定的上下文;子日志器共享级别、写入函数和时钟,但拥有独立的上下文字段。级别从低到高为 debug、info、warn、error,低于当前阈值的日志会被直接丢弃。
序列化层专门处理 Error、BigInt、Date、Map、Set 和循环引用,避免因为某个字段不可序列化而导致整条日志丢失。即使序列化失败,也会退化为一条最小的错误日志。默认写入 process.stdout,也可以注入自定义 write 收集到缓冲区或转发到文件。
关键代码
子日志器通过展开父上下文生成新实例,字段合并后再覆盖时间戳、级别和消息,防止业务字段伪造关键字段:
const entry = {
...base,
...fields,
timestamp: now(),
level: entryLevel,
message: String(message),
};
toSerializable 使用 WeakSet 记录当前递归路径,检测到重复对象时输出 [Circular],并在回溯后移除标记,因此共享引用不会被误判为循环。
使用注意
日志字段中的 getter 可能抛错,序列化异常会被捕获并替换为一条错误日志,但原始字段内容会丢失,敏感信息不应依赖该机制脱敏。base 和 fields 只做浅合并,嵌套对象不会自动脱敏或截断;需要遵守隐私规范时应在上游过滤。Error 的 stack 会完整写入日志,生产环境可能暴露文件路径。
write 抛出的异常不会被捕获,会直接影响调用方,远程传输场景应自行包裹。日志器不负责限流、采样或异步刷新,高频日志应配合缓冲和批量写入。level 在创建时固定,子日志器不能单独调整;child 的绑定字段会覆盖父级同名字段。
验证方式
示例创建带 service 和 env 上下文的主日志器,再派生子日志器并记录 info、warn、error 三条日志。输出应为合法 JSON 行,error 条目包含名称、消息和堆栈,debug 条目被过滤。随后记录一个自引用对象和 BigInt,检查 [Circular] 与字符串形式的 BigInt 均已正确输出。可以把每行交给 JSON.parse 验证格式。