上线之后，用户说“相册打不开了”，怎么排查？

第一反应不能是猜

“打不开”不是一个具体错误。

上线后必须具备 发现问题 + 定位问题 + 恢复服务

日志

日志不是随手写一句 fmt.Println。

日志的目的不是“证明代码执行过”，而是让你在故障发生后能回答：谁、什么时候、访问了什么、用了多久、失败在哪里。

Request ID

一次请求经过多个组件，需要一个统一标识。

如果每一层日志都没有共同字段，就很难把它们串成同一次请求。request_id 就是这条链路的线索。

{
  "code": "INTERNAL_ERROR",
  "message": "服务暂时不可用",
  "requestId": "abc123"
}

Gin 中间件

日志中间件负责统一记录请求上下文。

不要在每个 Handler 里手写一套日志。请求开始、请求结束、状态码、耗时、用户身份和错误信息，都适合由中间件统一处理。

AI 可以实现日志中间件，但字段设计和敏感信息边界必须由开发者决定。

健康检查

存活检查和就绪检查不是一回事。

监控指标

不要等用户反馈，系统应该先告诉你异常。

平均响应时间正常，不代表所有用户都正常。P95、P99 可以帮助你看到尾部慢请求，而不是只看“平均还行”。

分层排查

前端错误和后端错误要分开看。

不要一上来就改代码。先确认请求有没有发出、发到哪里、返回什么、哪个组件记录了异常。

错误信息分层

错误不能只打印，也不能直接返回内部细节。

{
  "code": "INTERNAL_ERROR",
  "message": "服务暂时不可用",
  "requestId": "abc123"
}

request_id=abc123
path=/api/my/albums
user_id=1001
error=mysql connection timeout

用户需要稳定、可理解的信息；开发者需要完整上下文。不要把数据库错误、SQL、密钥、签名 URL 直接暴露给用户。

Panic 与 Recovery

Recovery 是防止单次异常拖垮服务，不是掩盖缺陷。

Recovery 中间件保护进程稳定性，但 panic 仍然代表代码存在严重路径，需要追踪和修复。

发布版本信息

线上报错时，要知道当前运行的是哪一个版本。

没有版本信息，就很难判断问题是否由刚发布的代码引起，也很难确认回滚是否生效。

{
  "version": "1.3.0",
  "commit": "a8f921c",
  "buildTime": "2026-07-17T10:30:00+08:00",
  "env": "prod"
}