eafonyang
45 lines
3.0 KiB
Markdown
45 lines
3.0 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/redis.js
|
||
- backend/package.json
|
||
---
|
||
|
||
## 1. 使用的框架与工具
|
||
- 日志框架：`winston ^3.14`
|
||
- 依赖声明位于 `backend/package.json`，通过 `require('winston')` 引入。
|
||
- 前端未集成专用日志库，调试主要依赖浏览器控制台。
|
||
|
||
## 2. 核心文件与位置
|
||
- 日志配置与实例导出：`backend/src/config/logger.js`
|
||
- 应用入口统一引入：`backend/src/app.js`（`const logger = require('./config/logger');`）
|
||
- 各模块按需引入使用，典型示例：`backend/src/routes/auth.js`、`backend/src/config/redis.js` 等。
|
||
- 默认日志文件路径：`backend/logs/app.log`（由 `logger.js` 自动创建目录并写入）。
|
||
|
||
## 3. 架构与约定
|
||
- **集中式初始化**：所有日志输出均通过 `src/config/logger.js` 暴露的单一 `logger` 实例，避免重复配置。
|
||
- **输出目标（transports）**：同时输出到控制台和文件两个 sink：
|
||
- Console transport：便于本地开发实时观察。
|
||
- File transport：固定文件名 `logs/app.log`，编码 UTF-8。
|
||
- **格式策略**：`timestamp + level + message + JSON meta` 拼接的单行文本格式，时间格式为 `YYYY-MM-DD HH:mm:ss`；当存在额外元数据时以空格分隔追加 JSON 字符串。
|
||
- **级别策略**：全局 `level: 'info'`，代码中仅使用 `info / warn / error` 三个级别，未见 `debug` 级别调用。
|
||
- **结构化字段**：未采用 winston 的 structured log 对象传参方式，而是将业务上下文拼入 message 字符串（如 `Login failed for username=${trimmedUsername}`），meta 字段基本未使用。
|
||
- **数据库层日志**：Sequelize 在开发环境启用原生 `console.log` 打印 SQL，生产环境关闭（`logging: isDevelopment ? (msg) => console.log(msg) : false`），不走 Winston。
|
||
|
||
## 4. 开发者应遵循的规则
|
||
- **统一引用**：始终从 `../config/logger` 或相对路径引用同一 logger 实例，不要自行 `createLogger`。
|
||
- **级别选择**：
|
||
- `info`：记录关键业务流程事件（登录成功、密码修改、服务启动等）。
|
||
- `warn`：记录可恢复异常或预期外的分支（用户名不存在、资源未找到等）。
|
||
- `error`：记录异常堆栈信息或不可恢复错误。
|
||
- 不使用 `debug` 级别。
|
||
- **消息内容**：将关键上下文（用户名、ID、MAC 等）直接拼入 message 字符串；如需附带复杂对象，可通过第三个参数传入 meta，但当前代码风格倾向于纯文本。
|
||
- **敏感信息**：禁止在日志中输出密码、token、完整请求体等敏感数据（现有代码已避免输出 password_hash/token 值）。
|
||
- **文件轮转**：当前未配置 winston-daily-rotate-file 等轮转插件，长期运行需注意 `app.log` 体积增长，后续可在 transports 中补充轮转策略。 |