http.Error不适合统一错误处理，因其只能写死状态码和文本，无法携带错误码、业务上下文、本地化消息，且调用后立即写响应并关闭连接，阻断后续中间件或defer执行；真实项目需记录带trace ID的日志、返回含code/message的JSON、错误降级等，均无法实现。
为什么 http.Error 不适合做统一错误处理
它只能写死状态码和文本，无法携带错误码、业务上下文、本地化消息，且一调用就直接写响应体并关闭连接，后续中间件或 defer 都无法干预。真实项目里你经常需要：记录错误日志时带上 trace ID、返回 JSON 格式含 code 和 message 字段、对某些错误降级返回默认值——这些 http.Error 做不到。
定义可序列化的错误类型：用结构体代替字符串
不要用 errors.New 或 fmt.Errorf 直接抛裸错误。定义一个实现 error 接口的结构体，包含 Code（int）、Message（string）、Details（map[string]interface{}）等字段。关键点：
-
Code必须全局唯一且语义明确，比如1001表示“用户未登录”，2003表示“订单不存在”——不建议用 HTTP 状态码直接当业务码 - 重写
Error()方法，只返回Message，避免日志里刷出大段 JSON - 提供
WithDetail(key, value)方法，方便在 handler 里动态附加请求参数、SQL 错误等调试信息
中间件拦截 panic 和 error 并标准化输出
在路由最外层加一层中间件，统一捕获两类异常：
- 显式返回的
*AppError类型错误（比如从 service 层 return 上来的） - 未预期的 panic（如空指针、数组越界），用
recover()捕获后转为500-INTERNAL_ERROR级别的*AppError
该中间件决定最终响应格式：HTTP 状态码映射靠 AppError.Code 查表（如 1001 → 401，5001 → 500），Body 固定为：
{"code":1001,"message":"用户未登录","details":{}}。注意别把敏感字段（如数据库密码、token 原文）塞进 Details。
立即学习“go语言免费学习笔记（深入）”；
错误码分配容易踩的三个坑
团队协作时，错误码乱用比没错误码更糟：
- 不同模块用同一错误码表示不同含义（比如支付模块和用户模块都用
2001，但一个是“余额不足”，一个是“手机号格式错误”）——解决办法：按域分段，如用户域 1xxx，订单域 2xxx，支付域 3xxx - 把错误码硬编码在 handler 里，导致散落各处难以维护——应集中定义在
pkg/error/code.go，用 const 声明，生成文档时可自动提取 - 忽略客户端兼容性，上线后随意改已有错误码的含义或 message 文本——message 可以国际化替换，但
Code和语义一旦发布就不能变
真正难的不是设计一套规范，而是让所有人每次新增错误时，都去查表、填文档、跑 CI 检查码是否重复——这得靠工具链卡住，而不是靠人盯。
