Go 服务如何建立 Request ID、结构化日志与敏感字段脱敏

日志不是 fmt.Println 的集合。一次请求可能经过鉴权、Service、Repository 和第三方 API，如果没有稳定的 Request ID 与字段规范，线上问题只能靠时间范围和关键词猜测。

Request ID 的入口

如果网关传入 X-Request-ID，服务沿用它；否则生成新的 ID。响应头返回同一个值，中间件把它放入 Context，后续日志都从 Context 获取。

访问日志记录什么

• request_id、method、path 和必要的 query

• status_code、latency、client_ip 与 user_agent

• 已经认证的 user_id、tenant_id 或 store_id

• 统一错误码与错误类型

业务日志记录决策

业务日志应描述状态变化，例如订单从 PAYING 进入 PAID、用户创建了使用记录、Token 刷新成功。不要重复输出完整请求体，也不要把数据库错误原样返回客户端。

敏感字段黑名单

authorization, token, access_token, refresh_token, session_key, password, secret, openid

对 openid 等仍有排查价值的标识，只保留固定前后缀。结构化日志的字段必须经过集中清洗，不能依赖每个业务开发者记得手动脱敏。

Panic 与错误分层

Recovery 中间件记录 stack、请求上下文和 Request ID，客户端只收到统一系统错误。参数错误、业务冲突和数据库故障使用不同错误码，便于告警和统计。

存储与轮转

• 按天生成日志文件

• 达到大小阈值后切割

• 限制备份数量与保留天数

• 压缩历史文件

• 生产环境可继续采集到集中日志平台

验收方式

为中间件添加测试：客户端自带 Request ID 时保持不变；敏感 Header 不进入日志；Panic 返回统一格式；同一次请求的访问日志和业务日志具有相同关联 ID。