本文介绍如何使用 Docker 官方维护的 engine-api 库（现整合进 docker/docker 代码库）对接 Docker Engine Remote API v1.24，快速构建类型安全、符合规范的 Go 管理程序。
本文介绍如何使用 docker 官方维护的 `engine-api` 库（现整合进 `docker/docker` 代码库）对接 docker engine remote api v1.24，快速构建类型安全、符合规范的 go 管理程序。
Docker 自 v1.13 起将原独立的 engine-api 客户端库逐步迁移并整合至主仓库 docker/docker 中，其类型定义与客户端逻辑已作为 github.com/docker/docker/api/types 和 github.com/docker/docker/client 模块对外发布。这意味着——你不再需要寻找第三方封装库，而是直接使用 Docker 官方提供的、与 API 版本严格对齐的 Go SDK。
对于目标 API 版本 v1.24（对应 Docker Engine 1.12），推荐使用兼容该版本的 docker/client 客户端，并显式指定 API 版本以确保类型与行为一致性。以下是一个获取 Swarm 服务列表的完整示例：
package main
import (
"context"
"fmt"
"log"
"github.com/docker/docker/api/types"
"github.com/docker/docker/client"
)
func main() {
// 创建客户端，指定 API 版本为 1.24（格式：v1.24）
cli, err := client.NewClientWithOpts(
client.WithHost("tcp://10.0.1.10:2376"),
client.WithAPIVersionNegotiation(), // 启用版本协商（推荐）
client.WithVersion("1.24"), // 或强制锁定版本
)
if err != nil {
log.Fatal(err)
}
// 列出所有服务（仅在 Swarm 模式启用时有效）
ctx := context.Background()
services, err := cli.ServiceList(ctx, types.ServiceListOptions{})
if err != nil {
log.Fatal("failed to list services:", err)
}
for _, s := range services {
fmt.Printf("Service: %s (ID: %s)\n", s.Spec.Name, s.ID)
}
}✅ 关键说明：
- types.ServiceListOptions{} 支持过滤参数（如 Filters），可按 label、name 等筛选；
- client.WithAPIVersionNegotiation() 会自动协商最优兼容版本；若需严格绑定 v1.24，请显式设置 client.WithVersion("1.24")；
- 所有请求均需通过 context.Context 控制超时与取消，避免阻塞；
- 类型定义（如 types.Service, types.ServiceSpec, types.ContainerStatus）均来自官方 API Schema，完全匹配 v1.24 文档。
⚠️ 注意事项：
- go-dockerclient 已停止维护，不建议用于新项目；
- 使用 TLS 连接（如示例中的 tcp://...）时，务必配置 client.WithTLSClientConfig() 加载证书；
- 若运行环境为 Docker Desktop 或本地 Unix socket，可改用 unix:///var/run/docker.sock 并省略 TLS 配置；
- v1.24 属于较老版本（2016 年发布），生产环境建议升级至当前稳定版（如 v1.45+），并同步更新客户端依赖。
综上，Docker 官方 Go 客户端提供了开箱即用、类型完备、版本可控的 API 封装，是对接 Docker Remote API 的首选方案。只需正确初始化客户端并引用对应 api/types 包，即可安全、高效地操作容器、镜像、网络及 Swarm 服务等全部资源。
