企业官网建设流程全解析

• 容器运行时
• 云原生

api/types/versions是 Docker Engine 为实现 API 向后兼容而专门设立的“遗留类型”隔离区：当某个类型需要在旧版本 API 中维持原有字段、而在新版本中改变时，开发者就将该类型的旧形态搬入对应版本的子包，从而让新旧客户端同时正常工作。本文以 api/types/versions/README.md 为核心骨架，结合compare.go、v1p19、v1p20子包及 daemon 层的调用链源码，完整讲解这套遗留类型的组织规则、包命名规范、版本比较算法与真实接入方式，读完你即可掌握在 Docker API 演进中正确“冻结”旧类型的方法论。

包定位：稳定类型与遗留类型的分工

Docker Engine 的 API 类型定义分布在两处：

• 稳定版本类型：位于 api/types 下的*.go，例如types.go中的ContainerJSON、ContainerJSONBase、NetworkSettings等，代表当前最新 API 版本使用的类型定义；
• 遗留版本类型：位于 api/types/versions，该包内不放置“当前版本”的类型，而是按 API 版本归档那些只能在旧版本 API 中出现、但当前主类型已经演进的旧形态。

README 给出了一个非常明确的迁移决策点：

Consider moving a type here when you need to keep backwards compatibility in the API.

也就是说，只有当某个类型在旧版本 API 中必须保持原始字段结构、而新版本又需要改变它时，才把该类型“搬进”versions包。这是避免直接修改稳定类型导致旧客户端解析失败的关键手段。

按“最新出现版本”组织子包

遗留类型的组织原则是：按该类型出现的最后一个 API 版本号归档（organized by the latest API version they appear in）。README 的原话定义了这一边界：

• v1p19包中的类型，适用于API 版本小于等于1.19的客户端（valid for API versions below or equal 1.19）；
• v1p20包中的类型，适用于API 版本1.20，因为比1.20更低的版本会使用v1p19中的遗留类型。

因此版本边界是“半开区间”式的：一个子包覆盖的版本区间从上一个子包的版本号+1 开始，到本子包版本号为止。这种设计与 Docker 的版本分发策略一致：每个 API 版本号的ContainerJSON、StatsJSON等结构都有且仅有一个权威定义，旧客户端请求时由服务端按版本分派到正确的结构。

包命名约定：v + 主版本 + p + 补丁版本

包名以v作为版本号前缀、以p（patch）作为分隔符，例如v1p19、v1p20。README 明确说明了这一命名法的两个动因：

1. 不能使用.：点号在 Go 语言中是选择器（selector）语法的一部分，v1.20.CallFunction会被语言解析为“从包v1调用字段20上的CallFunction”，语义完全错误；
2. 不能使用_：下划线虽然合法，但会触发golint的命名风格告警，v1_20.CallFunction虽然可编译，但读起来怪异。

因此v+ 数字 +p+ 数字成为唯一既合规又易读的选择。以 README 的例子来说：如果你要修改一个 API1.21中可用、但会在1.22中改变字段的类型，就应当在api/types/versions下新建v1p21子包，将旧形态放进去。当前仓库中已存在的子包是 v1p19/types.go 与 v1p20/types.go，二者也是该命名约定的直接实例。

版本比较实现：compare.go 与五个判断函数

虽然 README 未展开实现细节，但该包的核心工具函数集中在 compare.go，它负责字符串形式的版本号比较（如"1.20"、"1.41"），是上层“按版本分派行为”的基础。

底层compare函数

compare(v1, v2 string) int返回三个可能值：-1（v1 < v2）、1（v1 > v2）、0（相等）。实现逻辑为：

1. 先用strings.Split(v, ".")把版本号按点号切分成数字片段；
2. 取两个切片长度的较大值作为比较轮数，max := len(currTab)，若len(otherTab) > max则更新max；
3. 逐位比较：某侧若已没有该位数字，则当作0参与比较（if len(currTab) > i/if len(otherTab) > i判定后取strconv.Atoi的结果，忽略转换错误）；
4. 首次出现currInt > otherInt返回1，otherInt > currInt返回-1；全部位相等则返回0。

这套实现天然支持了不同位数版本号的比较，例如"1"与"1.0.0"会被判定为相等（缺位按 0 补齐）。这一行为在 compare_test.go 的TestCompareVersion中直接得到验证：

五个对外判断函数

compare.go在compare之上封装了五个布尔判断 API，全仓库大量路由代码直接引用：

• LessThan(v, other string) bool：compare == -1；
• LessThanOrEqualTo(v, other string) bool：compare <= 0；
• GreaterThan(v, other string) bool：compare == 1；
• GreaterThanOrEqualTo(v, other string) bool：compare >= 0；
• Equal(v, other string) bool：compare == 0。

从源码检索可见，这些函数是 Docker API 服务端实现“版本感知路由”的主力。例如 build_routes.go 中连续用GreaterThanOrEqualTo(version, "1.12")、"1.16"、"1.32"、"1.40"决定构建参数forcerm、pull等字段的兼容处理；container_routes.go 用LessThan(version, "1.19")等判断是否需要对CPUShares、HostConfig字段做版本化调整；system_routes.go 则用LessThan(..., "1.25")决定返回老式信息。可以说versions包不仅是类型容器，更是全引擎版本分支判断的基础设施。

版本校验中间件：版本号从哪来、如何被拦截

遗留类型被使用的场景，发生在请求到达各业务路由之前。整个链路由 version.go 的VersionMiddleware把关：

1. NewVersionMiddleware(s, d, m string)注入serverVersion（服务端版本）、defaultVersion（当前默认 API 版本）与minVersion（最低支持版本）；
2. WrapHandler首先设置Server、API-Version、OSType三个响应头；
3. 从 URL 变量vars["version"]读取客户端请求的 API 版本，为空则回退到defaultVersion；
4. 用versions.LessThan(apiVersion, v.minVersion)判断是否“太旧”，用versions.GreaterThan(apiVersion, v.defaultVersion)判断是否“太新”，命中则返回versionUnsupportedError（错误信息明确提示client version %s is too old或too new，对应 API 版本范围约束）；
5. 校验通过后，把版本号以httputils.APIVersionKey{}写入context，供下游通过 httputils.VersionFromContext 取出。

正是这一中间件，让“同一个 URL、不同version路径参数”能路由到完全不同的处理分支，而versions包的比较函数正是分支判断的执行者。

遗留类型的真实消费场景：以 v1p19 与 v1p20 为例

daemon 层的版本分派

遗留类型最典型的消费点在ContainerInspect。在 daemon/inspect.go 中可以看到经典的“三分支”调度：

func (daemon *Daemon) ContainerInspect(name string, size bool, version string) (interface{}, error) { switch { case versions.LessThan(version, "1.20"): return daemon.containerInspectPre120(name) case versions.Equal(version, "1.20"): return daemon.containerInspect120(name) } return daemon.ContainerInspectCurrent(name, size) }

这与 README 描述的边界完全吻合：低于1.20用v1p19类型、等于1.20用v1p20类型、更高版本用当前稳定类型（types.ContainerJSON，见 types.go）。上游路由 container/inspect.go 从 context 取出version后直接透传给该函数，即完成了“HTTP 版本参数 → 正确 JSON 结构”的映射。

v1p19：1.19 及更早版本的类型快照

v1p19/types.go 定义了ContainerJSON与ContainerConfig，它们直接反映了 1.19 及之前 API 的响应形态：

• ContainerJSON内嵌*types.ContainerJSONBase（复用了当前稳定的基础字段），但额外保留了Volumes map[string]string与VolumesRW map[string]bool——这两个字段在后续版本中被Mounts []types.MountPoint取代；
• NetworkSettings指向v1p20.NetworkSettings（说明网络设置结构自 1.20 起统一为同一种向后兼容形态）；
• ContainerConfig内嵌*container.Config，并保留了大量“后来迁入 HostConfig”的字段：VolumeDriver、Memory、MemorySwap、CPUShares（JSON 名为CpuShares）、CPUSet（JSON 名为Cpuset）等，且MacAddress、NetworkDisabled、ExposedPorts也在其中。文件注释特别注明该结构不适用于 Windows daemon（Note this is not used by the Windows daemon）。

对应实现位于 daemon/inspect_linux.go 的containerInspectPre120：它从ctr.MountPoints手工重建volumes/volumesRW两个 map（volumes[m.Destination] = m.Path()、volumesRW[m.Destination] = m.RW），并逐一从ctr.HostConfig取值回填Memory、MemorySwap、CPUShares、CPUSet——这正是“老字段迁到了 HostConfig，旧版本还要吐出来”的落地实现。

v1p20：1.20 版本的类型快照

v1p20/types.go 定义了三类结构：

1. ContainerJSON：开始使用Mounts []types.MountPoint替代Volumesmap，NetworkSettings为包内自有的向后兼容结构；
2. ContainerConfig：相比v1p19版本，Memory、MemorySwap、CPUShares、CPUSet已被移除（它们只保留到 1.19），仅剩VolumeDriver这类仍需回填的字段；
3. StatsJSON与NetworkSettings：后者组合types.NetworkSettingsBase与types.DefaultNetworkSettings，注释表明它们服务于1.21 之前的 API（APIs prior to 1.21），注意这里与包名1.20并不冲突——README 的原则是“按最新出现版本归档”，StatsJSON最后一次出现在 1.20，故归入v1p20。

StatsJSON的消费点在 daemon/stats.go：当versions.LessThan(apiVersion, "1.21")时，代码会把types.NetworkStats（定义于 api/types/stats.go，含RxBytes、RxPackets、RxErrors、RxDropped、TxBytes等字段）中的多网络数据手工聚合成单个Network字段，再包进v1p20.StatsJSON返回——因为 1.21 之前的客户端只认扁平的单网络统计格式。Windows 下 1.21 之前的 API 甚至直接不支持 stats（见 daemon/stats.go）。

新增一个遗留类型包的完整步骤

结合 README 的说明与仓库现状，当 API 演进需要“冻结”一个旧类型时，完整步骤如下：

1. 确定冻结边界：确认该类型最后一次出现的 API 版本号，例如在1.22中字段将变化、最后一次完整出现在1.21；
2. 创建子包：在api/types/versions下新建目录v1p21，命名遵循v+ 版本号 +p+ 补丁号的规则（新版本号对应v1p21）；
3. 声明包注释：仿照 v1p19/types.go 的写法，在文件头部以// Package v1p21 provides specific API types for the API version 1, patch 21.说明用途，并写package v1p21 // import "github.com/docker/docker/api/types/versions/v1p21"规范 import 路径；
4. 编写结构体：以“复用稳定基础类型 + 保留旧字段”为原则组织字段。内嵌当前稳定的*types.ContainerJSONBase、*container.Config等以减少重复，仅保留旧版本独有的字段，并在注释中标明“backward compatibility, they now live in HostConfig”之类的迁移说明（如 v1p19/types.go）；
5. 接线 daemon：在 daemon/inspect.go 的分支 switch（或 stats 等对应处理函数）中，新增case versions.Equal/LessThan分支并实现对应的序列化函数，把旧字段从当前存储结构（如ctr.HostConfig、ctr.MountPoints）回填到新类型；
6. 补充测试：至少为版本比较行为编写断言（参考 compare_test.go 的assertVersion模式），并可通过集成测试（如 docker_api_inspect_test.go 反序列化v1p20.ContainerJSON）验证 JSON 字段与旧客户端期望一致。

小结

api/types/versions包用“按最新出现版本归档”的简单原则，加上v/p命名约定，为 Docker Engine 的 API 向后兼容提供了清晰而强制的工程边界：稳定类型在 api/types 演进，遗留类型在 api/types/versions 冻结；compare.go 提供逐位数字比较，middleware/version.go 负责校验并注入版本号，daemon/inspect.go 等消费方按版本分派到对应结构。理解这套机制，不仅有助于读懂 Docker API 在不同版本下的响应差异，也能为自研服务在“接口演进但老客户端仍需可用”的场景下提供可直接借鉴的落地范式。

• 容器运行时
• 云原生