npm package: @oiiiai/category-logger
Description: An implementation class for log management capabilities that can be categorized and grouped
Author: whynotsnow
Latest version: 1.0.4

# 日志系统使用文档

## 目录

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

---

## 简介

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

支持功能：

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

---

## 快速开始

```ts
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 安装：

```bash
npm install @oiiiai/category-logger
```

引入模块：

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

或者按文件引入：

```ts
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`

---

## 基本用法

### 创建分类

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

或者使用对象配置形式：

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

### 启用/禁用分类

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

### 日志输出

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

### 日志分组

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

---

## 高级用法

### 对象调用方式

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

对象参数字段：

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

### 原生调用方式

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

### 批量操作

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

---

## 配置说明

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

---

## 示例代码

```ts
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)

### 为什么没有日志输出？

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

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

### 如何只启用部分分类？

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

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

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

### 如何统计分组耗时？

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

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

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