eafonyang
39 lines
2.1 KiB
Markdown
39 lines
2.1 KiB
Markdown
---
|
|
kind: logging_system
|
|
name: 后端日志系统 (Winston)
|
|
category: logging_system
|
|
scope:
|
|
- '**'
|
|
source_files:
|
|
- backend/src/config/logger.js
|
|
- backend/src/app.js
|
|
- backend/src/routes/auth.js
|
|
- backend/src/config/database.js
|
|
---
|
|
|
|
## 1. 核心框架与配置
|
|
- **框架**: 使用 `winston` 作为后端 Node.js 应用的统一日志框架。
|
|
- **配置文件**: `backend/src/config/logger.js` 负责初始化 logger 实例。
|
|
- **日志级别**: 默认设置为 `info`，涵盖 info, warn, error 等级别。
|
|
- **输出格式**:
|
|
- 采用自定义的文本格式：`${timestamp} - ${level} - ${message} ${JSON.stringify(meta)}`。
|
|
- 时间戳格式为 `YYYY-MM-DD HH:mm:ss`。
|
|
- 额外元数据（meta）会被序列化为 JSON 字符串附加在消息后。
|
|
|
|
## 2. 日志输出目标 (Transports)
|
|
- **控制台 (Console)**: 所有级别的日志都会输出到标准输出，便于本地开发和容器日志采集。
|
|
- **文件 (File)**: 所有日志同时写入 `backend/logs/app.log` 文件。
|
|
- 目录 `logs/` 若不存在会在初始化时自动创建。
|
|
- 目前未配置日志轮转（Log Rotation），长期运行需注意文件大小。
|
|
|
|
## 3. 使用规范与模式
|
|
- **引入方式**: 在各业务模块中通过 `require('../config/logger')` 获取单例 logger。
|
|
- **记录模式**:
|
|
- **信息类**: `logger.info('描述性消息')`，如服务启动、用户登录成功、数据库同步完成。
|
|
- **警告类**: `logger.warn('异常但可恢复的情况')`，如登录失败、资源未找到。
|
|
- **错误类**: `logger.error('错误详情')`，通常在 catch 块中记录异常信息 `e.message`。
|
|
- **上下文记录**: 建议在 message 中包含关键业务 ID 或参数，例如 `User ${username} logged in` 或 `id=${brandId}`。
|
|
|
|
## 4. 特殊场景处理
|
|
- **数据库日志**: 在 `backend/src/config/database.js` 中，Sequelize 的 SQL 日志仅在开发环境 (`APP_ENV === 'development'`) 下通过 `console.log` 输出，生产环境关闭以避免性能损耗和日志污染。
|
|
- **前端日志**: 前端项目 (`frontend/`) 目前未发现统一的日志封装，主要依赖浏览器控制台默认的 `console` 输出。 |