# 日志规范

## 日志格式标准

### 标准日志格式
```
[时间] [级别] [模块] [请求ID] 消息内容 {JSON上下文}
```

```
[2024-01-15 10:30:00.123] [INFO] [user-service] [req-abc123] 用户登录成功 {"userId": 123, "ip": "192.168.1.1"}
```

### 结构化日志（推荐）
```javascript
logger.info('用户登录成功', {
  userId: 123,
  ip: '192.168.1.1',
  timestamp: new Date().toISOString(),
  duration: 150 // ms
});
```

## 各模块日志标识

| 模块 | 标识名 | 说明 |
|:----|:-------|:-----|
| HTTP 请求 | `http` | 请求/响应日志 |
| 数据库 | `db` | SQL 查询日志 |
| 缓存 | `cache` | Redis 操作日志 |
| 第三方 API | `external` | 外部接口调用日志 |
| 定时任务 | `cron` | 定时任务日志 |
| 用户操作 | `audit` | 用户操作审计日志 |

## 日志记录策略

### 必须记录的场景
1. 请求开始和结束（含耗时）
2. 数据库查询失败
3. 第三方服务调用（含请求参数和响应）
4. 用户关键操作（登录、支付、权限变更）
5. 系统异常和未捕获错误
6. 应用启动/停止/重载

### 建议不记录的场景
1. 频繁的轮询请求（用计数器代替）
2. 文件/图片内容（记录文件名和大小即可）
3. 密码/密钥/Token（脱敏或直接不记录）
4. 超大数据体（截断 > 10KB 的内容）

## 日志文件管理

| 规则 | 说明 |
|:----|:-----|
| 日志目录 | `./logs/` |
| 文件命名 | `app-YYYY-MM-DD.log` |
| 按天轮转 | 每天生成一个新文件 |
| 按大小轮转 | 单文件最大 100MB |
| 保留周期 | 最近 30 天 |
| 日志归档 | 超过 30 天自动压缩归档 |

## 敏感信息脱敏

```javascript
function maskSensitive(data) {
  if (data.password) data.password = '***';
  if (data.token) data.token = data.token.slice(0, 4) + '***';
  if (data.phone) data.phone = data.phone.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2');
  if (data.email) data.email = data.email.replace(/(.{2}).*(@.*)/, '$1***$2');
  return data;
}
```

## 禁止行为
- ❌ 禁止在日志中输出完整 SQL（含参数值的 SQL）
- ❌ 禁止日志中包含用户敏感信息（密码、身份证、银行卡号）
- ❌ 禁止在循环中打印日志（会导致日志量爆炸）
- ❌ 禁止在同一行混用不同级别的日志
- ❌ 禁止日志内容使用非 UTF-8 编码