Go的encoding/json包轻量高效，解析JSON需避免Body重复读取、显式设Content-Type和状态码，用指针处理可选字段，注意结构体导出与标签匹配，时间字段需特殊处理。
Go 的 encoding/json 包足够轻量、高效，且原生支持结构体标签控制序列化行为——只要结构体字段可导出（首字母大写），就能直接用 json.Marshal 和 json.Unmarshal 处理请求与响应，无需第三方库。
如何正确解析 HTTP 请求中的 JSON 数据
常见错误是直接对 *http.Request.Body 多次读取：Body 是单次读取流，第二次调用 io.ReadAll 会返回空字节或 EOF。必须在解析前确保只读一次，并注意 Content-Type 是否为 application/json。
实操建议：
- 用
http.MaxBytesReader包裹r.Body防止恶意大 payload（例如限制 1MB） - 先检查
r.Header.Get("Content-Type")是否包含"application/json"，避免非 JSON 请求 panic - 用
json.NewDecoder(r.Body).Decode(&v)替代json.Unmarshal(io.ReadAll(...))，更省内存 - 结构体字段必须导出（大写开头），且带上
json:"field_name"标签明确映射关系
type UserRequest struct {
Name string `json:"name"`
Email string `json:"email"`
Age int `json:"age,omitempty"`
}
func handler(w http.ResponseWriter, r *http.Request) {
if r.Method != "POST" || !strings.Contains(r.Header.Get("Content-Type"), "application/json") {
http.Error(w, "invalid content type", http.StatusBadRequest)
return
}
var req UserRequest
decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1024*1024))
if err := decoder.Decode(&req); err != nil {
http.Error(w, "invalid json: "+err.Error(), http.StatusBadRequest)
return
}
// 处理 req...
}
如何构造带状态码和标准格式的 JSON 响应
不要手动拼接 json.Marshal 后用 w.Write 输出——容易遗漏 Content-Type 头或状态码错位。Go 的 http.ResponseWriter 必须在写 body 前设置状态码，且默认是 200 OK。
立即学习“go语言免费学习笔记（深入）”；
实操建议：
- 始终显式调用
w.Header().Set("Content-Type", "application/json; charset=utf-8") - 需要非 200 响应时，**必须在
json.NewEncoder(w).Encode()之前**调用w.WriteHeader(statusCode) - 避免用
fmt.Fprintf(w, ...)输出 JSON 字符串，无法自动处理转义和编码 - 考虑封装一个通用响应函数，统一处理 success/error 结构
type APIResponse struct {
Success bool `json:"success"`
Data interface{} `json:"data,omitempty"`
Error string `json:"error,omitempty"`
}
func writeJSON(w http.ResponseWriter, statusCode int, v interface{}) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(statusCode)
json.NewEncoder(w).Encode(v)
}
// 使用示例：
writeJSON(w, http.StatusOK, APIResponse{Success: true, Data: user})
writeJSON(w, http.StatusUnprocessableEntity, APIResponse{Success: false, Error: "email invalid"})
如何处理嵌套 JSON、空值与缺失字段
前端传来的 JSON 经常字段不全、有 null 或嵌套对象为空，而 Go 结构体默认零值（如 string 为 ""，int 为 0）可能掩盖真实意图。这时不能只依赖 omitempty，得用指针或自定义类型控制解码逻辑。
实操建议：
- 对可选字段使用指针类型（如
*string,*int），null 或缺失时值为nil -
omitempty只跳过零值，不跳过nil指针；若想把nil指针也忽略，需额外处理 - 嵌套结构体字段也必须导出，否则内部字段无法被解码
- 用
json.RawMessage延迟解析不确定结构的字段（如 webhook payload 中的payload）
type OrderRequest struct {
ID int64 `json:"id"`
Items []Item `json:"items"`
Meta *RawMeta `json:"meta,omitempty"` // nil 表示未提供
Config json.RawMessage `json:"config,omitempty"` // 不立即解析
}
type Item struct {
Name string `json:"name"`
Count int `json:"count"`
}
type RawMeta struct {
Tags []string `json:"tags"`
Score *float64 `json:"score,omitempty"` // 可为 null 或缺失
}
为什么有时候 JSON 解码失败但没报错？
最常见原因是字段名大小写不匹配 + 缺少 json: 标签。Go 结构体字段小写（如 userName）即使加了 json:"user_name"，如果漏写标签，解码器仍按字段名 userName 去找 JSON key，导致静默失败（字段保持零值）。
另一个隐蔽问题是时间字段：JSON 中的 "2024-01-01T12:00:00Z" 默认无法直接解码进 time.Time，除非结构体字段类型为 time.Time 且注册了自定义 UnmarshalJSON 方法，或使用字符串暂存后手动解析。
排查建议：
- 打印解码后的结构体变量，确认字段是否为预期值，而非零值
- 用
json.Unmarshal([]byte(jsonStr), &v)在单元测试中单独验证结构体定义 - 对时间字段，优先用
string接收，再用time.Parse转换；或使用github.com/lib/pq等已实现UnmarshalJSON的类型 - 启用
json.Decoder.DisallowUnknownFields()捕获 JSON 中存在但结构体未定义的字段（开发期很有用）
结构体标签拼写错误、Body 重复读取、状态码写晚了、时间字段没处理——这几个点在上线后最容易引发静默异常或 HTTP 协议错误，比功能逻辑更值得花时间写测试覆盖。
