直接写ResponseWriter易出错，因未设Content-Type、忽略json.Marshal错误、状态码语义混乱；应封装JSONResponse函数，接收data、statusCode、可选message，避免全局变量复用w/req，框架中优先使用内置JSON方法。
Go HTTP handler 返回 JSON 时，为什么 json.Marshal 直接写 ResponseWriter 容易出错？
因为没设 Content-Type、没处理错误、没统一状态码语义，导致前端解析失败或调试困难。最常见的是返回空响应或 500 Internal Server Error 却没日志，实际是 json.Marshal 遇到不可序列化字段（比如 func 类型或未导出字段）直接 panic。
- 必须手动调用
w.Header().Set("Content-Type", "application/json; charset=utf-8")，否则部分客户端（如某些 Axios 版本）可能不识别为 JSON -
json.Marshal错误不能忽略：它返回([]byte, error)，error为nil才能安全写入w.Write - HTTP 状态码应由业务逻辑决定，不是所有成功都该用
200；例如创建资源推荐201 Created，无内容响应用204 No Content
封装一个通用的 JSONResponse 函数，需要覆盖哪些关键参数？
核心就三个：响应体数据、HTTP 状态码、可选的自定义消息。不要塞进「code」「msg」「data」三层嵌套逻辑——那是业务协议，不是传输层封装。真正的封装只管序列化、头设置、错误透出。
-
data interface{}：要序列化的值，支持 struct、map、slice，但需确保字段可导出（首字母大写） -
statusCode int：显式传入，不硬编码200，避免掩盖语义（如404和200 { "code": 404 }是两回事） -
message string（可选）：仅用于调试或开发环境，生产环境建议关闭，避免泄露内部信息 - 别在封装里做日志记录——日志应由 handler 上层或中间件统一处理
为什么不要用全局变量或单例来存 ResponseWriter 或 Request？
因为 Go 的 HTTP handler 是并发安全的，每个请求都有独立的 http.ResponseWriter 和 *http.Request 实例。一旦你把它们存到包级变量或结构体字段里，多个 goroutine 会竞争修改，轻则响应错乱（A 请求拿到 B 的 body），重则 panic。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 所有响应操作必须在 handler 函数作用域内完成，
JSONResponse(w, data, 200)的w必须是当前 handler 入参的那个 - 如果想复用逻辑，用闭包或函数参数传递，而不是绑定到结构体上
- 常见翻车点：
type API struct { w http.ResponseWriter }—— 这个结构体不能跨请求复用
在 Gin / Echo 等框架里，还能用原生 JSONResponse 封装吗？
可以，但没必要。Gin 的 c.JSON(statusCode, obj) 和 Echo 的 c.JSON(statusCode, obj) 已经做了头设置、错误检查和基础 panic 捕获。强行再包一层容易干扰框架的错误处理链（比如 Gin 的 c.AbortWithStatusJSON）。
立即学习“go语言免费学习笔记（深入）”；
- 如果你用的是 Gin，直接用
c.JSON(200, resp)，别自己调json.Marshal+w.Write - 如果要用自定义结构（比如统一加
timestamp字段），建议用中间件注入公共字段，或定义返回 struct，而不是改写底层 JSON 写法 - 框架封装的
JSON方法默认不格式化输出（no indent），若需调试可用c.IndentedJSON，但线上禁用——多出来的空格和换行会增加带宽和解析开销
真正难的不是怎么封装 JSON，而是什么时候不该封装：比如流式响应（SSE）、文件下载、二进制上传，这些场景根本不该走统一 JSON 路线。还有就是错误处理路径——500 响应是否要带 stack trace？这得看环境变量或配置开关，不是封装函数能自动判断的。
