mini-starter/.roo/rules/09-logging.md

日志规范

1. 基础配置

• 前后端统一使用debug库
• 开发环境：启用所有日志级别
• 生产环境：通过环境变量DEBUG控制日志级别
• 安装依赖：已安装debug@4.4.1和@types/debug

2. 命名空间规范

格式：<应用>:<模块>:<功能>
示例：

frontend:auth:login    # 前端-认证-登录
backend:api:middleware # 后端-API-中间件
backend:db:query       # 后端-数据库-查询
k8s:deployment:create  # K8S-部署-创建

3. 日志级别

级别	使用场景
error	系统错误、异常情况
warn	警告性事件
info	重要业务流程信息
debug	调试信息
trace	详细跟踪信息(慎用)

4. 实现示例

前端示例

// 在需要使用日志的文件中直接引入debug
import debug from 'debug';

// 按需定义命名空间
const errorLogger = debug('frontend:error');
const apiLogger = debug('frontend:api');
const authLogger = debug('frontend:auth');
const uiLogger = debug('frontend:ui');

// 使用示例
errorLogger('用户登录失败: %s', error.message);
apiLogger('API请求: %s', url);

后端示例

// 在需要使用日志的文件中直接引入debug
import debug from 'debug';

// 按需定义命名空间
const errorLogger = debug('backend:error');
const apiLogger = debug('backend:api');
const dbLogger = debug('backend:db');
const middlewareLogger = debug('backend:middleware');

// 使用示例
errorLogger('数据库连接失败: %s', error.message);
dbLogger('查询执行: %s', sql);

5. 最佳实践

1. 错误日志必须包含错误堆栈和上下文
2. 禁止记录密码、token等敏感信息
3. 生产环境避免使用trace级别
4. 复杂对象使用JSON.stringify()

6. 环境配置

```bash

开发环境

DEBUG=*

生产环境

DEBUG=:error,:warn

特定模块调试

DEBUG=backend:api,backend:db