DockerAPI

阅读提示

• 适用版本：Go 1.21+（示例在 Go 1.22 下验证）· 前置知识：标准库-net · 阅读时长：约 15 分钟

文档：Develop with Docker Engine SDKs | Docker Documentation

DockerAPI是Docker的SDK，以编程的方式与Docker进行交互，例如拉取镜像，运行容器，这个文档只是简单的讲解如何去使用DockerAPI，在官方文档中对每一个API有着更详细的解释。官方API只有Go和Python版本，并且Docker本身也支持HTTP进行交互，如果是其他语言的话可以使用第三方社区开源的SDK，本教程将采用Go语言进行讲解。

安装

使用Go Get 安装Docker Client。

go get github.com/docker/docker/client

完整示例

下面的程序可以直接运行：复制到文件后执行 go run main.go，或粘贴到 Go Playground 运行。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// Docker Engine API 使用带版本号的路径与查询过滤器
	filters := url.Values{}
	filters.Set("status", "running")

	path := "/v1.43/containers/json"
	escaped := url.QueryEscape(`{"status":["running"]}`)
	fmt.Println("request:", path+"?filters="+escaped)
	fmt.Println("simple filters:", filters.Encode())
}

预期输出：

request: /v1.43/containers/json?filters=%7B%22status%22%3A%5B%22running%22%5D%7D
simple filters: status=running

常见错误与踩坑

• 先协商 API 版本。 调用 client.NegotiateAPIVersion（或显式传入版本），不要硬编码 daemon 可能不支持的版本。
• 遵守环境配置。 DOCKER_HOST、TLS 与 context 应由 client.FromEnv 读取。
• 每个操作都传带超时的 context。 daemon 繁忙时容器操作可能长时间挂起。
• 处理类型化错误。 使用客户端提供的 errdefs/IsErrNotFound 等辅助函数，而不是比对错误字符串。
• 生产环境不要手拼 URL。 官方客户端方法会处理版本、编码与流式响应。

更新记录

• 2026-10-14：新增"阅读提示"、完整可运行示例（含预期输出）、常见错误与踩坑清单，以及本更新记录。