# 日志系统

## 概述

本插件实现了一个功能完善的日志系统，支持同时输出到控制台和文件，便于调试和问题追踪。

## 功能特性

### 1. 多级日志级别

支持四种日志级别，可按需过滤：

| 级别 | 值 | 描述 |
|------|-----|------|
| DEBUG | DEBUG | 调试信息，最详细的日志 |
| INFO | INFO | 一般信息，记录正常流程 |
| WARN | WARN | 警告信息，记录潜在问题 |
| ERROR | ERROR | 错误信息，记录异常和错误 |

### 2. 双输出机制

日志同时输出到：

- **控制台**: 实时查看，颜色区分
- **文件**: 持久化存储，便于事后分析

### 3. 智能日志文件路径

日志文件自动存储在 Joplin 日志目录中：

- **桌面端**: `~/.config/joplin/logs/joplin-plugin-typora-like-editor.log` (Linux)
- **移动端**: 插件数据目录下的 `logs/` 文件夹

每次插件启动时会清空旧日志文件。

### 4. 丰富的日志方法

提供多种便捷的日志记录方法：

```typescript
logger.debug(message, ...args);        // 调试日志
logger.info(message, ...args);         // 信息日志
logger.warn(message, ...args);         // 警告日志
logger.error(message, ...args);        // 错误日志
logger.logObject(label, obj);          // 记录对象详细信息
logger.logFunctionStart(name, ...args); // 记录函数调用开始
logger.logFunctionEnd(name, result);   // 记录函数调用结束
logger.logError(error, context);       // 记录错误堆栈
```

## 日志格式

日志采用统一的格式，便于解析：

```
[时间戳] [级别] [插件名] 消息内容 附加参数
```

示例：

```
[2026-02-03T10:30:45.123Z] [INFO] [joplin-plugin-typora-like-editor] Typora-like Editor Plugin started!
[2026-02-03T10:30:45.125Z] [DEBUG] [joplin-plugin-typora-like-editor] 日志文件路径: /home/user/.config/joplin/logs/joplin-plugin-typora-like-editor.log
[2026-02-03T10:30:50.234Z] [DEBUG] [joplin-plugin-typora-like-editor] [函数调用] onInit 开始 { destPath: '/home/user/export/test.md' }
```

## 使用示例

### 基本使用

```typescript
import { getLogger, LogLevel } from "./logger";

// 创建日志记录器
const logger = getLogger("my-plugin", {
  level: LogLevel.DEBUG,
  consoleEnabled: true,
  fileEnabled: true,
});

// 初始化（在插件启动时调用）
await logger.initialize();

// 记录不同级别的日志
logger.debug("这是调试信息");
logger.info("这是普通信息");
logger.warn("这是警告信息");
logger.error("这是错误信息");
```

### 记录对象

```typescript
const noteData = { id: "123", title: "测试笔记", body: "内容" };
logger.logObject("笔记数据", noteData);
```

### 记录函数调用

```typescript
async function processNote(noteId: string) {
  logger.logFunctionStart("processNote", { noteId });

  try {
    const note = await getNote(noteId);
    const result = transformNote(note);

    logger.logFunctionEnd("processNote", result);
    return result;
  } catch (error) {
    logger.logError(error, "处理笔记失败");
    throw error;
  }
}
```

### 记录错误

```typescript
try {
  await riskyOperation();
} catch (error) {
  logger.logError(error, "执行操作时发生错误");
}
```

## 在插件中的应用

本插件在以下场景中使用日志：

| 场景 | 日志级别 | 说明 |
|------|----------|------|
| 插件启动 | INFO | 记录启动事件和日志文件路径 |
| 导出初始化 | INFO | 记录缓存清空 |
| 笔记处理 | DEBUG | 记录笔记基础信息、完整属性、处理后内容 |
| YAML处理 | INFO | 记录YAML前沿处理状态 |
| 资源处理 | DEBUG | 记录资源路径计算、映射记录 |
| 资源复制 | INFO | 记录复制操作 |
| 导出完成 | INFO | 记录导出结果统计 |
| 错误处理 | ERROR | 记录异常堆栈信息 |

## 配置选项

```typescript
interface LoggerConfig {
  level: LogLevel;          // 日志级别
  consoleEnabled: boolean;  // 是否启用控制台输出
  fileEnabled: boolean;     // 是否启用文件输出
  logDir?: string;          // 自定义日志目录（可选）
}
```

## 获取日志文件路径

在插件运行时，可以通过以下方式获取日志文件路径：

```typescript
const logFilePath = logger.getLogFilePath();
logger.info(`日志文件路径: ${logFilePath}`);
```

## 最佳实践

1. **合理使用日志级别**
   - DEBUG: 详细的调试信息，仅在开发时使用
   - INFO: 记录重要的业务流程节点
   - WARN: 记录可恢复的异常情况
   - ERROR: 记录需要关注的错误

2. **函数调用追踪**
   - 使用 `logFunctionStart` 和 `logFunctionEnd` 追踪关键函数的执行
   - 便于性能分析和调用链追踪

3. **错误处理**
   - 使用 `logError` 记录完整的错误堆栈
   - 添加上下文信息便于定位问题

4. **对象序列化**
   - 使用 `logObject` 记录复杂对象
   - 自动处理 JSON 序列化

## 日志文件管理

- 每次插件启动时，日志文件会被清空
- 日志文件命名格式：`{插件名}.log`
- 日志文件位于 Joplin 日志目录，与 Joplin 自身日志同目录
- 长期运行可能产生较大日志文件，建议定期清理

## 故障排查

### 日志文件未生成

检查以下项：
1. 确认 `fileEnabled` 配置为 `true`
2. 检查 Joplin 日志目录是否有写入权限
3. 查看 `getLogFilePath()` 返回的路径是否正确

### 日志未显示

检查以下项：
1. 确认 `consoleEnabled` 配置为 `true`
2. 检查日志级别设置，DEBUG 级别会被 INFO 过滤
3. 确认 `initialize()` 已被调用