workleap-logging

Workleap Logging (@workleap/logging)

适用于 Workleap 前端应用的结构化日志记录库。提供可组合、带样式的控制台日志记录，支持作用域、多种日志级别以及与遥测工具集成。

该库导出四种关键类型：Logger（基础接口）、RootLogger（扩展 Logger 并支持作用域）、BrowserConsoleLogger 和 CompositeLogger。

安装

pnpm add @workleap/logging

核心概念

日志记录器

• BrowserConsoleLogger：将日志输出到浏览器控制台，并支持样式
• CompositeLogger：将日志转发给多个底层日志记录器
• createCompositeLogger(verbose, loggers)：创建 CompositeLogger 的工厂函数。当 verbose 为 true 且未提供日志记录器时，会添加 BrowserConsoleLogger；否则仅使用你传入的日志记录器（空列表不会产生任何输出）。详情请参阅 references/api.md。

日志级别（从低到高）

1. debug - 用于开发的详细诊断信息
2. information - 应用的常规流程事件
3. warning - 需要关注的非关键问题
4. error - 导致功能无法完成的故障（在生产环境中会触发告警）
5. critical - 可能危及数据完整性的严重错误

作用域

作用域会在内存中缓冲日志条目，并在调用 .end() 时将其作为分组内容输出。这有助于在嘈杂的控制台输出中追踪多步骤操作。

const scope = logger.startScope("User signup");
scope.debug("Validating...");
scope.information("Signup complete");
scope.end();

Logger 接口未公开 startScope，因为作用域属于根级别功能。使用 Squide 的 useLogger() 时，返回类型为 Logger，因此请转换为 RootLogger 以访问作用域方法：

import { useLogger } from "@squide/firefly";
import type { RootLogger } from "@workleap/logging";

const logger = useLogger();
(logger as RootLogger).startScope("User signup");

链式片段

通过串联片段来构建复杂的日志条目。未调用终结日志级别方法（.debug()、.error() 等）的链不会产生任何输出，这是日志缺失最常见的原因。

logger
    .withText("Processing order")
    .withObject({ orderId: 123 })
    .withError(new Error("Failed"))
    .error();
// Output: [error] Processing order { orderId: 123 } Error: Failed

常见问题

1. 忘记调用终结日志方法：未调用 .debug()、.error() 等方法的链不会产生任何输出。
2. 未结束作用域：作用域内的条目会在内存中缓冲，只有调用 .end() 后才会刷新到控制台。若不调用该方法，日志会悄然丢失。
3. 将 warning 用于故障：故障应使用 error，warning 用于非关键问题。这一区分很重要，因为生产环境的告警和日志筛选依赖准确的严重性级别。
4. 记录敏感数据：日志条目可能出现在 LogRocket 会话回放和浏览器开发者工具中，因此包含凭据或个人身份信息（PII）会带来合规与安全风险。
5. 缺少错误上下文：未使用 withObject() 提供相关数据、未使用 withError() 提供异常时，错误日志就会缺少在生产环境中重现问题所需的信息。

参考指南

• references/api.md — 需要查看构造函数签名、完整方法列表（带样式的文本、换行、withObject、withError）、作用域生命周期 API 或 createCompositeLogger 详情时阅读。
• references/patterns.md — 从头设置日志记录器、与 LogRocket 集成、为功能或操作实现作用域日志记录，或审查日志记录代码的 PR 时阅读。