日志系统使用文档

目录

1. 简介
2. 快速开始
3. 安装与引入
4. 核心概念
   • LogCategory
   • LogCategoryGroup
   • LogLevel
5. 基本用法
   • 创建分类
   • 启用/禁用分类
   • 日志输出
   • 日志分组
6. 高级用法
   • 对象调用方式
   • 原生调用方式
   • 批量操作
7. 配置说明
8. 示例代码
9. 最佳实践
10. 注意事项
11. 常见问题 (FAQ)

简介

对原生浏览器 console 扩展，实现 分类化 与 分组化 的日志管理能力，在前端复杂场景中可实现更可控、更清晰的日志输出。

支持功能：

• 分类（Category）与分组（Group）管理
• 动态启用/禁用日志输出
• 支持多参数与对象参数形式
• 分组日志耗时统计
• 与原生 console.log 调用方式兼容

快速开始

import { LogCategory, LogCategoryGroup } from '@oiiiai/category-logger';

const logCategory = new LogCategory(['API', 'INPUT', 'EFFECT']);
const group = new LogCategoryGroup();
logCategory.bindCategoryGroup(group);

logCategory.enableAll();
group.enableAll();

// 普通日志
logCategory.info('流程开始', 'API');

// 分组日志
logCategory.group('表单操作', ['INPUT'], () => {
  logCategory.debug('输入用户名', 'INPUT', { username: 'Alice' });
  logCategory.info('提交表单', 'API');
});

输出示例：

[INFO] [API] 流程开始
[DEBUG] [INPUT] 输入用户名 { username: "Alice" }
[INFO] [API] 提交表单
分组 "[INPUT] 表单操作" 耗时: 23ms

安装与引入

如果在项目中使用 npm 安装：

npm install @oiiiai/category-logger

引入模块：

import { LogCategory, LogCategoryGroup } from '@oiiiai/category-logger';

或者按文件引入：

import { LogCategory } from '@oiiiai/category-logger/logCategory';
import { LogCategoryGroup } from '@oiiiai/category-logger/logCategoryGroup';

核心概念

LogCategory

管理日志分类，决定某一类日志是否输出。

常用方法：

• info/debug/warn/error 输出日志
• enableCategories/disableCategories 启用或禁用分类
• enableAll/disableAll 批量启用或禁用
• group/groupEnd 创建或结束日志分组

LogCategoryGroup

将多个分类组织成逻辑组，便于整体控制。

• 启用/禁用分组
• 绑定到 LogCategory 后，分组状态会影响分类

LogLevel

日志等级：

• DEBUG
• INFO
• WARN
• ERROR

基本用法

创建分类

const logCategory = new LogCategory(['API', 'INPUT']);

或者使用对象配置形式：

const logCategory = new LogCategory({
  API: { active: true, prefix: '[API]' },
  INPUT: { active: false }
});

启用/禁用分类

logCategory.enableCategories(['API']);
logCategory.disableCategories(['INPUT']);
logCategory.enableAll();
logCategory.disableAll();

日志输出

logCategory.info('请求开始', 'API');
logCategory.debug('表单数据', 'INPUT', { username: 'Alice' });
logCategory.error('请求失败', 'API', { code: 500 });

日志分组

logCategory.group('用户操作', ['API'], () => {
  logCategory.info('点击按钮', 'INPUT');
  logCategory.debug('表单状态', 'INPUT', { field: 'username' });
});
// 输出: 分组 "[API] 用户操作" 耗时: XXms

高级用法

对象调用方式

logCategory.info({
  msg: '数据处理完成',
  data: { id: 123 },
  categories: 'EFFECT',
  prefix: '>>>'
});

对象参数字段：

• msg 日志信息
• data 任意对象
• categories 分类或分类数组
• prefix 自定义前缀

原生调用方式

logCategory.info('提交表单', 'API', { username: 'Bob' });

批量操作

logCategory.enableAll();
logCategory.disableAll();
group.enableAll();
group.disableAll();

配置说明

• 默认行为：所有分类与分组均未激活
• 激活方式：通过 enableCategories 或 enableAll 显式启用
• 单例设计：推荐在项目初始化时统一配置 LogCategory 和 LogCategoryGroup

示例代码

const logCategory = new LogCategory(['API', 'INPUT', 'EFFECT']);
const group = new LogCategoryGroup();
logCategory.bindCategoryGroup(group);

logCategory.enableAll();
group.enableAll();

logCategory.info('开始流程', 'API');

logCategory.group('表单操作', ['INPUT'], () => {
  logCategory.debug('修改字段', 'INPUT', { key: 'username' });
  logCategory.info('提交表单', 'API');
});

最佳实践

1. 初始化时配置分类和分组，避免运行中动态修改配置
2. 按需启用分类，避免控制台冗余信息
3. 推荐使用对象调用方式输出结构化日志
4. 使用分组统计耗时，对性能敏感场景特别有帮助

注意事项

1. 默认未激活任何分类/分组 → 不会有日志输出
2. prefix 仅在对象调用方式或分组配置中生效
3. 支持嵌套分组，结束时自动统计耗时
4. 分类未启用但所属分组启用 → 日志依然输出
5. 不建议频繁修改配置，推荐单例管理

常见问题 (FAQ)

为什么没有日志输出？

• 默认情况下，所有分类和分组均未激活
• 解决方法：

logCategory.enableCategories(['API']); // 启用指定分类
logCategory.enableAll(); // 或启用所有分类

如何只启用部分分类？

• 使用 enableCategories 启用指定分类
• 已绑定分组也会影响输出

如何区分开发环境与生产环境日志？

if (process.env.NODE_ENV === 'development') {
  logCategory.enableAll();
} else {
  logCategory.disableAll();
  logCategory.enableCategories(['ERROR']); // 仅输出错误日志
}

如何统计分组耗时？

• 使用 group 包裹操作，结束后自动输出耗时

logCategory.group('操作流程', ['API'], () => {
  logCategory.info('开始操作', 'API');
});

分组 "[API] 操作流程" 耗时: XXms