Moby Engine API 版本怎么选如何查看各版本变更并固定 API 版本【免费下载链接】mobyThe Moby Project - a collaborative project for the container ecosystem to assemble container-based systems项目地址: https://gitcode.com/GitHub_Trending/mo/moby如果你的 Go 程序通过 Moby 的 Engine APIHTTP API操作容器、镜像或网络就需要决定一个问题请求时按哪个 API 版本来发。选高了可能超出客户端库支持的范围选低了会失去新版本提供的字段和端点。本文基于 moby 仓库内的 API 文档和 Go 客户端源码说明如何查看各版本的变更、为客户端选择合适的版本以及如何把 API 版本固定下来。先确定版本支持范围写代码前先确认两端各自支持的版本客户端库支持的范围client包定义了 MaxAPIVersion当前为1.56客户端支持的最高 REST API 版本和 MinAPIVersion当前为1.40版本协商时低于此版本的守护进程会被拒绝。各版本的变更内容api/docs/CHANGELOG.md 按版本从高到低v1.56 往下列出了每个 API 版本新增、修改和废弃的内容。完整的接口定义v1.25 及以后每个版本有一份 Swagger (OpenAPI) v2.0 规格文件位于 api/docs/ 目录下如v1.52.yaml到v1.56.yamlv1.24 及更早版本只有 Markdown 文档。api/docs/README.md 同时提示模块虽然支持旧版本 API但支持是best-effort尽力而为官方建议优先使用最新版本只在需要兼容旧客户端时才依赖旧版本。如何选择要使用的版本api/docs/README.md 给出的选择原则是优先使用最新 API 版本旧版本的支持是尽力而为版本越旧越不保证。新版本通常向后兼容旧版本但有例外——部分功能会被废弃deprecated。所以如果你的程序依赖某个字段或端点升级前要到 CHANGELOG 中确认它是否被废弃。api/swagger.yaml当前最新版本规格的 Versioning 章节还说明了两条与兼容性相关的事实API 采用开放模式open schema服务器可能在响应中增加额外属性并忽略未知的查询参数和请求体字段。你写的客户端必须在解析响应时忽略多余属性否则与更新版本的守护进程通信时可能出错。不写版本前缀的请求会被视为当前最新版本且这种方式已废弃deprecated未来版本会移除——所以不要依赖无版本前缀的调用。CHANGELOG 中的废弃项示例可直接检索确认v1.53 中标记了POST /grpc和POST /session端点已废弃、将在未来版本移除v1.52 中移除了KernelMemoryTCP字段、并删除了NetworkSettings中自 v1.21 起就已废弃的一组字段。判断能不能从 X 版本升到 Y 版本时就查这两个版本区段之间的条目。如何查看某个版本的变更具体操作分三步查变更摘要打开 api/docs/CHANGELOG.md找到目标版本的小节。例如## v1.52 API changes小节列出了GET /images/{name}/get支持多个platform参数、GET /events移除status/id/from字段等内容。查接口定义对应该版本的规格文件在 api/docs/ 下文件名为v1.xx.yaml。注意 api/docs/README.md 明确说明这些 swagger 文件是项目生成 API 文档的依据项目会尽量让它们与实现一致但 OpenAPI 2.0 的表达限制可能导致与实现存在出入discrepancies如果你发现不一致官方建议提 issue 或 PR。查最新可能含未发布变更的规格api/swagger.yaml 位于 api 模块根目录可能包含尚未发布的变更只适合跟踪开发中的行为不适合当作稳定版本的参考。在 Go 客户端中固定 API 版本client包默认启用API 版本协商首次请求时客户端向守护进程发/_pingHEAD失败则回退 GET读取响应中的Api-Version头如果守护进程版本低于客户端使用的版本就把版本降级到守护进程的版本如果高于客户端最大值则使用客户端最大值见 ping.go 中negotiateAPIVersion的说明。协商只做一次后续请求不再重新协商。如果你希望固定版本、关闭协商有两条等价的路径代码中固定WithAPIVersionapiClient, err : client.New( client.FromEnv, client.WithAPIVersion(1.52), // 格式为 major.minor如 1.52 )WithAPIVersion的文档client_options.go给出几点约束版本必须是major.minor格式允许带v前缀格式非法时初始化直接返回错误设置后禁用自动版本协商该选项不会校验你给的版本是否在客户端支持范围内调用方需要自行确认它不低于 MaxAPIVersion 定义的支持范围WithAPIVersion与WithAPIVersionFromEnv同时设置时后者环境变量优先。环境变量固定DOCKER_API_VERSIONFromEnv即WithTLSClientConfigFromEnvWithHostFromEnvWithAPIVersionFromEnv的组合会读取DOCKER_API_VERSION并据此固定版本export DOCKER_API_VERSION1.52envvars.go 中对这个变量有两点说明值必须是MAJOR.MINOR格式例如1.19一旦设置了非空值它优先于 API 版本协商文档同时提示这个变量should be used for debugging purposes only仅建议用于调试因为它可能把客户端设置到不兼容甚至无效的 API 版本上。正式固定版本时优先用WithAPIVersion在代码里显式写死。验证版本是否按预期生效有三个文档给出的验证手段查看客户端当前使用的版本调用 ClientVersion() 返回该客户端正在使用的 API 版本字符串。Ping 查询守护进程版本调用Ping(ctx, PingOptions{NegotiateAPIVersion: true})返回的 PingResult 中APIVersion字段来自响应的Api-Version头即守护进程报告的版本。PingOptions还提供ForceNegotiate即使之前已协商过或已用WithAPIVersion/WithAPIVersionFromEnv固定过版本也强制重新协商一次注意该选项仅在NegotiateAPIVersion为 true 时生效。直接 HTTP 请求时按 api/swagger.yaml Versioning 章节的说明把版本前缀写进 URL例如调用/v1.30/info以使用 v1.30 版本的/info端点如果 URL 中指定的 API 版本不被守护进程支持会返回 HTTP400 Bad Request这就是判断当前守护进程支不支持某个版本的直接方式。协商路径本身的边界行为来自 ping.go守护进程 ping 响应低于客户端最低支持版本MinAPIVersion时negotiateAPIVersion返回错误形如API version x is not supported by this client: the minimum supported API version is MinAPIVersion此时客户端版本不会被更新、协商也不标记完成如果守护进程的 ping 响应中没有 API 版本通常是太老的守护进程客户端会假设对面不支持协商并降级到最低支持版本。限制与注意旧版本的 API 支持是 best-effort不要为了稳定而长期钉在一个很旧的版本上api/docs/README.md 的建议是使用最新版本只在兼容旧客户端时才用旧版本。升级版本前先读 api/docs/CHANGELOG.md 对应区段中的 Deprecated 条目废弃项在当前版本仍可用但会在未来版本移除例如 v1.53 对POST /grpc、POST /session的处理。swagger 规格文件与实际实现可能存在出入以实际行为为准发现不一致可在项目仓库提 issue 或 PR。客户端解析响应时必须容忍服务端新增的额外字段开放模式这是 api/swagger.yaml 明确要求的客户端侧责任。完成版本选择和固定后你的客户端行为就确定下来了ClientVersion()返回固定值、协商不再发生与更新版本的守护进程通信时你依赖的端点行为以你固定的那个 API 版本的 CHANGELOG 与 swagger 规格为准。【免费下载链接】mobyThe Moby Project - a collaborative project for the container ecosystem to assemble container-based systems项目地址: https://gitcode.com/GitHub_Trending/mo/moby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考