Codex
128 lines
5.8 KiB
Markdown
128 lines
5.8 KiB
Markdown
# 新增功能模块 / 模块重构
|
||
|
||
> 适用场景：新增模块、重大模块重构、核心架构能力演进。
|
||
> 不适用场景：小接口或轻量功能变更，请使用“功能变更”模板。
|
||
|
||
## 基本信息
|
||
|
||
- 模块 ID：Module-20260109-0001
|
||
- 模块名称: SxLog 轻量日志系统
|
||
- 状态：已完成（历史记录；本次仅归档，未重新验证）
|
||
- 类型：新增模块
|
||
- 所属系统 / 子系统: StellarX / Logging / Diagnostics
|
||
- 版本 / 分支: v3.0.0 / master
|
||
- 环境: Windows x64 / Visual Studio 2022 / Debug、Release / 控制台模式
|
||
- 负责人: Ysm-04（历史实现）
|
||
|
||
## 背景与目标
|
||
|
||
- 背景: Canvas、TabControl、Table 以及快照重绘链路逐渐复杂，仅依靠断点难以还原事件、重绘和状态变化顺序。
|
||
- 当前痛点:
|
||
- 缺少统一的日志级别、Tag 过滤和输出渠道。
|
||
- 分散日志难以控制噪声，也难以保存为可回放证据。
|
||
- 协作和对外输出需要中英文文本选择能力。
|
||
- 目标:
|
||
- 提供统一日志入口和宏封装。
|
||
- 支持级别控制、Tag 白名单/黑名单、控制台输出、文件输出和按大小滚动。
|
||
- 提供 `SX_T` / `SxT` 双语文本选择以及作用域耗时记录。
|
||
- 非目标：[可选]
|
||
- 不负责字符编码转换。
|
||
- 不依赖 WinAPI 调试输出通道，不引入第三方日志库。
|
||
- 不保证高频同步 I/O 场景下无性能影响。
|
||
|
||
## 模块边界
|
||
|
||
- 职责:
|
||
- `SxLogger` 负责配置、过滤、格式化与 Sink 分发。
|
||
- `ConsoleSink`、`FileSink` 负责具体输出。
|
||
- `SxLogLine` 通过 RAII 完成流式拼接和行提交。
|
||
- `SxLogScope` 记录作用域耗时。
|
||
- 不负责什么:
|
||
- 不负责日志采集服务、网络上报、结构化查询或跨进程聚合。
|
||
- 不对业务敏感信息进行脱敏。
|
||
- 外部依赖:
|
||
- C++ 标准库的流、文件、互斥量、原子变量和时间工具。
|
||
- `setGBK()` 面向 Windows 控制台环境。
|
||
- 对外能力 / API:
|
||
- `SxLogger::Get()`、`setMinLevel()`、`setTagFilter()`、`clearTagFilter()`。
|
||
- `enableConsole()`、`enableFile()`、`disableFile()`。
|
||
- `setLanguage()`、`setGBK()`。
|
||
- `SX_LOG_TRACE`、`SX_LOGD/I/W/E/F`、`SX_TRACE_SCOPE`、`SX_T` / `SxT`。
|
||
- 关键数据 / 状态:
|
||
- `SxLogConfig` 保存级别、格式、Tag 策略以及文件配置。
|
||
- Logger 单例持有配置和 Sink；语言选择使用原子状态。
|
||
|
||
## 设计说明
|
||
|
||
- 核心流程:
|
||
1. 日志宏先调用 `shouldLog()` 判断级别、Tag 和可用 Sink。
|
||
2. 命中条件时构造 `SxLogLine` 并进行流式拼接。
|
||
3. `SxLogLine` 析构时提交完整日志行。
|
||
4. `SxLogger::logLine()` 在互斥保护下格式化并分发给控制台和文件 Sink。
|
||
- 关键对象 / 类关系:
|
||
- `SxLogger`：中心配置与分发器。
|
||
- `ILogSink`：输出目标抽象。
|
||
- `ConsoleSink` / `FileSink`：具体输出实现。
|
||
- `SxLogLine` / `SxLogScope`：调用端 RAII 辅助对象。
|
||
- 生命周期:
|
||
- Logger 为进程内单例；Sink 随配置启用或关闭。
|
||
- 日志行对象只在命中过滤条件时短暂存在，并在析构时提交。
|
||
- 事件 / 渲染 / 数据流：[按模块类型填写]
|
||
- 调用点 -> 宏短路 -> 日志行拼接 -> Logger 过滤/格式化 -> Sink 输出。
|
||
- 关键不变量:
|
||
- `shouldLog()` 返回 false 时不应构造日志行或执行字符串拼接。
|
||
- 单条日志必须作为整体写出，不能被其他线程插入破坏。
|
||
- 语言切换只选择文本，不进行编码转换。
|
||
- 未启用任何 Sink 时应直接短路。
|
||
- 降级 / 回退策略：[可选]
|
||
- 将最低级别设为 Off，或关闭控制台和文件 Sink。
|
||
- 必要时通过编译期开关关闭日志宏。
|
||
|
||
## 实现与影响
|
||
|
||
- 关键实现点:
|
||
- Tag 过滤使用适合少量 Tag 的线性查找。
|
||
- 文件输出支持追加和按字节阈值滚动。
|
||
- 输出阶段使用互斥量保证行级串行；语言状态使用原子变量。
|
||
- 涉及文件 / 类 / 函数:
|
||
- 历史路径：`include/StellarX/SxLog.h`
|
||
- 历史路径：`src/SxLog.cpp`
|
||
- `SxLogger`、`SxLogConfig`、`ILogSink`、`ConsoleSink`、`FileSink`、`SxLogLine`、`SxLogScope`
|
||
- 兼容性影响:
|
||
- 新增独立模块，不改变既有控件公共 API；调用方可选择是否接入。
|
||
- 性能影响:
|
||
- 未命中过滤条件时由宏短路降低开销。
|
||
- 命中时存在格式化、互斥和 I/O 成本；高频 Trace 输出可能成为瓶颈并快速增大日志文件。
|
||
- 风险点:
|
||
- 文件权限、文件占用或滚动重命名失败可能影响持续写入。
|
||
- 控制台代码页差异可能导致中文显示不一致。
|
||
- 日志内容如果包含敏感数据，需要由调用方自行控制。
|
||
|
||
## 测试与验证
|
||
|
||
- 测试范围:
|
||
- 日志级别、Tag 白名单/黑名单、控制台和文件输出、文件滚动、语言切换、不可写路径。
|
||
- 验证步骤:
|
||
|
||
1. 启用控制台并依次输出不同级别，检查格式、级别和语言文本。
|
||
2. 启用文件输出，验证追加写、Tag 过滤以及不可写路径的返回值。
|
||
3. 使用较小的滚动阈值持续输出，检查旧文件重命名和新文件续写。
|
||
|
||
- 验证结果:
|
||
- PDF 给出了上述测试方案，但“验证证据”仍是待填占位内容，没有附带日志、截图或性能数据。
|
||
- 本次只确认模块源码、公共接口、提交和发布记录存在，未重新执行运行时测试。
|
||
- 已知限制 / 遗留问题：[可选]
|
||
- 同步互斥和文件 I/O 不适合无约束的高频热路径。
|
||
- `setGBK()` 只调整终端解释输出的方式，不进行字符串编码转换。
|
||
|
||
## 落地信息
|
||
|
||
- 关联功能变更 ID：[可选]
|
||
- 关联 BUG / Fix：[可选]
|
||
- Commit: `5cb59b36525cde93de83313551296c6458694110`
|
||
- PR：[可选]
|
||
- 发布版本：[可选] v3.0.0
|
||
- 相关文档：[可选]
|
||
- `StellarX功能_模块变更.pdf` 第 24-28 页。
|
||
- 历史 `CHANGELOG.md` 的 v3.0.0 条目。
|