# log_storage_tool

**Repository Path**: dxm_code/log_storage_tool

## Basic Information

- **Project Name**: log_storage_tool
- **Description**: FlutterLog - Flutter 日志存储与拉取工具
一套完整的 Flutter 日志管理解决方案,包含日志缓存工具和 ADB 日志拉取脚本。
- **Primary Language**: Dart
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-23
- **Last Updated**: 2026-03-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LogStorageTool - 日志存储与管理工具

跨平台日志管理方案，支持 Android 原生 (Java) 和 Flutter (Dart) 双端，包含日志轮转归档、ADB 拉取脚本。

---

## 📦 项目组成

| 文件 | 说明 |
|------|------|
| `tools/LogStorageTool.java` | Android 原生端日志工具 |
| `tools/log_storage_tool.dart` | Flutter/Dart 端日志工具 |
| `tools/pull_log.bat` | 快速拉取当前日志脚本 |
| `tools/pull_app_files.bat` | 全量拉取应用文件脚本 |
| `test/log_storage_tool_test.dart` | Dart 端单元测试 (27 个用例) |

---

## ✨ 核心特性

| 特性 | 说明 |
|------|------|
| **日志轮转** | 单文件 5MB 上限，超出自动归档为 `log_YYYYMMDD_HHmmss.txt` |
| **归档管理** | 最多保留 10 个归档 + 1 个活跃文件，总计最大 **55MB** |
| **异步写入** | 队列缓冲 + 批量写入，不阻塞主线程 |
| **节流控制** | 3 秒最小写入间隔，减少 I/O |
| **双端一致** | Java 和 Dart 使用相同的文件名、目录、轮转策略 |
| **控制字符清理** | 自动过滤不可见字符，防止写入失败 |

### 存储结构

```
/storage/emulated/0/Android/data/<包名>/files/
└── log_s_files/
    ├── log_now.txt                  ← 当前活跃日志 (最大 5MB)
    ├── log_20260307_103000.txt      ← 归档文件 1
    ├── log_20260306_180000.txt      ← 归档文件 2
    └── ...                          ← 最多 10 个归档
```

---

## 🚀 快速开始

### Flutter 端

1. 将 `log_storage_tool.dart` 复制到项目中

2. 添加依赖:

```yaml
dependencies:
  path_provider: ^2.1.5
```

3. 使用:

```dart
import 'log_storage_tool.dart';

// 打印到控制台并写入文件
println('应用启动');

// 多参数拼接
println('用户:', userId, '操作:', action);

// 静默写入（不打印到控制台）
println('敏感操作记录', 'silent');

// Map 自动 JSON 序列化
println({'event': 'login', 'user': 'Alice'});

// 读取日志
String logs = await LogStorageTool.readLog();

// 清空所有日志（含归档）
await LogStorageTool.clear();
```

### Android 端

1. 将 `LogStorageTool.java` 复制到项目中，修改 `package` 为你的包名

2. 在 `Application.onCreate` 中初始化:

```java
LogStorageTool.init(this);
```

3. 使用:

```java
// 替代 Android Log
LogStorageTool.d("MyTag", "Debug message");
LogStorageTool.i("MyTag", "Info message");
LogStorageTool.w("MyTag", "Warning", exception);
LogStorageTool.e("MyTag", "Error message");

// 通用打印
LogStorageTool.println("自定义日志", data);

// 接收外部日志（如 Flutter 端传来的日志列表）
LogStorageTool.saveList(logList);

// 读取 / 清空
String log = LogStorageTool.readLog();
LogStorageTool.clearLog();

// 应用退出时
LogStorageTool.shutdown();
```

---

## 🔧 拉取工具

### pull_log.bat - 快速拉取当前日志

```cmd
:: 自动检测设备
pull_log.bat

:: 指定设备
pull_log.bat -s <设备ID>
```

脚本顶部配置区可修改包名和日志文件名:

```batch
set "PKG=com.example.app"
set "LOG_FILE=log_now.txt"
```

### pull_app_files.bat - 全量拉取应用文件

```cmd
pull_app_files.bat
```

交互式选择应用，支持多设备。脚本顶部配置区可自定义应用列表:

```batch
set "APP_1=com.example.app1|应用1"
set "APP_2=com.example.app2|应用2"
```

### 前置要求

- ADB 已安装并配置到环境变量
- 设备已开启 USB 调试并授权连接

---

## 📖 API 参考

### Dart - 全局函数

#### `println([v1, v2, v3, v4, v5])`

打印日志到控制台并写入文件，最多 5 个参数自动拼接。
- `v2 == "silent"` 时只写文件不打印
- `Map` 类型自动 JSON 序列化

#### `cleanBasicInvalidChars(String input)`

清除字符串中的控制字符 (`\x00-\x08`, `\x0B`, `\x0C`, `\x0E-\x1F`)。

### Dart - LogStorageTool 类

| 属性/方法 | 说明 |
|-----------|------|
| `write` | 是否启用文件写入 (默认 `true`) |
| `nowServerTime` | 注入服务器时间用于时间戳对齐 |
| `printAndWrite(info, [show])` | 底层打印写入方法 |
| `readLog()` | 读取当前活跃日志内容 |
| `clear()` | 清空所有日志（含归档文件） |

### Java - LogStorageTool 类

| 方法 | 说明 |
|------|------|
| `init(Context)` | 初始化（Application.onCreate 中调用） |
| `d/i/w/e(tag, msg)` | 各级别日志，兼容 Android Log API |
| `println(Object...)` | 通用打印 |
| `saveList(List)` | 异步保存外部日志列表 |
| `saveListSync(List)` | 同步保存外部日志列表 |
| `readLog()` | 读取当前日志 |
| `clearLog()` | 清空所有日志 |
| `flushImmediately()` | 异步刷出队列 |
| `flushNow()` | 同步阻塞刷出队列 |
| `shutdown()` | 关闭工具，释放资源 |
| `setEnableConsole(bool)` | 开关控制台输出 |
| `setEnableFile(bool)` | 开关文件写入 |

---

## 📊 参数配置

| 参数 | Java | Dart | 说明 |
|------|------|------|------|
| 单文件上限 | `MAX_FILE_SIZE` | `maxFileSize` | 5MB |
| 归档数量 | `MAX_ARCHIVE_COUNT` | `maxArchiveCount` | 10 |
| 活跃文件名 | `ACTIVE_LOG_NAME` | `activeLogName` | `log_now.txt` |
| 日志目录 | `LOG_DIR_NAME` | `_logDirName` | `log_s_files` |
| 写入间隔 | `writeInterval` | `_minInterval` | 3 秒 |
| 队列容量 | `MAX_QUEUE_SIZE` | — | 10000 条 (仅 Java) |

---

## 🧪 测试

```bash
flutter test test/log_storage_tool_test.dart
```

27 个测试用例覆盖: 控制字符清理、日志写入、文件轮转、归档清理、日志读取、清空、println 参数处理、时间格式化、目录创建。

---

## 📄 许可证

MIT License

---

**最后更新:** 2026-03-07
**版本:** 2.0.0