应避免在http handler中直接调用http.error，改用自定义writeerror函数统一返回json格式错误（如{“code”:400,”message”:”xxx”,”trace_id”:”abc”}），并配合中间件兜底处理panic和未捕获错误。
HTTP handler里直接写http.Error会破坏统一错误格式
Go标准库的http.Error强制返回纯文本或固定HTML，没法嵌入code、message、details等JSON字段。一旦项目要求所有API错误都走{"code":400,"message":"xxx","trace_id":"abc"}这种结构，用http.Error就等于主动放弃一致性。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 别在handler里调
http.Error，改用自定义的writeError函数，统一设置Content-Type: application/json和状态码 - 错误结构体必须导出字段，且加
jsontag，比如Code int `json:"code"`，否则json.Marshal输出空对象 - 避免在错误响应里暴露敏感信息（如数据库错误详情），生产环境应只返回预设的用户友好提示
用net/http中间件统一拦截panic和未处理错误
手动在每个handler里defer/recover太重复，也容易漏。中间件能兜底捕获panic，并把业务层抛出的error转成标准JSON响应。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 中间件里
defer捕获panic后，记录日志并返回500 Internal Server Error，不要把panic堆栈吐给前端 - 业务handler内部该
return就return，别用os.Exit或log.Fatal，否则整个服务挂掉 - 中间件判断
err != nil时，优先检查是否是自定义错误类型（比如实现了ErrorResponse()方法的接口），再 fallback 到通用错误
json.Marshal对nil指针和零值字段的处理很关键
如果错误结构体里有*string字段，又没初始化，json.Marshal会序列化成null；而int字段为0会被当成有效值输出，可能和“未设置”语义混淆。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 错误结构体字段尽量用值类型（
int、string），避免指针，除非明确需要区分“未设置”和“设为空字符串” - 用
omitemptytag控制零值字段不输出：Details map[string]string `json:"details,omitempty"` - 测试时故意传
nilerror进响应函数，确认不会panic ——json.Marshal(nil)返回null，但有些老版本Go在特定场景下会panic
HTTP状态码和JSON里的code字段别混用
HTTP状态码（如404）是协议层概念，告诉客户端“资源不存在”；JSON里的"code"是业务层约定，比如"USER_NOT_FOUND"或1002。两者语义不同，不能互相替代。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 状态码决定客户端是否重试、缓存、跳转，必须严格按RFC：4xx表示客户端错，5xx表示服务端错，别用
200配错误JSON - JSON
code字段用于前端分支逻辑或运维排查，建议用字符串枚举（如"invalid_param"），比数字更易维护 - 别在中间件里硬编码映射表（比如
map[int]string{400: "bad_request"}），状态码和业务code的关联应在错误构造时由业务方决定
最麻烦的是跨团队协作时，前端按code写switch，后端悄悄改了字段名或类型，JSON key一错，前端就收不到提示。所以错误结构体定义要进共享SDK，而不是每个服务自己写一遍。