Files

tzdwindows 7 7badbb0d8e docs: 添加 Axis Innovators Box 框架完整 API 文档

- 新增浏览器模块技术文档，涵盖 BrowserCore、BrowserWindow 等核心组件
- 添加事件系统文档，包括 EventBus、GlobalEventBus 及各类事件定义
- 创建 LanguageManager 国际化管理器详细说明文档
- 新增 Log4j2OutputStream 标准输出重定向类文档
- 添加 Main 入口类启动流程与路由机制说明
- 创建 BrowserCreationCallback 回调接口使用指南
- 完善 AxisInnovatorsBox 主类架构与崩溃诊断系统文档

2026-01-03 08:46:19 +08:00

4.4 KiB

Raw Permalink Blame History

这是一个专门为 com.axis.innovators.box.Log4j2OutputStream 类编写的技术介绍文档。

Log4j2OutputStream 类技术文档

包路径: com.axis.innovators.box.Log4j2OutputStream
主要功能: 标准输出重定向与日志集成
作者: tzdwindows 7

1. 概述

Log4j2OutputStream 是一个高度定制化的 OutputStream 实现，旨在解决 Java 应用程序中标准输出 (System.out) 和标准错误 (System.err) 与日志框架（Log4j2）集成时的冲突问题。

传统的日志重定向往往会“吞掉”控制台输出，导致开发者在调试时无法实时看到控制台信息。该类通过多路输出机制，实现了在保持控制台原始输出的同时，将内容自动同步到 Log4j2 日志记录器中，并保留一份副本在内存中用于崩溃诊断。

2. 核心特性

三路并行输出 (Triple-Way Output): 任何写入此流的数据会同时流向：
1. 原始控制台流: 保证开发环境下的实时可见性。
2. Log4j2 Logger: 将普通的 print 语句转换为结构化的日志条目。
3. 内存缓冲区: 静态存储在 systemOutContent 和 systemErrContent 中，供系统在发生崩溃时提取诊断数据。
智能行缓冲 (Line-Buffered Logging): 为了避免日志碎片化，该流会累积字符直到遇到换行符 (\n) 或手动触发 flush() 时，才会将其作为一条完整的日志记录（INFO 或 ERROR 级别）发送给 Log4j2。
字符编码安全: 全程采用 StandardCharsets.UTF_8 处理，有效防止中文字符在重定向过程中出现乱码。
无缝集成: 提供静态方法一键重定向整个系统的标准流。

3. 工作原理

3.1 数据流向图

System.out.println("Hello")
      │
      ▼
Log4j2OutputStream.write()
      │
      ├───> 原始 PrintStream (控制台显示)
      ├───> 内存 ByteArrayOutputStream (诊断快照)
      └───> 内部 Buffer ───(遇到 \n)───> LogManager.getLogger().info()

3.2 级别映射

System.out 映射为 Log4j2 的 INFO 级别。
System.err 映射为 Log4j2 的 ERROR 级别。

4. API 说明

4.1 核心静态方法

方法	描述
`static void redirectSystemStreams()`	最常用的方法。调用后会立即劫持全局 `System.out` 和 `System.err`，并将其替换为封装后的 `Log4j2OutputStream`。
`static String getSystemOutContent()`	获取自程序启动（或上次清空）以来标准输出的所有文本内容。
`static String getSystemErrContent()`	获取自程序启动以来标准错误的所有文本内容。
`static void clearBuffers()`	重置内存中的静态缓冲区，释放内存。

4.2 构造函数

public Log4j2OutputStream(boolean isErrorStream, PrintStream originalStream)

isErrorStream: 指定该流是否作为错误流处理（影响日志级别）。
originalStream: 传入系统原始的打印流（如 System.out 在重定向前的副本），确保数据能回流到控制台。

5. 使用场景：崩溃诊断报告

该类与 AxisInnovatorsBox 的崩溃报告系统紧密配合。当程序发生未捕获异常时，AxisInnovatorsBox 会调用：

String systemOut = Log4j2OutputStream.systemOutContent.toString();
String systemErr = Log4j2OutputStream.systemErrContent.toString();
// ... 组合成完整的诊断报告

这确保了即使用户没有查看日志文件的习惯，程序也能在崩溃瞬间抓取到最后时刻的控制台输出，极大地方便了远程排查。

6. 使用示例

在程序启动的最早期（通常在 main 方法或初始化块中）调用：

public static void main(String[] args) {
    // 初始化并启动重定向
    Log4j2OutputStream.redirectSystemStreams();
    
    // 现在的 println 既会出现在控制台，也会进入 log4j2 配置文件定义的 Appender 中
    System.out.println("This is a test message.");
    System.err.println("This error will be logged as ERROR level.");
}

7. 注意事项

资源开销: 由于内存中保留了输出副本，如果程序产生极大量的控制台输出（如数 GB 的日志），应定期调用 clearBuffers() 以防止内存溢出。
线程安全: 该类依赖 ByteArrayOutputStream 的同步机制和 Log4j2 的线程安全保证。

文档生成时间: 2026-01-02

4.4 KiB Raw Permalink Blame History Unescape Escape