应使用 json.NewEncoder(w).Encode(v) 直接写 JSON，需先设置 Content-Type；它流式编码、自动错误传播、避免内存分配，而手动 Marshal+Write 易漏设类型、忽略写错、导致截断或空响应。
用 json.NewEncoder 直接写 JSON 到 ResponseWriter 最稳妥
Go 的 HTTP 处理函数里，直接调用 json.NewEncoder(w).Encode(v) 是返回 JSON 响应的推荐做法，不是“可以”，而是“应该”。它自动处理流式写入、HTTP 状态码未设置时的默认 200、以及底层 io.Writer 的错误传播——比先 json.Marshal 再 w.Write 少三处易错点。
常见错误现象：http: request body too large（其实和 body 无关）、http: Handler returned error 但没看到 panic、前端收空响应或截断 JSON。这些往往是因为手动 json.Marshal 后忘了设 Content-Type，或 Write 失败却没检查返回值。
-
json.NewEncoder写失败会立刻返回 error，你能在 handler 里捕获并记录，而Marshal+Write容易忽略Write的n, err中的err - 必须在
Encode前设置Content-Type：w.Header().Set("Content-Type", "application/json; charset=utf-8") - 如果
v是 nil 或含不可序列化字段（如func、chan），Encode会返回json.UnsupportedTypeError，别假设数据一定干净
json.Encoder 和 json.Marshal 性能与内存差异在哪
核心区别不在“快慢”，而在“谁分配内存”和“何时暴露错误”。json.Marshal 必须把整个 JSON 字节切片一次性分配在堆上；json.NewEncoder 把结构体字段逐个 encode 到 ResponseWriter 的底层连接缓冲区，不额外分配大块内存。
使用场景：API 返回几百 KB 以上数据（比如导出列表）、低内存容器环境、高并发小响应体服务——后者尤其受益于 encoder 避免的临时切片分配。
立即学习“go语言免费学习笔记（深入）”；
-
json.Marshal错误只在序列化完成时才返回，可能已浪费 CPU 和 GC 压力；Encode在第一个字段失败就停，更快 fail-fast - 若需对 JSON 做 post-process（比如加签名、替换字段），只能用
Marshal；但这类需求应在业务层做，不该塞进 HTTP handler - 注意：
ResponseWriter可能是http.Hijacker或其他 wrapper，某些中间件（如 gzip）依赖WriteHeader调用时机，Encode不会自动触发WriteHeader，仍要自己调w.WriteHeader(statusCode)（默认 200 不用显式写）
为什么 Encode 后还报 “http: response wrote more than the declared Content-Length”
这错误只发生在你手动设置了 Content-Length header，又用 json.NewEncoder 写响应时。Go 的 http.Server 检测到实际写出字节数 ≠ 声明的 Content-Length，就强制关闭连接并报这个错。
根本原因：JSON 编码结果长度在运行时才能确定，你不可能提前算准（尤其含中文、浮点数精度、嵌套结构）。所以——永远不要手动设 Content-Length。
- 删掉所有类似
w.Header().Set("Content-Length", strconv.Itoa(len(data)))的代码 - 让 Go 自动处理：不设
Content-Length，它会用 chunked encoding（HTTP/1.1）或直接流式传输（HTTP/2） - 如果你在中间件里包装了
ResponseWriter并缓存了输出，确保它实现了Flusher和正确透传WriteHeader，否则 encoder 可能写到假 buffer 里
struct 字段没被 JSON 序列化？检查 json: tag 和导出规则
Go 的 json 包只序列化首字母大写的导出字段，且受 json: tag 控制。一个字段没出现在响应里，90% 是因为没导出或 tag 写错。
典型错误：用 type User struct { name string }（小写 name），或者 UpdatedAt time.Time `json:"updated_at"` 但 UpdatedAt 是零值，又没加 omitempty 导致字段为 null 被前端忽略（其实是写了，只是值是 null）。
- 字段名必须首字母大写，例如
Name string，不是name string -
json:"-"完全忽略字段；json:",omitempty"在零值时跳过（注意：指针 nil、字符串 ""、切片 nil/len=0、数字 0 都算零值） - 时间字段建议用
time.Time+json:"created_at" time_format:"2006-01-02T15:04:05Z"，否则默认输出带时区的长字符串 - 如果用了自定义 marshaler（如实现
MarshalJSON()方法），确保它不 panic 且返回合法 JSON 字节，否则Encode会失败
Content-Type 设置和字段导出规则，这两处一错，前端连请求都看起来“成功”但拿不到数据。 
