335 lines
8.9 KiB
Markdown
335 lines
8.9 KiB
Markdown
# 日志规范完善版 (By ChatGPT)
|
||
|
||
> 基于现有 `日志规范说明.md` 整理，目标是把“什么时候记、谁来记、记什么、记到什么程度”说清楚，便于后续统一埋点和排查问题。
|
||
|
||
## 1. 文档目标
|
||
|
||
日志的核心目标不是“尽可能多地打印”，而是为了后续能够：
|
||
|
||
- 快速定位问题发生在哪一层
|
||
- 还原一次请求的完整链路
|
||
- 区分业务异常、参数异常和系统异常
|
||
- 追踪核心业务动作是否执行成功
|
||
- 在网络调用、数据库调用、SDK 调用等场景下，快速确认耗时和返回状态
|
||
|
||
## 2. 总体原则
|
||
|
||
### 2.1 谁负责记录谁的日志
|
||
|
||
- **Controller**：负责接口入口层的访问日志和兜底异常日志
|
||
- **Service**：负责业务里程碑日志
|
||
- **Utils / RPC / HTTP / Redis / DB / SDK**：负责外部依赖调用的前后日志
|
||
- **下游异常**：由下游自己记录，不在上游重复记录
|
||
|
||
### 2.2 日志要满足的最小信息
|
||
|
||
一条可用日志，至少应能回答以下问题：
|
||
|
||
- 谁发起的：`uid`、`traceId`
|
||
- 调了什么：类名、方法名、接口 URI、目标服务名
|
||
- 做了多久：`durationMs`、耗时统计
|
||
- 结果如何：成功、失败、HTTP 状态码、业务状态码
|
||
- 为什么失败：异常类型、必要的错误摘要
|
||
|
||
### 2.3 避免重复记录
|
||
|
||
当异常已经在下游被明确处理并记录时，上游不要再重复打 ERROR：
|
||
|
||
- 下游负责记录：具体依赖失败、远程超时、数据库异常等
|
||
- 上游负责感知：把异常继续抛出，或转换为统一业务异常
|
||
- 上游只保留必要的上下文日志，不重复打印同一条堆栈
|
||
|
||
## 3. Controller 层日志规范
|
||
|
||
Controller 是接口入口层，重点关注“请求进来了、请求结果是什么、是否发生兜底异常”。
|
||
|
||
### 3.1 必须记录的内容
|
||
|
||
由 `@DefaultControllerLog` 统一记录：
|
||
|
||
- 接口描述 `desc`
|
||
- 类名 `className`
|
||
- 方法名 `methodName`
|
||
- 请求 URI `uri`
|
||
- 用户标识 `uid`
|
||
- 耗时 `durationMs`
|
||
- 响应状态 `status`
|
||
- 异常类型 `exception`
|
||
|
||
### 3.2 记录方式
|
||
|
||
Controller 推荐只保留一层统一切面：
|
||
|
||
- 请求进入时开始计时
|
||
- 方法正常返回后记录成功日志
|
||
- 方法抛出异常后记录失败日志
|
||
- 在 `finally` 中完成统一输出，保证无论成功失败都能落日志
|
||
|
||
### 3.3 Controller 的异常处理原则
|
||
|
||
- Controller 内部应有 **try-catch 兜底** 的意识，但不要吞掉异常
|
||
- 如果异常来自下游服务、数据库、SDK 等，应该继续向上抛出，由对应下游层自己先记录
|
||
- 如果是 Controller 自身拼装、参数转换、分支判断等导致的异常，可以记录兜底日志
|
||
- 参数解析失败、JSON 反序列化失败等客户端问题，优先作为 **400 类问题** 处理，不应误报成系统故障
|
||
|
||
### 3.4 建议记录示例
|
||
|
||
- 成功请求：记录 `INFO`
|
||
- 业务异常：记录 `WARN` 或 `INFO`，视业务重要程度决定
|
||
- 未预期异常：记录 `ERROR`
|
||
|
||
### 3.5 当前项目中的对应实现
|
||
|
||
项目里已有：
|
||
|
||
- `DefaultControllerLogAspect`
|
||
- `ControllerLogBO`
|
||
- `BusinessControllerExceptionHandler`
|
||
- `TraceContextUtil`
|
||
|
||
这套实现已经具备 Controller 统一记录的基础，后续建议补齐：
|
||
|
||
- `uid` 的获取逻辑
|
||
- `traceId` / `spanId` 在日志中的统一输出
|
||
- 对不同异常类型的日志级别区分
|
||
|
||
## 4. Service 层日志规范
|
||
|
||
Service 层是业务核心，不负责“每一步都打日志”，而是负责记录对业务有里程碑意义的节点。
|
||
|
||
### 4.1 应记录的场景
|
||
|
||
建议在以下场景记录业务日志：
|
||
|
||
- 核心对象创建
|
||
- 核心对象删除
|
||
- 业务状态变化
|
||
- 数据同步完成
|
||
- 流程节点切换
|
||
- 核心任务开始与结束
|
||
- 影响用户结果的关键决策点
|
||
|
||
### 4.2 不建议记录的场景
|
||
|
||
以下情况一般不应在 Service 层重复记录：
|
||
|
||
- 下游抛出的异常已经在下游记录过
|
||
- 单纯的参数透传
|
||
- 没有业务意义的中间变量变化
|
||
- 每次循环都打印相同信息
|
||
|
||
### 4.3 Service 层建议关注的日志内容
|
||
|
||
一条好的业务日志通常包含：
|
||
|
||
- 业务对象 ID
|
||
- 业务动作
|
||
- 状态前后变化
|
||
- 处理结果
|
||
- 关键条件分支
|
||
|
||
示例字段：
|
||
|
||
- `orderId`
|
||
- `userId`
|
||
- `beforeStatus`
|
||
- `afterStatus`
|
||
- `action`
|
||
- `result`
|
||
|
||
### 4.4 异常处理原则
|
||
|
||
- Service 层可对业务异常做转换，但不要重复打印同一个下游异常堆栈
|
||
- 如果 Service 自己发现业务不成立，应抛出明确的业务异常
|
||
- 如果是资源、网络、数据库等问题，交给下游或统一异常处理层记录
|
||
|
||
## 5. Utils 与跨服务调用日志规范
|
||
|
||
Utils、RPC、HTTP Client、Redis、DB、SDK 等调用是最容易出现网络波动和性能问题的区域，因此必须前后成对记录。
|
||
|
||
### 5.1 调用前必须记录
|
||
|
||
调用发起前，应记录以下信息：
|
||
|
||
- 目标名称：服务名、库名、SDK 名称、URL、Redis Key 前缀等
|
||
- 请求摘要：请求参数的关键字段，避免打印敏感数据
|
||
- 调用目的：本次调用是为了什么业务动作
|
||
- 关联链路：`traceId`、`spanId`
|
||
|
||
### 5.2 调用后必须记录
|
||
|
||
调用返回后，应记录：
|
||
|
||
- 耗时 `durationMs`
|
||
- 返回结果摘要
|
||
- 对方状态码或业务状态码
|
||
- 是否超时
|
||
- 是否重试
|
||
|
||
### 5.3 建议关注的日志内容
|
||
|
||
对于外部依赖，重点不是“全量打印响应”，而是以下信息：
|
||
|
||
- 请求目标
|
||
- 请求关键参数
|
||
- 返回耗时
|
||
- 返回状态
|
||
- 失败原因
|
||
|
||
### 5.4 不应记录的内容
|
||
|
||
- 密码、令牌、密钥、身份证号等敏感信息
|
||
- 过大的请求/响应全文
|
||
- 无法脱敏的用户隐私数据
|
||
- 已知会产生大量噪音的调试级细节
|
||
|
||
### 5.5 异常处理原则
|
||
|
||
- 下游调用失败，由下游先记录
|
||
- 上游只做必要的异常转换或透传
|
||
- 若需要重试，应记录每次重试的次数和最终结果
|
||
|
||
## 6. 日志字段建议
|
||
|
||
建议统一使用以下基础字段：
|
||
|
||
- `traceId`：一次请求链路的全局标识
|
||
- `spanId`：当前调用点标识
|
||
- `uid`：用户标识
|
||
- `className`：类名
|
||
- `methodName`：方法名
|
||
- `uri`：请求路径或目标路径
|
||
- `durationMs`：耗时
|
||
- `status`：HTTP 状态或调用状态
|
||
- `exception`：异常类型或摘要
|
||
- `desc`：业务描述
|
||
|
||
### 6.1 字段使用建议
|
||
|
||
- `traceId`：用于串联一次请求的完整链路
|
||
- `spanId`：用于区分同一请求内的不同调用点
|
||
- `uid`：用于追踪用户行为
|
||
- `durationMs`：用于性能分析
|
||
- `status`：用于快速判断结果是否成功
|
||
- `exception`：用于快速定位失败类型
|
||
|
||
## 7. 日志级别建议
|
||
|
||
### 7.1 INFO
|
||
|
||
适用于：
|
||
|
||
- 请求正常完成
|
||
- 核心业务动作成功
|
||
- 外部调用成功且有分析价值
|
||
|
||
### 7.2 WARN
|
||
|
||
适用于：
|
||
|
||
- 客户端参数错误
|
||
- 可预期的业务失败
|
||
- 可恢复的下游失败
|
||
- 需要关注但不一定影响主流程的异常
|
||
|
||
### 7.3 ERROR
|
||
|
||
适用于：
|
||
|
||
- 未预期系统异常
|
||
- 无法恢复的故障
|
||
- 需要立即排查的严重错误
|
||
|
||
## 8. 推荐的统一输出格式
|
||
|
||
建议日志内容尽量结构化，方便后续检索和分析。
|
||
|
||
示例结构：
|
||
|
||
```text
|
||
{"traceId":"...","spanId":"...","uid":"...","className":"...","methodName":"...","uri":"...","durationMs":123,"status":"OK","exception":null,"desc":"..."}
|
||
```
|
||
|
||
对于外部调用，可再补充：
|
||
|
||
- `target`
|
||
- `requestSummary`
|
||
- `responseSummary`
|
||
- `retryCount`
|
||
- `remoteCode`
|
||
|
||
## 9. 常见误区
|
||
|
||
### 9.1 过度记录
|
||
|
||
问题表现：
|
||
|
||
- 一个方法内打印很多行
|
||
- 同一异常被多层重复打印
|
||
- 每个中间步骤都记日志
|
||
|
||
后果：
|
||
|
||
- 日志噪音过大
|
||
- 关键问题被淹没
|
||
- 排障效率下降
|
||
|
||
### 9.2 只记异常，不记上下文
|
||
|
||
问题表现：
|
||
|
||
- 只有 `NullPointerException`
|
||
- 没有用户、接口、调用目标、耗时
|
||
|
||
后果：
|
||
|
||
- 无法快速定位具体链路
|
||
|
||
### 9.3 打印敏感信息
|
||
|
||
问题表现：
|
||
|
||
- 直接打印完整请求体
|
||
- 直接打印密码或 token
|
||
|
||
后果：
|
||
|
||
- 安全风险
|
||
- 合规风险
|
||
|
||
## 10. 新增接口或调用点时的检查清单
|
||
|
||
新增代码前，建议逐项确认：
|
||
|
||
- [ ] 这段代码属于 Controller、Service 还是 Utils/外部调用
|
||
- [ ] 是否已经有统一切面或统一处理器
|
||
- [ ] 是否只记录了应该记录的那一层
|
||
- [ ] 是否避免了重复打印下游异常
|
||
- [ ] 是否包含 `traceId` / `spanId`
|
||
- [ ] 是否包含业务关键字段
|
||
- [ ] 是否脱敏了敏感数据
|
||
- [ ] 是否记录了耗时和结果状态
|
||
- [ ] 是否对异常级别做了合理区分
|
||
|
||
## 11. 建议落地顺序
|
||
|
||
如果要逐步完善当前项目，建议按下面顺序推进：
|
||
|
||
1. 统一 `traceId` / `spanId` 输出
|
||
2. 补齐 `uid` 获取逻辑
|
||
3. 完善 Controller 统一访问日志
|
||
4. 补充 Service 业务里程碑日志
|
||
5. 为外部调用增加前后日志模板
|
||
6. 统一异常分类与日志级别
|
||
|
||
## 12. 总结
|
||
|
||
这份规范的核心只有三句话：
|
||
|
||
- **Controller 记录入口和兜底异常**
|
||
- **Service 记录业务里程碑**
|
||
- **Utils / 跨服务调用记录前后摘要、耗时和状态**
|
||
|
||
如果所有日志都遵守“谁负责谁记录、下游异常不重复记、日志只保留关键上下文”这三个原则，后续排障和审计都会轻松很多。
|
||
|