init commit

This commit is contained in:
ResCells committed 2026-04-03 17:43:57 +08:00
commit 4ffd2436ba
44 files changed
+6584

No files matched your search

+334
View File
@@ -0,0 +1,334 @@
# 日志规范完善版 (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 / 跨服务调用记录前后摘要、耗时和状态**
如果所有日志都遵守“谁负责谁记录、下游异常不重复记、日志只保留关键上下文”这三个原则,后续排障和审计都会轻松很多。
+19
View File
@@ -0,0 +1,19 @@
# 记录位置
## Controller
Controller使用`@DefaultControllerLog`切面统一记录访问日志, 并且实现接口大面积失效报警功能;
需要一个 try-catch 块来捕获 Controller 内部的所有异常, 并在 catch 块中记录**兜底**异常日志, 如果是下游抛出的异常, 则交给下游记录日志;
## Service
Service层是业务核心, 需要在**核心对象创建/删除**, **状态变化**, **数据同步与核心流程结束**, 等具有业务里程碑意义的场景记录日志, 以便于事后追踪用户行为和系统状态;
同样, 如果是下游抛出的异常, 则由下游处理, 不应该在 Service 层重复记录日志;
## Utils & 跨服务调用 (RPC/HttpClient/Redis/DB/SDK)
Utils 和跨服务调用是网络波动极其多发的灾区, 需要在**调用前切面/钩子**记录发起目的地名称和请求摘要, 在**调用返回**时必须记录耗时(ms)以及对方返回的关键状态(如 HTTP Code 或三方的业务状态码), 以便于事后追踪网络问题和性能瓶颈;
同样, 如果是下游抛出的异常, 则由下游处理, 不应该在 Utils 层重复记录日志;