如何使用Golang实现JSON接口_Golang JSON接口处理方法_技术教程

Go标准库encoding/json足以支撑绝大多数JSON接口开发，需正确使用struct标签、Content-Type头、错误处理及请求体大小限制。

Go 标准库的 encoding/json 足以支撑绝大多数 JSON 接口开发，无需额外框架也能写出清晰、健壮、可维护的 HTTP JSON 服务。

用 `json.Marshal` 和 `json.Unmarshal` 处理结构体序
列化

Go 的 JSON 编解码强依赖结构体标签（struct tags），尤其是 json tag。不加 tag 时字段名默认按首字母大写导出，且大小写必须完全匹配；加了 tag 才能控制字段映射关系、忽略空值或指定别名。

常见错误：忘记导出字段（小写开头）、tag 拼错（如写成 josn）、未处理指针或零值导致序列化异常。

字段必须首字母大写才能被 json.Marshal 导出
json:"name,omitempty" 表示该字段为空值（""、0、false、nil）时不参与序列化
json:"-" 表示完全忽略该字段
嵌套结构体需同样定义导出字段和 tag，否则子字段不会被编码

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email,omitempty"`
    Admin bool   `json:"is_admin"`
}

data, err := json.Marshal(User{ID: 123, Name: "Alice"})
// 输出：{"id":123,"name":"Alice","is_admin":false}

在 HTTP handler 中正确返回 JSON 响应

直接调用 json.Marshal 后用 w.Write 写入响应体是常见做法，但容易遗漏关键细节：Content-Type 头、错误处理、HTTP 状态码。

典型问题包括：没设 Content-Type: application/json 导致前端解析失败；panic 未捕获导致整个服务崩溃；错误响应没带状态码（如 400/500）让客户端无法区分成功与失败。

务必在 WriteHeader 前设置 Content-Type
对 json.Marshal 错误必须检查，不能忽略（如 struct 字段含不可序列化类型：func、chan、map[interface{}]string）
建议封装一个通用的 JSON 响应函数，统一处理 header、status、body

func writeJSON(w http.ResponseWriter, status int, v interface{}) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    if err := json.NewEncoder(w).Encode(v); err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }
}

func userHandler(w http.ResponseWriter, r *http.Request) {
    user := User{ID: 456, Name: "Bob"}
    writeJSON(w, http.StatusOK, map[string]interface{}{"data": user})
}

接收并校验 JSON 请求体（`json.Unmarshal` + `io.LimitReader`）

用 json.Decode(r.Body) 解析请求体是标准做法，但要注意：body 只能读一次；超大 payload 可能引发内存溢出；未校验字段可能导致业务逻辑异常。

容易被忽略的是请求体大小限制——攻击者可能发送 GB 级 JSON 触发 OOM。标准库不自动限流，必须手动控制。

使用 io.LimitReader(r.Body, maxBytes) 包裹原始 body，防止过载
解码前检查 Content-Type 是否为 application/json
对必填字段做空值判断（Unmarshal 不会报错，但字段可能为零值）
避免直接解码到 map[string]interface{}，除非确实需要动态结构；优先用具名结构体便于 IDE 提示和类型安全

const maxBodySize = 1 << 20 // 1MB

func createUserHandler(w http.ResponseWriter, r *http.Request) {
    if r.Header.Get("Content-Type") != "application/json" {
        http.Error(w, "Content-Type must be application/json", http.StatusBadRequest)
        return
    }

    limitedBody := io.LimitReader(r.Body, maxBodySize)
    var req struct {
        Name  string `json:"name"`
        Email string `json:"email"`
    }
    if err := json.NewDecoder(limitedBody).Decode(&req); err != nil {
        http.Error(w, "Invalid JSON", http.StatusBadRequest)
        return
    }
    if req.Name == "" || req.Email == "" {
        http.Error(w, "name and email are required", http.StatusBadRequest)
        return
    }
    // ... 处理业务逻辑
}

注意 `time.Time`、`nil` slice 和嵌套 `interface{}` 的 JSON 行为

Go 的 JSON 默认对 time.Time 序列化为 RFC3339 字符串（如 "2025-05-20T14:30:00Z"），但反序列化时需显式指定格式，否则会失败；空 slice 会被编码为 []，而 nil slice 编码为 null —— 前端常期望统一行为；interface{} 在解码时会变成 map[string]interface{}、[]interface{} 或基础类型，类型断言易出错。

若需自定义时间格式（如 Unix 时间戳），应实现 MarshalJSON/UnmarshalJSON 方法
用 omitempty 时，nil slice 和空 slice 表现不同，需明确业务语义
避免在结构体中混用 interface{} 和具体类型；如必须用，解码后尽早转为确定类型并验证
第三方库如 github.com/mitchellh/mapstructure 可辅助 map[string]interface{} → struct 转换，但增加依赖

最常踩的坑是：把 nil slice 当作空 slice 使用，或在前端传 null 给非指针字段导致解码失败 —— 这类问题往往在联调后期才暴露，调试成本高。