统一错误结构体必须包含 code 和 message 字段，code 映射 HTTP 状态码，message 为简明提示，details 仅用于调试；错误应实现 StatusCoder 接口以避免字符串匹配；响应与日志内容须分离，禁止透出敏感信息。
统一错误结构体必须包含 status code 和 message 字段
Go 的 HTTP handler 本身不强制错误格式，但前端或调用方依赖可预测的 JSON 错误响应。硬编码 http.Error() 或直接 json.Marshal(map[string]string{"error": "xxx"}) 会导致字段不一致、缺失状态码、无法区分业务错误与系统错误。
推荐定义一个基础错误结构体，例如：
type ErrorResponse struct {
Code int `json:"code"`
Message string `json:"message"`
Details string `json:"details,omitempty"`
}
Code 应映射 HTTP 状态码（如 400、401、404、500），而非自定义错误码；Message 是面向调用方的简明提示；Details 仅用于调试或内部日志，生产环境应为空或脱敏。
不要在 handler 里用 panic 捕获并返回错误
用 recover() + http.Error() 包裹整个 handler 是常见反模式：它掩盖真实错误位置、丢失堆栈、无法区分预期错误（如参数校验失败）和意外 panic（如 nil pointer）。
立即学习“go语言免费学习笔记（深入）”；
正确做法是让业务逻辑返回明确的 error 类型，并由中间件或 handler 自上而下处理：
- 校验失败 → 返回
ErrValidation（实现status() int方法） - 资源未找到 → 返回
ErrNotFound，其status()返回 404 - 数据库超时 → 返回原生
*pq.Error或封装为ErrInternal
最终统一由一个 writeError(w http.ResponseWriter, err error) 函数序列化并写入响应，避免每个 handler 重复判断类型。
HTTP 状态码不能全靠 error 字符串匹配
有人会写 if strings.Contains(err.Error(), "not found") { writeJSON(w, 404, ...) } —— 这极脆弱：翻译、日志前缀、拼写变化都会导致失效。
更可靠的方式是让 error 实现接口：
type StatusCoder interface {
StatusCode() int
}
然后在 writeError 中判断：
if sc, ok := err.(StatusCoder); ok {
w.WriteHeader(sc.StatusCode())
} else {
w.WriteHeader(http.StatusInternalServerError)
}
这样 ErrNotFound、ErrBadRequest 等类型可各自控制状态码，无需字符串解析，也便于单元测试覆盖。
日志记录和响应内容必须分离
同一个错误，响应给前端的 Message 要简洁安全（如 “用户不存在”），而日志里要保留完整上下文（如 “user_id=123 not found in users table, query took 12ms”）。
常见错误是把 err.Error() 直接塞进响应 message，导致暴露路径、SQL 片段、内部服务名等敏感信息。务必检查所有 error 构造点：
- 使用
fmt.Errorf("failed to get user: %w", dbErr)而非fmt.Errorf("failed to get user: %v", dbErr) - 自定义 error 类型的
Error()方法只返回用户友好文本 - 真正原始错误（如
os.PathError）只进日志，不出现在 HTTP 响应中
最易被忽略的是第三方库返回的 error —— 它们往往带详细底层信息，直接透出就等于交出服务器部分控制权。
