mstf-kit/docs/logger.md

一个现代化的 JavaScript/TypeScript 工具库，提供了丰富的常用工具函数

# Logger 使用指南

## 概述

`Logger` 是一个统一的日志工具类，提供可配置的日志输出功能。支持多种日志级别、时间戳、自定义前缀等特性。

## 主要特性

- ✅ 多种日志级别：NONE、ERROR、WARN、INFO、DEBUG
- ✅ 可配置的日志前缀
- ✅ 可选的时间戳显示
- ✅ 支持启用/禁用日志
- ✅ 支持自定义日志处理函数
- ✅ 支持创建子 Logger
- ✅ 提供分组、表格、计时等高级功能
- ✅ TypeScript 完整类型支持

## 基本使用

### 创建 Logger

```typescript
import { createLogger, LogLevel } from 'mstf-kit';

// 创建一个基本的 Logger
const logger = createLogger({
  enabled: true,
  prefix: '[MyApp]',
  level: LogLevel.INFO
});

// 输出日志
logger.log('应用启动');
logger.info('这是一条信息');
logger.warn('这是一条警告');
logger.error('这是一条错误');
logger.debug('这是一条调试信息'); // 不会输出，因为级别是 INFO
```

### 日志级别

```typescript
import { LogLevel } from 'mstf-kit';

// 使用枚举
const logger1 = createLogger({
  level: LogLevel.DEBUG  // 输出所有日志
});

// 使用字符串
const logger2 = createLogger({
  level: 'debug'  // 等同于 LogLevel.DEBUG
});

// 可用的日志级别（从低到高）：
// - LogLevel.NONE / 'none'    - 不输出任何日志
// - LogLevel.ERROR / 'error'  - 只输出错误
// - LogLevel.WARN / 'warn'    - 输出警告和错误
// - LogLevel.INFO / 'info'    - 输出信息、警告和错误（默认）
// - LogLevel.DEBUG / 'debug'  - 输出所有日志
```

### 启用时间戳

```typescript
const logger = createLogger({
  enabled: true,
  prefix: '[MyApp]',
  showTimestamp: true
});

logger.log('带时间戳的日志');
// 输出: [2024-03-10T12:34:56.789Z] [MyApp] 带时间戳的日志
```

### 动态控制

```typescript
const logger = createLogger({
  enabled: true,
  prefix: '[MyApp]'
});

// 禁用日志
logger.disable();
logger.log('这条不会输出');

// 启用日志
logger.enable();
logger.log('这条会输出');

// 修改日志级别
logger.setLevel(LogLevel.ERROR);
logger.info('这条不会输出'); // INFO < ERROR
logger.error('这条会输出');

// 修改前缀
logger.setPrefix('[NewPrefix]');
logger.log('新前缀的日志');
```

## 高级功能

### 创建子 Logger

```typescript
const mainLogger = createLogger({
  enabled: true,
  prefix: '[App]',
  level: LogLevel.DEBUG
});

// 创建子 Logger，继承父 Logger 的配置
const authLogger = mainLogger.createChild('Auth');
const dbLogger = mainLogger.createChild('Database');

authLogger.log('用户登录');  // [App:Auth] 用户登录
dbLogger.log('连接数据库');  // [App:Database] 连接数据库
```

### 分组日志

```typescript
const logger = createLogger({
  enabled: true,
  prefix: '[MyApp]'
});

logger.group('用户操作');
logger.log('步骤1: 验证用户');
logger.log('步骤2: 加载数据');
logger.log('步骤3: 渲染界面');
logger.groupEnd();

// 折叠的分组
logger.groupCollapsed('详细信息');
logger.log('这些信息默认折叠');
logger.groupEnd();
```

### 表格输出

```typescript
const logger = createLogger({
  enabled: true,
  prefix: '[MyApp]'
});

const users = [
  { id: 1, name: 'Alice', age: 25 },
  { id: 2, name: 'Bob', age: 30 },
  { id: 3, name: 'Charlie', age: 35 }
];

logger.table(users);
```

### 计时功能

```typescript
const logger = createLogger({
  enabled: true,
  prefix: '[MyApp]',
  level: LogLevel.DEBUG
});

logger.time('数据加载');

// 执行一些操作
await loadData();

logger.timeEnd('数据加载');
// 输出: [MyApp] 数据加载: 123.456ms
```

### 对象详细信息

```typescript
const logger = createLogger({
  enabled: true,
  prefix: '[MyApp]',
  level: LogLevel.DEBUG
});

const complexObject = {
  user: { id: 1, name: 'Alice' },
  settings: { theme: 'dark', lang: 'zh' }
};

logger.dir(complexObject);
```

### 自定义日志处理

```typescript
const logger = createLogger({
  enabled: true,
  prefix: '[MyApp]',
  customHandler: (level, prefix, ...args) => {
    // 自定义处理逻辑，例如发送到服务器
    const message = args.join(' ');
    
    // 发送到日志服务
    sendToLogServer({
      level,
      prefix,
      message,
      timestamp: new Date().toISOString()
    });
    
    // 同时输出到控制台
    console.log(`${prefix} [${level}]`, ...args);
  }
});

logger.log('这条日志会被自定义处理');
```

## 实际应用场景

### 场景1：在音频处理中使用

```typescript
import { createLogger, LogLevel, processNonStreamAudio } from 'mstf-kit';

// 创建音频处理专用的 Logger
const audioLogger = createLogger({
  enabled: true,
  prefix: '[AudioProcessor]',
  level: LogLevel.DEBUG,
  showTimestamp: true
});

async function processAudio(response: any) {
  audioLogger.time('音频处理');
  
  try {
    audioLogger.log('开始处理音频数据');
    
    const result = await processNonStreamAudio(response, {
      audioField: 'data.audio',
      dataType: 'base64',
      debug: true  // 内部也会使用 Logger
    });
    
    audioLogger.log('音频处理成功', {
      size: result.size,
      type: result.mimeType
    });
    
    audioLogger.timeEnd('音频处理');
    
    return result;
    
  } catch (error) {
    audioLogger.error('音频处理失败:', error);
    throw error;
  }
}
```

### 场景2：模块化日志管理

```typescript
import { createLogger, LogLevel } from 'mstf-kit';

// 创建应用主 Logger
const appLogger = createLogger({
  enabled: true,
  prefix: '[App]',
  level: process.env.NODE_ENV === 'development' ? LogLevel.DEBUG : LogLevel.INFO
});

// 为不同模块创建子 Logger
export const authLogger = appLogger.createChild('Auth');
export const apiLogger = appLogger.createChild('API');
export const uiLogger = appLogger.createChild('UI');

// 在不同模块中使用
// auth.ts
import { authLogger } from './logger';

export function login(username: string) {
  authLogger.log('用户登录:', username);
  // ...
}

// api.ts
import { apiLogger } from './logger';

export async function fetchData(url: string) {
  apiLogger.time(`请求: ${url}`);
  const response = await fetch(url);
  apiLogger.timeEnd(`请求: ${url}`);
  return response;
}
```

### 场景3：开发/生产环境切换

```typescript
import { createLogger, LogLevel } from 'mstf-kit';

// 根据环境变量配置日志
const isDevelopment = process.env.NODE_ENV === 'development';

const logger = createLogger({
  enabled: isDevelopment,  // 生产环境禁用日志
  prefix: '[MyApp]',
  level: isDevelopment ? LogLevel.DEBUG : LogLevel.ERROR,
  showTimestamp: isDevelopment
});

// 开发环境会输出，生产环境不会
logger.debug('调试信息');
logger.info('普通信息');

// 生产环境也会输出错误
logger.error('错误信息');
```

### 场景4：性能监控

```typescript
import { createLogger, LogLevel } from 'mstf-kit';

const perfLogger = createLogger({
  enabled: true,
  prefix: '[Performance]',
  level: LogLevel.DEBUG
});

class PerformanceMonitor {
  private timers = new Map<string, number>();
  
  start(label: string): void {
    this.timers.set(label, performance.now());
    perfLogger.debug(`开始计时: ${label}`);
  }
  
  end(label: string): number {
    const startTime = this.timers.get(label);
    if (!startTime) {
      perfLogger.warn(`未找到计时器: ${label}`);
      return 0;
    }
    
    const duration = performance.now() - startTime;
    this.timers.delete(label);
    
    perfLogger.log(`${label}: ${duration.toFixed(2)}ms`);
    
    // 如果耗时过长，输出警告
    if (duration > 1000) {
      perfLogger.warn(`${label} 耗时过长: ${duration.toFixed(2)}ms`);
    }
    
    return duration;
  }
  
  report(): void {
    perfLogger.group('性能报告');
    perfLogger.log(`活跃计时器数量: ${this.timers.size}`);
    
    if (this.timers.size > 0) {
      const timers = Array.from(this.timers.entries()).map(([label, startTime]) => ({
        label,
        elapsed: `${(performance.now() - startTime).toFixed(2)}ms`
      }));
      perfLogger.table(timers);
    }
    
    perfLogger.groupEnd();
  }
}

// 使用
const monitor = new PerformanceMonitor();

monitor.start('数据加载');
await loadData();
monitor.end('数据加载');

monitor.start('渲染界面');
await renderUI();
monitor.end('渲染界面');

monitor.report();
```

### 场景5：错误追踪

```typescript
import { createLogger, LogLevel } from 'mstf-kit';

const errorLogger = createLogger({
  enabled: true,
  prefix: '[ErrorTracker]',
  level: LogLevel.ERROR,
  showTimestamp: true,
  customHandler: (level, prefix, ...args) => {
    // 输出到控制台
    console.error(prefix, ...args);
    
    // 发送到错误追踪服务
    if (level === 'ERROR') {
      sendToErrorTracker({
        message: args.join(' '),
        timestamp: new Date().toISOString(),
        userAgent: navigator.userAgent,
        url: window.location.href
      });
    }
  }
});

// 全局错误处理
window.addEventListener('error', (event) => {
  errorLogger.error('全局错误:', {
    message: event.message,
    filename: event.filename,
    lineno: event.lineno,
    colno: event.colno
  });
});

// Promise 错误处理
window.addEventListener('unhandledrejection', (event) => {
  errorLogger.error('未处理的 Promise 拒绝:', event.reason);
});

// 手动记录错误
try {
  riskyOperation();
} catch (error) {
  errorLogger.error('操作失败:', error);
}
```

### 场景6：调试复杂流程

```typescript
import { createLogger, LogLevel } from 'mstf-kit';

const workflowLogger = createLogger({
  enabled: true,
  prefix: '[Workflow]',
  level: LogLevel.DEBUG,
  showTimestamp: true
});

async function complexWorkflow(data: any) {
  workflowLogger.group('开始复杂工作流');
  
  try {
    // 步骤1
    workflowLogger.log('步骤1: 验证数据');
    workflowLogger.dir(data);
    const validatedData = await validateData(data);
    workflowLogger.log('✓ 数据验证通过');
    
    // 步骤2
    workflowLogger.log('步骤2: 处理数据');
    workflowLogger.time('数据处理');
    const processedData = await processData(validatedData);
    workflowLogger.timeEnd('数据处理');
    workflowLogger.log('✓ 数据处理完成');
    
    // 步骤3
    workflowLogger.log('步骤3: 保存结果');
    const result = await saveResult(processedData);
    workflowLogger.log('✓ 结果保存成功');
    
    workflowLogger.log('工作流完成', { resultId: result.id });
    
    return result;
    
  } catch (error) {
    workflowLogger.error('工作流失败:', error);
    throw error;
    
  } finally {
    workflowLogger.groupEnd();
  }
}
```

## API 参考

### Logger 类

```typescript
class Logger {
  constructor(options?: LoggerOptions);
  
  // 基本日志方法
  debug(...args: any[]): void;
  log(...args: any[]): void;
  info(...args: any[]): void;
  warn(...args: any[]): void;
  error(...args: any[]): void;
  
  // 分组方法
  group(label: string): void;
  groupCollapsed(label: string): void;
  groupEnd(): void;
  
  // 高级方法
  table(data: any): void;
  dir(obj: any): void;
  time(label: string): void;
  timeEnd(label: string): void;
  
  // 控制方法
  enable(): void;
  disable(): void;
  setLevel(level: LogLevel | string): void;
  setPrefix(prefix: string): void;
  
  // 查询方法
  isEnabled(): boolean;
  getLevel(): LogLevel;
  
  // 创建子 Logger
  createChild(subPrefix: string): Logger;
}
```

### LoggerOptions

```typescript
interface LoggerOptions {
  enabled?: boolean;        // 是否启用日志，默认 true
  prefix?: string;          // 日志前缀，默认 '[Logger]'
  level?: LogLevel | string; // 日志级别，默认 LogLevel.INFO
  showTimestamp?: boolean;  // 是否显示时间戳，默认 false
  customHandler?: (level: string, prefix: string, ...args: any[]) => void;
}
```

### LogLevel 枚举

```typescript
enum LogLevel {
  NONE = 0,   // 不输出任何日志
  ERROR = 1,  // 只输出错误
  WARN = 2,   // 输出警告和错误
  INFO = 3,   // 输出信息、警告和错误
  DEBUG = 4   // 输出所有日志
}
```

### 工具函数

```typescript
// 创建 Logger 实例
function createLogger(options?: LoggerOptions): Logger;

// 默认的全局 Logger（禁用状态）
const defaultLogger: Logger;
```

## 最佳实践

1. **为不同模块创建独立的 Logger**
   ```typescript
   const authLogger = createLogger({ prefix: '[Auth]' });
   const apiLogger = createLogger({ prefix: '[API]' });
   ```

2. **使用子 Logger 管理层级关系**
   ```typescript
   const appLogger = createLogger({ prefix: '[App]' });
   const moduleLogger = appLogger.createChild('Module');
   ```

3. **根据环境配置日志级别**
   ```typescript
   const level = process.env.NODE_ENV === 'production' 
     ? LogLevel.ERROR 
     : LogLevel.DEBUG;
   ```

4. **使用计时功能监控性能**
   ```typescript
   logger.time('操作');
   await doSomething();
   logger.timeEnd('操作');
   ```

5. **在生产环境禁用或限制日志**
   ```typescript
   const logger = createLogger({
     enabled: process.env.NODE_ENV !== 'production',
     level: LogLevel.ERROR
   });
   ```

## 总结

`Logger` 提供了一个统一、灵活、功能丰富的日志解决方案。通过合理使用日志级别、前缀和分组功能，可以有效地管理应用的日志输出，提高开发和调试效率。