应使用 statuserror 封装 http 状态码，统一返回带状态码的业务错误；定义 apperror 结构体规范 json 响应与日志字段；gorm 日志需分离慢查询与错误，并重定向至独立输出；log.setoutput 需线程安全且复用文件句柄。
用 statuserror 封装 http 状态码，避免 panic 处理业务错误
go 的错误哲学不鼓励用 panic 处理可预期的业务异常（比如参数校验失败、资源未找到），否则会干扰监控指标、掩盖真实调用链上下文。你应该让 handler 显式返回带状态码的错误。
定义一个轻量级的 StatusError 类型，把 HTTP 状态码和原始错误绑定：
type StatusError struct {
Status int
Err error
}
func (e *StatusError) Error() string {
return e.Err.Error()
}
- 所有业务 handler 改为返回
error，例如：return &StatusError{Status: 400, Err: errors.New("invalid user ID")} - 中间件中统一检查是否为
*StatusError，再调用w.WriteHeader(e.Status)并写入结构化响应 - 不要在中间件里对
nil错误做默认 500 处理——这会掩盖漏掉的错误返回
统一错误响应结构 + 日志上下文注入
客户端需要稳定字段解析，服务端需要可追溯的调试信息。二者不能割裂设计。
定义 AppError 作为 JSON 响应体，并确保每次记录日志时都携带相同字段：
type AppError struct {
Code int `json:"code"`
Message string `json:"message"`
Detail string `json:"detail,omitempty"`
TraceID string `json:"trace_id,omitempty"` // 来自 context 或 middleware 注入
}
-
Code是业务错误码（如1001表示用户不存在），不是 HTTP 状态码；HTTP 状态码由中间件根据Code映射决定（比如1001 → 404） - 日志写入前，从
context.Context中提取TraceID、UserID、ReqID等，用zap.String("trace_id", ...)或log.Printf格式化输出 - 别把敏感字段（如密码、token）打到日志里；用
log.SetFlags(log.Ldate | log.Ltime | log.Lshortfile)确保每条日志带时间与位置
GORM 慢查询与错误日志分离配置
GORM 默认日志会把 SQL 执行、错误、慢查询混在一起，不利于监控告警。你需要按级别拆开处理。
关键配置项必须显式设置：
- 启用慢查询检测：
SlowThreshold: 200 * time.Millisecond，超过即触发logger.Warn - 忽略“记录未找到”类噪音：
IgnoreRecordNotFoundError: true，否则First()查不到就报错，日志爆炸 - 生产环境禁用
ParameterizedQueries: false，防止 SQL 日志泄露参数值（如WHERE email = 'admin@x.com'） - 把 GORM 日志重定向到独立文件或
io.MultiWriter，别和应用主日志混流
log.SetOutput 多目标输出与线程安全陷阱
开发期想看控制台又存文件，上线后要对接 ELK 或 Loki，靠 log.SetOutput 切换最直接，但容易踩坑。
典型做法是用 io.MultiWriter 同时写终端和文件：
file, _ := os.OpenFile("app.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
multi := io.MultiWriter(os.Stdout, file)
log.SetOutput(multi)
- 文件句柄必须全局复用，不能每次写日志都
OpenFile—— 文件描述符会耗尽 -
log包本身是并发安全的，但如果你用log.SetOutput动态切换输出目标，需加锁，否则可能写乱 - 更稳妥的方式是封装一个自定义
io.Writer，内部用sync.Mutex保护 write 操作，再传给SetOutput
实际部署时，最常被忽略的是错误码与 HTTP 状态码的映射一致性：同一个业务错误，在 REST 接口返回 404，在 gRPC 端却返回 codes.NotFound，而日志里只记了 1001，没有自动关联。这种割裂会让排障变慢。
