如何在Golang中实现JSON API接口_Golang JSON数据解析与返回示例_技术教程

Go中返回JSON需手动调用json.Marshal并设Content-Type；解析请求体要用json.Unmarshal配合类型安全结构体；大响应推荐json.Encoder流式编码；结构体字段应合理使用omitempty标签控制零值输出。

用 `json.Marshal` 和 `http.ResponseWriter` 返回 JSON 响应

Go 标准库不自动序列化结构体为 JSON，必须显式调用 json.Marshal，再手动写入响应体。常见错误是忘记设置 Content-Type: application/json，导致前端解析失败或浏览器直接下载文件。

关键点：

务必在 WriteHeader 或 Write 前调用 w.Header().Set("Content-Type", "application/json")
json.Marshal 返回 []byte 和 error，不能忽略错误（如含不可序列化字段的 struct）
避免直接拼接字符串返回 JSON，既不安全也不符合标准

func handler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    data := map[string]interface{}{
        "id":   123,
        "name": "alice",
        "tags": []string{"go", "api"},
    }
    b, err := json.Marshal(data)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    w.WriteHeader(http.StatusOK)
    w.Write(b)
}

用 `json.Unmarshal` 解析请求体中的 JSON 数据

HTTP 请求体（如 POST/PUT）的 JSON 数据需手动读取并反序列化。容易出错的地方包括：未限制读取长度、未检查 Content-Type 头、未处理空 body 或非法编码。

建议做法：

立即学习“go语言免费学习笔记（深入）”；

先检查 r.Header.Get("Content-Type") 是否包含 application/json
用 io.LimitReader(r.Body, 1048576) 限制最大读取 1MB，防内存耗尽
用 json.Unmarshal 解析到预定义结构体（而非 map[string]interface{}），利于类型安全和字段校验

type UserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

func createUser(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
    }

    var req UserRequest
    decoder := json.NewDecoder(io.LimitReader(r.Body, 1048576))
    if err := decoder.Decode(&req); err != nil {
        http.Error(w, "Invalid JSON", http.StatusBadRequest)
        return
    }

    // 处理业务逻辑...
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(map[string]string{"status": "created"})
}

用 `json.Encoder` 替代 `json.Marshal` 避免中间字节切片

当响应数据较大（如列表导出、日志流）时，json.Marshal 会先全部加载进内存再写入，可能触发 GC 或 OOM。此时应直接用 json.NewEncoder(w).Encode(v) 流式编码。

注意：

json.Encoder 会自动处理 http.ResponseWriter 的写入，但不会自动设 Content-Type，仍需手动设置
它对 error 的处理更“静默”——失败时只返回 error，不自动中断响应，需显式检查
不适用于需要修改 JSON 字节后再发送的场景（如加签名、压缩）

func listItems(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")

    items := []map[string]string{
        {"id": "1", "title": "first"},
        {"id": "2", "title": "second"},
    }

    enc := json.NewEncoder(w)
    if err := enc.Encode(items); err != nil {
        // 此处 err 可能是写入失败（如客户端断连），需记录但通常不重试
        log.Printf("encode error: %v", err)
    }
}

结构体字段标签与零值处理：为什么 `omitempty` 很关键

Go 的 JSON 序列化默认导出所有字段，但空字符串、零值数字、nil 切片等常不希望出现在响应中。这时必须用 json:"field,omitempty" 标签控制。

典型陷阱：

忘记加 omitempty 导致前端收到 "count": 0 或 "name": ""，误判为有效值
混用指针字段（如 *string）和 omitempty，结果字段完全消失，调试困难
omitempty 对布尔字段无效（false 总被忽略），需用 *bool 或自定义 MarshalJSON

type ApiResponse struct {
    ID     int64  `json:"id"`
    Name   string `json:"name,omitempty"`      // 空字符串时不出现
    Count  int    `json:"count,omitempty"`     // 0 时不出现
    Tags   []string `json:"tags,omitempty"`    // nil 或空切片时不出现
    Active *bool  `json:"active,omitempty"`    // 只有非 nil 才序列化
}