如何在 Go 中正确等待并处理 Docker API 的流式 JSON 响应

Go 中发起 Docker 的 POST 拉取镜像请求时，若直接用 json.NewDecoder.Decode() 仅读取一次，会提前终止连接，导致镜像拉取不完整；需循环解码流式响应体，直到 EOF 或错误发生。

Go 中发起 Docker 的 POST 拉取镜像请求时，若直接用 `json.NewDecoder.Decode()` 仅读取一次，会提前终止连接，导致镜像拉取不完整；需循环解码流式响应体，直到 EOF 或错误发生。

Docker 的 /images/create 接口，返回的并不是一个完整的 JSON 数组或单个 JSON 对象，而是逐行输出的 JSON 流（JSON Lines）：每一行，都是一个独立的 JSON 对象。说白了，这就是一种典型的服务器推送式流式响应（带有 Server-Sent Events 的风格），很适合用来承载这类耗时任务的进度反馈，比如镜像拉取、镜像构建这类过程。

问题就出在这里：原代码里的 json.NewDecoder(resp.Body).Decode(&pullresbody) 只做了一次解码，也就是说，它读到第一条 {"status":"Pulling from..."} 之后就停下来了。后面持续返回的响应内容没有继续消费，等于被直接丢掉；与此同时，连接还会随着 resp.Body.Close()（不管是显式调用还是隐式触发）被关闭，结果就是 Docker 后端把这次拉取流程中途掐断了。

✅ 正确做法是：持续调用 decoder.Decode() 直到返回 io.EOF（表示流结束）或其它错误。注意需手动管理解码循环，并妥善处理各类错误（网络中断、解析失败、服务端异常等）。

以下是修复后的完整示例：

func PullImage(imagename string, uuid string) error {
logFields := log.Fields{
"handler": "PullImage",
"uuid":uuid,
}

log.WithFields(logFields).Debugf("imagename: %v", imagename)

url := fmt.Sprintf("https://%s/images/create?fromImage=%s", sconf.Docker.Endpoint, url.QueryEscape(imagename))
req, err := http.NewRequest("POST", url, nil)
if err != nil {
log.WithFields(logFields).Errorf("Failed to create request: %v", err)
return fmt.Errorf("failed to create request: %w", err)
}
req.Header.Set("Content-Type", "application/json")

resp, err := client.Do(req)
if err != nil {
log.WithFields(logFields).Errorf("HTTP request failed: %v", err)
return fmt.Errorf("HTTP request failed: %w", err)
}
defer resp.Body.Close() // ✅ 必须确保 Body 被关闭

if resp.StatusCode = 300 {
log.WithFields(logFields).Errorf("Docker API returned status %d", resp.StatusCode)
return fmt.Errorf("Docker API error: status %d", resp.StatusCode)
}

// 使用 json.Decoder 持续读取流式响应
dec := json.NewDecoder(resp.Body)
var pullEvent map[string]interface{} // 动态结构，适配不同事件字段

for {
err := dec.Decode(&pullEvent)
if err == io.EOF {
log.WithFields(logFields).Info("Image pull completed successfully")
break // ✅ 正常结束
}
if err != nil {
// 区分临时错误与致命错误（如 malformed JSON）
if errors.Is(err, io.ErrUnexpectedEOF) || strings.Contains(err.Error(), "invalid character") {
log.WithFields(logFields).Warnf("Malformed JSON event (likely partial response): %v", err)
continue // 可选：跳过损坏行，继续下一条
}
log.WithFields(logFields).Errorf("JSON decode error: %v", err)
return fmt.Errorf("failed to decode pull event: %w", err)
}

// 日志记录 & 业务逻辑处理（例如提取 status/id/progress）
status, _ := pullEvent["status"].(string)
id, _ := pullEvent["id"].(string)
log.WithFields(logFields).Infof("Pull event: status=%q, id=%q", status, id)

// ✅ 可在此处添加状态判断（如检测 "Pull complete" 或 "Downloaded newer image"）
if status == "Pull complete" || strings.Contains(status, "Downloaded newer image") {
log.WithFields(logFields).Info("Final pull status detected")
}
}

return nil
}

? 关键注意事项：

• 必须 defer resp.Body.Close()：避免连接泄漏，尤其在长轮询场景下至关重要；
• URL 参数需 URL 编码：fromImage=imagename 中的 imagename 可能含特殊字符（如 /, :），应使用 url.QueryEscape(imagename)；
• 不要忽略 StatusCode：Docker API 出错时（如镜像不存在）可能返回 404 或 500，但响应体仍为 JSON 流，需前置校验；
• io.EOF 是正常终止信号，不是错误；其他错误（如网络超时、json.SyntaxError）需明确处理；
• 若需强类型解析，可定义结构体（如 type PullEvent struct { Status stringjson:"status"; ID stringjson:"id"; ProgressDetail map[string]interface{}json:"progressDetail"}），但需容忍部分字段缺失（Docker 返回字段动态变化）；
• 生产环境建议添加上下文（context.Context）支持超时与取消，防止无限阻塞。

通过循环解码流式响应，Go 程序才能真正“等待 POST 完成”，与 curl 行为对齐，确保 Docker 镜像拉取可靠执行。