## 日志优化评估与补丁跟踪

**概述**：基于现有日志（已含 `requestId` / `traceId`），本文档记录对你提出的日志优化建议的评估、对现有配置的影响、需要的补丁清单与实施步骤，可作为补丁进展的跟踪记录。

**当前关键文件**：
- **当前 logback 配置**: [api-springboot/src/main/resources/logback-spring.xml](api-springboot/src/main/resources/logback-spring.xml#L1-L200)
- **Trace 拦截器**: [api-springboot/src/main/java/work/baiyun/chronicdiseaseapp/config/TraceInterceptor.java](api-springboot/src/main/java/work/baiyun/chronicdiseaseapp/config/TraceInterceptor.java#L1-L200)
- **Maven POM**: [api-springboot/pom.xml](api-springboot/pom.xml#L1-L120)

**1. 评估摘要（快速结论）**
- **可行性**：你列出的优化（logback 重构、请求拦截器、脱敏 appender、AOP）均可实现，且与现有 `logback-spring.xml` 兼容，但需替换或合并已有配置（不要并存多个 logback-spring 配置以免冲突）。
- **影响范围**：主要影响 `logback` 配置；当前决定先不引入日志 JSON 输出（FILE_JSON）或额外的 `logstash-logback-encoder` 依赖，后续如需再考虑添加。
- **性能/风险**：脱敏正则在高 QPS 下可能带来 CPU 与延迟，建议异步输出或在代码层避免打印敏感值优先；额外 appender 会增加磁盘 IO。

**2. 是否影响现有日志配置 / 冲突点**
- 不会破坏 MDC 的现有使用，但要统一 MDC key（当前使用 `requestId` / `traceId`）。若要添加 `spanId`，需在拦截器或链路追踪库中写入 `MDC.put("spanId", ...)`。
- 必须确保仓库中只有一个 `logback-spring.xml` 生效（当前文件位于上面链接）。替换时请备份原文件。
- 当前已决定不引入 JSON encoder；若未来启用 JSON 输出，再在 `pom.xml` 添加 `net.logstash.logback:logstash-logback-encoder`。

**3. 依赖变更**
- 当前无需立即变更 `pom.xml`，保留为文本日志；若未来决定使用结构化 JSON 日志，可考虑添加依赖（示例）: `net.logstash.logback:logstash-logback-encoder:7.4`。
- 若使用异步 appender，依赖可以直接使用 logback 自带 `AsyncAppender`，无需额外库。

- **4. 建议补丁清单（要修改/新增的文件）**
- 替换/更新 `api-springboot/src/main/resources/logback-spring.xml`：使用示例中更简洁的 pattern、增加 `FILE_DETAIL`、`FILE_ERROR`，并使用 `%X{traceId:-}` 等避免空括号。
- 新增 `RequestLoggingFilter`：`api-springboot/src/main/java/work/baiyun/chronicdiseaseapp/filter/RequestLoggingFilter.java`（记录 URI、耗时、client IP、MDC traceId，慢请求告警）。
- 新增 `LoggingAspect`：`api-springboot/src/main/java/work/baiyun/chronicdiseaseapp/aop/LoggingAspect.java`（入参/出参脱敏与方法耗时、慢方法告警）。
- 新增 `LogDesensitizeAppender`（可选草稿）：`api-springboot/src/main/java/work/baiyun/chronicdiseaseapp/log/LogDesensitizeAppender.java`（若采用，全链路异步写入并仅对必要消息做替换）。
- 新增 `RequestLoggingFilter`：`api-springboot/src/main/java/work/baiyun/chronicdiseaseapp/filter/RequestLoggingFilter.java`（记录 URI、耗时、client IP、MDC traceId，慢请求告警）。
- 新增 `LoggingAspect`：`api-springboot/src/main/java/work/baiyun/chronicdiseaseapp/aop/LoggingAspect.java`（入参/出参脱敏与方法耗时、慢方法告警）。
- 新增 `LogDesensitizeAppender`（可选草稿）：`api-springboot/src/main/java/work/baiyun/chronicdiseaseapp/log/LogDesensitizeAppender.java`（若采用，全链路异步写入并仅对必要消息做替换）。

**5. 实施步骤（推荐顺序）**
1. 备份并替换 `logback-spring.xml`，保证新配置引用的 appender 与 logger 正确（避免重复写入）。
2. 部署 `RequestLoggingFilter`（低风险，记录必要请求信息，注意 body/headers 不默认记录）。
3. 在代码中查找并移除/屏蔽直接打印敏感值的语句（优先于全局脱敏）。
4. 添加 `LoggingAspect`（AOP）以覆盖 Controller 入参/出参日志并做脱敏处理。
5. 若确有必要且确认性能可接受，再实现 `LogDesensitizeAppender` 并通过 `AsyncAppender` 链接到文件/控制台。 
6. 回归测试（低流量环境），并做压力测试以观察 CPU/IO 影响；调整异步队列大小与文件滚动策略。

**6. 测试与验证要点**
- 启动应用，检查控制台/`logs/app.log` 是否仅有一份消息（无重复）。
- 验证 MDC 字段在日志中展示：例如 `[traceId]` 不再空白（或显示 `-` 作为默认）。
- 验证敏感字段被脱敏（示例请求中 `secret`/`token` 显示为 `***`）。
- 运行压力测试（如 ApacheBench 或 JMeter）观察新增正则或额外 appender 是否导致延迟或 CPU 升高。

**7. 风险与应对**
- 脱敏正则造成 CPU 占用：使用预编译 Pattern、限制匹配范围、或采用异步 appender。
- 日志双写/重复：检查 logger 的 `additivity` 与 root logger，必要时将业务 logger additivity 设为 false。
- 敏感信息仍可能在异常栈或第三方库中打印：最好在代码中根本避免将 secret 写入日志。

**8. 补丁进度（来自 TODO 跟踪）**
- 已完成：检查现有配置与 MDC 使用；校验依赖是否存在；评估兼容性。
- 进行中：评估脱敏 Appender 的可行性及性能影响（id=4）。
- 未开始：添加 Filter/AOP 与提交可执行补丁并运行测试（id=5、6）。
 - 已应用：备份并替换 `logback-spring.xml`，已添加异步文件与错误文件 appender（步骤 1 完成）。
 - 已应用：备份并替换 `logback-spring.xml`，已添加异步文件与错误文件 appender（步骤 1 完成）。
 - 已应用：新增 `RequestLoggingFilter`（`api-springboot/src/main/java/work/baiyun/chronicdiseaseapp/filter/RequestLoggingFilter.java`），记录请求开始/结束、耗时及慢请求告警（步骤 2 完成）。
 - 已应用：新增 `RequestLoggingFilter`（`api-springboot/src/main/java/work/baiyun/chronicdiseaseapp/filter/RequestLoggingFilter.java`），记录请求开始/结束、耗时及慢请求告警（步骤 2 完成）。
 - 已应用：新增 `LoggingAspect`（`api-springboot/src/main/java/work/baiyun/chronicdiseaseapp/aop/LoggingAspect.java`），记录 Controller 入参/出参（脱敏）、耗时与慢方法告警（步骤 3 完成）。
 - 已应用：新增 `LoggingAspect`（`api-springboot/src/main/java/work/baiyun/chronicdiseaseapp/aop/LoggingAspect.java`），记录 Controller 入参/出参（脱敏）、耗时与慢方法告警（步骤 3 完成）。
 - 已应用：修正 `build-and-run.bat`，脚本现在会切换到脚本目录（`api-springboot`）再执行 Maven 和启动命令，避免在仓库根目录运行导致的错误（脚本修正完成）。

**9. 下一步（我可以代劳）**
- 我可以帮你逐项生成补丁：修改 `pom.xml`、替换 `logback-spring.xml`、新增 `RequestLoggingFilter`、`LoggingAspect`、`LogDesensitizeAppender` 草稿，并运行静态检查；是否现在开始按照建议顺序生成这些补丁？

---

文档生成时间：2025-12-22  本文为补丁与评估记录，后续补丁进展会以 TODO 列表同步更新。