---
name: logging
when: '日志记录, 日志, log, 打日志, 链路追踪, MDC, traceId, 日志格式, 记录日志, 操作日志'
scope:
  - backend
products:
  - '*'
id: ka-pattern-logging
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 日志记录
  - 日志
  - log
  - 打日志
  - 链路追踪
  - MDC
  - traceId
  - 日志格式
  - 记录日志
  - 操作日志
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 必须使用 SLF4J + Logback，禁止 System.out.println
- 所有请求必须有 traceId 贯穿完整链路（MDC Filter）
- 关键业务操作（创建/修改/删除）必须记录 INFO 日志
- 禁止日志中打印敏感信息（密码、token、身份证号），敏感字段必须脱敏
- ERROR 日志必须包含异常堆栈（log.error("msg", e)）
- 所有新增/修改/删除/审核/审批/发放/冻结/解冻等写操作必须有审计落点
- 审计至少包含：操作者、操作时间、操作对象、来源入口、关键前后值或结果摘要
- 关键路径（写操作、状态变更、外部调用、异常捕获）必须有日志，只读查询不得为满足规则而硬加日志
- 禁止在循环中打印日志（尤其是 DEBUG 级别），防止日志洪泛
- 异常日志必须包含完整堆栈（log.error("msg", exception)），禁止只打印 getMessage()
- 生产环境禁止使用 DEBUG/TRACE 级别日志

## 验收项
- [AC-01] 所有请求有 traceId 贯穿
- [AC-02] 关键操作记录 INFO 日志
- [AC-03] 日志不含敏感信息
- [AC-04] 无 System.out.println
- [AC-05] 写操作有审计记录（操作者/时间/对象/来源）
- [AC-06] 关键路径有日志且只读查询无冗余日志
- [AC-07] 关键操作有审计日志
- [AC-08] 日志包含 traceId
- [AC-09] 异常日志包含完整堆栈
