日志与错误处理系统使用指南

概述

应用现在拥有完善的日志记录和错误处理系统，可以帮助你更好地追踪问题和调试。

日志系统 (logger.ts)

特性

• 分级日志: DEBUG, INFO, WARN, ERROR
• 自动文件持久化: 日志自动保存到 AppData/logs/app-YYYY-MM-DD.log
• 控制台输出: 同时输出到浏览器控制台
• 日志缓冲: 保留最近 1000 条日志在内存中
• 详细上下文: 支持附加数据和堆栈信息

使用方法

1. 创建模块日志器

import { createModuleLogger } from "@/utils/logger";

const logger = createModuleLogger("MyModule");

// 使用
logger.debug("调试信息", { data: "some data" });
logger.info("普通信息");
logger.warn("警告信息", { warning: "details" });
logger.error("错误信息", error, { context: "data" });

2. 日志级别

// DEBUG - 调试信息
logger.debug("函数被调用", { params: { id: 123 } });

// INFO - 一般信息
logger.info("配置加载成功", { profileCount: 5 });

// WARN - 警告
logger.warn("API密钥未配置", { profileId: "xxx" });

// ERROR - 错误
logger.error("请求失败", error, {
  url: "https://api.example.com",
  status: 500,
});

3. 设置日志级别

import { logger, LogLevel } from "@/utils/logger";

// 仅记录 INFO 及以上级别
logger.setLevel(LogLevel.INFO);

// 开发环境显示所有日志
if (import.meta.env.DEV) {
  logger.setLevel(LogLevel.DEBUG);
}

错误处理系统 (errorHandler.ts)

特性

• 统一错误处理: 标准化所有错误
• 自动用户提示: 根据错误级别显示相应提示
• 错误队列: 保留最近 100 个错误记录
• 友好错误消息: 自动翻译技术错误为用户可理解的消息
• 与日志系统集成: 错误自动记录到日志

使用方法

1. 创建模块错误处理器

import { createModuleErrorHandler } from "@/utils/errorHandler";

const errorHandler = createModuleErrorHandler("MyModule");

// 基础使用
try {
  // 可能出错的代码
  await riskyOperation();
} catch (error) {
  errorHandler.error(error, "操作失败，请重试");
}

2. 不同错误级别

// INFO - 信息性提示
errorHandler.info(error, "这是一条信息");

// WARN - 警告
errorHandler.warn(error, "配置可能有问题");

// ERROR - 错误（默认）
errorHandler.error(error, "操作失败");

// CRITICAL - 严重错误（不自动关闭提示）
errorHandler.critical(error, "系统遇到严重错误");

3. 异步函数包装

// 自动捕获异步错误
const result = await errorHandler.wrapAsync(
  async () => {
    return await fetchData();
  },
  {
    userMessage: "获取数据失败",
    context: { userId: 123 },
  }
);

// result 为 null 表示出错
if (result) {
  // 成功处理数据
}

4. 同步函数包装

const result = errorHandler.wrapSync(
  () => {
    return parseComplexData(data);
  },
  { userMessage: "数据解析失败" }
);

全局错误捕获

系统已在 main.ts 中配置全局错误捕获：

1. Vue 错误捕获

// 自动捕获 Vue 组件中未处理的错误
app.config.errorHandler = (err, instance, info) => {
  // 自动记录和处理
};

2. Promise 错误捕获

// 自动捕获未处理的 Promise rejection
window.addEventListener("unhandledrejection", (event) => {
  // 自动记录和处理
});

3. 全局 JavaScript 错误

// 自动捕获全局错误
window.addEventListener("error", (event) => {
  // 自动记录和处理
});

最佳实践

1. 在 Composables 中

import { createModuleLogger } from "@/utils/logger";
import { createModuleErrorHandler } from "@/utils/errorHandler";

const logger = createModuleLogger("MyComposable");
const errorHandler = createModuleErrorHandler("MyComposable");

export function useMyFeature() {
  const loadData = async () => {
    try {
      logger.info("开始加载数据");
      const data = await fetchData();
      logger.info("数据加载成功", { count: data.length });
      return data;
    } catch (error) {
      logger.error("数据加载失败", error);
      errorHandler.error(error, "无法加载数据，请重试");
      return [];
    }
  };

  return { loadData };
}

2. 在组件中

<script setup lang="ts">
import { createModuleLogger } from '@/utils/logger';
import { createModuleErrorHandler } from '@/utils/errorHandler';

const logger = createModuleLogger('MyComponent');
const errorHandler = createModuleErrorHandler('MyComponent');

const handleSubmit = async () => {
  try {
    logger.debug('提交表单', { formData });
    await submitForm(formData);
    logger.info('表单提交成功');
    ElMessage.success('保存成功');
  } catch (error) {
    errorHandler.error(error, '保存失败，请重试');
  }
};
</script>

3. 在 API 调用中

async function callApi() {
  const logger = createModuleLogger("ApiCall");

  logger.debug("发送API请求", { url, method });

  try {
    const response = await fetch(url, options);

    if (!response.ok) {
      const errorText = await response.text();
      logger.error("API请求失败", new Error(errorText), {
        status: response.status,
        url,
      });
      throw new Error(`请求失败 (${response.status})`);
    }

    logger.info("API请求成功", { url });
    return await response.json();
  } catch (error) {
    logger.error("API调用异常", error, { url });
    throw error;
  }
}

调试技巧

1. 查看日志文件

日志文件位于：AppData/aiohub/logs/app-YYYY-MM-DD.log

在 Windows 上通常是：

C:\Users\你的用户名\AppData\Roaming\com.mty.aiohub\logs\

2. 查看内存中的日志

import { logger } from "@/utils/logger";

// 获取所有日志
const logs = logger.getLogBuffer();
console.table(logs);

// 清空日志缓冲
logger.clearBuffer();

3. 查看错误队列

import { errorHandler } from "@/utils/errorHandler";

// 获取所有错误
const errors = errorHandler.getErrorQueue();
console.table(errors);

// 清空错误队列
errorHandler.clearErrorQueue();

4. 导出日志

import { logger } from "@/utils/logger";

// 导出日志到文件
await logger.exportLogs("/path/to/export.log");

常见问题

Q: 如何禁用某个模块的日志？

A: 设置更高的日志级别：

import { logger, LogLevel } from "@/utils/logger";

// 生产环境只记录错误
if (import.meta.env.PROD) {
  logger.setLevel(LogLevel.ERROR);
}

Q: 如何避免在控制台显示错误提示？

A: 使用 showToUser: false 选项：

errorHandler.handle(error, {
  showToUser: false,
  context: { silent: true },
});

Q: 如何自定义错误消息？

A: 使用 userMessage 参数：

errorHandler.error(error, "自定义的用户友好消息", {
  additionalContext: "data",
});

Q: 日志文件会占用大量空间吗？

A: 每天一个日志文件，建议定期清理旧日志。未来版本将添加自动清理功能。

迁移指南

从旧代码迁移

之前：

try {
  await operation();
} catch (error) {
  console.error("操作失败:", error);
  ElMessage.error("操作失败");
}

现在：

import { createModuleLogger } from "@/utils/logger";
import { createModuleErrorHandler } from "@/utils/errorHandler";

const logger = createModuleLogger("MyModule");
const errorHandler = createModuleErrorHandler("MyModule");

try {
  await operation();
} catch (error) {
  logger.error("操作失败", error);
  errorHandler.error(error, "操作失败");
}

或者更简洁：

const result = await errorHandler.wrapAsync(() => operation(), {
  userMessage: "操作失败",
});