diff --git a/文档/基础组件/20250428-后端服务日志规范.md b/文档/基础组件/20250428-后端服务日志规范.md index bfd73e2..75cb5ff 100644 --- a/文档/基础组件/20250428-后端服务日志规范.md +++ b/文档/基础组件/20250428-后端服务日志规范.md @@ -25,13 +25,13 @@ ## 一、日志级别定义与使用场景 -| 日志级别 | 使用场景 | 典型输出示例 | -|-----------|------------------------------------|---------------------------------------------------------------------------| -| **TRACE** | 最细粒度的调试信息,用于跟踪代码执行路径
(生产环境默认关闭) | `TRACE [http-nio-8080-exec-1] c.a.Service - Entering calculate() method` | -| **DEBUG** | 开发/测试环境使用的调试信息,记录关键变量值、流程分支等 | `DEBUG [http-nio-8080-exec-1] c.a.Service - UserID=123, balance=500.00` | -| **INFO** | 重要业务流程节点信息,用于跟踪系统运行状态 | `INFO [http-nio-8080-exec-1] c.a.Service - Order 20230815001 created` | -| **WARN** | 非预期但可恢复的异常情况,需要人工关注但不需要立即干预 | `WARN [http-nio-8080-exec-1] c.a.Service - Cache miss for key: user_123` | -| **ERROR** | 系统级错误,导致当前操作失败且无法自动恢复的异常(需触发告警) | `ERROR [http-nio-8080-exec-1] c.a.Service - DB connection failed` | +| 日志级别 | 使用场景 | 典型输出示例 | +|-----------|---------------------------------|---------------------------------------------------------------------------| +| **TRACE** | 最细粒度的调试信息,用于跟踪代码执行路径:(生产环境默认关闭) | `TRACE [http-nio-8080-exec-1] c.a.Service - Entering calculate() method` | +| **DEBUG** | 开发/测试环境使用的调试信息,记录关键变量值、流程分支等 | `DEBUG [http-nio-8080-exec-1] c.a.Service - UserID=123, balance=500.00` | +| **INFO** | 重要业务流程节点信息,用于跟踪系统运行状态 | `INFO [http-nio-8080-exec-1] c.a.Service - Order 20230815001 created` | +| **WARN** | 非预期但可恢复的异常情况,需要人工关注但不需要立即干预 | `WARN [http-nio-8080-exec-1] c.a.Service - Cache miss for key: user_123` | +| **ERROR** | 系统级错误,导致当前操作失败且无法自动恢复的异常(需触发告警) | `ERROR [http-nio-8080-exec-1] c.a.Service - DB connection failed` | --- @@ -132,12 +132,12 @@ public void log() { ## 四、异常体系与日志级别映射 -| 异常类型 | 日志级别 | 继承关系 | 使用场景说明 | -|------------------------|-------|------------------------------------------------------|---------------------------------------------| -| **YmBizDataException** | INFO | `extends YmBizException` | 业务数据相关预期异常(不影响主流程)
例:查询结果为空、数据状态不满足条件 | -| **YmBizException** | WARN | `extends YmException` | 业务流程中的可控异常(需明确处理流程)
例:参数校验失败、权限不足、业务规则限制 | -| **YmException** | ERROR | `extends RuntimeException` | 系统级不可恢复异常(需立即介入)
例:基础设施故障、关键依赖服务不可用 | -| **自定义业务异常** | 继承父类 | `extends YmException/YmBizException/YmBiz*Exception` | 根据业务需求扩展,自动继承父类日志级别策略 | +| 异常类型 | 日志级别 | 继承关系 | 使用场景说明 | +|------------------------|-------|------------------------------------------------------|------------------------------------------| +| **YmBizDataException** | INFO | `extends YmBizException` | 业务数据相关预期异常(不影响主流程)。例:查询结果为空、数据状态不满足条件 | +| **YmBizException** | WARN | `extends YmException` | 业务流程中的可控异常(需明确处理流程)。例:参数校验失败、权限不足、业务规则限制 | +| **YmException** | ERROR | `extends RuntimeException` | 系统级不可恢复异常(需立即介入)。例:基础设施故障、关键依赖服务不可用 | +| **自定义业务异常** | 继承父类 | `extends YmException/YmBizException/YmBiz*Exception` | 根据业务需求扩展,自动继承父类日志级别策略 | ---