3. API兼容性定义：向前兼容、向后兼容与语义化版本控制

在Kubernetes集群升级与制品库准入治理中，API兼容性是决定升级风险的核心度量。一个不兼容的API变更可能导致控制器崩溃、资源无法解析、甚至集群控制面瘫痪。本章从兼容性方向与版本语义两个维度，建立可量化的兼容性定义体系。

3.1 兼容性方向：向前兼容 vs 向后兼容

兼容性方向决定了变更的“破坏半径”。在API治理中，我们通常以客户端（Consumer）和服务端（Provider）的视角来区分两个方向：

下图展示了两个兼容性方向在API版本演进中的交互关系：

3.2 语义化版本控制（SemVer）在API中的应用

语义化版本控制（Semantic Versioning，SemVer）为API版本号赋予了明确的兼容性语义。格式为：MAJOR.MINOR.PATCH。在Kubernetes生态和制品库中，SemVer是判断API变更是否可被准入的核心依据。

3.3 SemVer在Kubernetes API版本中的实际映射

Kubernetes API版本并不直接使用SemVer，但其API版本字符串（如 v1、v1beta1、v2alpha1）隐含了类似的兼容性语义。下表将Kubernetes API版本与SemVer概念对齐：

3.4 兼容性检查的制品库准入规则

基于上述兼容性定义，我们可以制定制品库的API兼容性准入规则。以下是一个简化的规则矩阵：

1. 规则1：版本号格式校验 — 所有API制品必须遵循 MAJOR.MINOR.PATCH 格式，拒绝不符合SemVer规范的制品。
2. 规则2：MAJOR版本变更阻断 — 当新制品的MAJOR版本号大于制品库中已准入的最大MAJOR版本时，触发阻断，要求提交兼容性评估报告。
3. 规则3：MINOR版本变更记录 — MINOR版本变更自动准入，但必须记录变更的API字段差异，生成兼容性报告。
4. 规则4：PATCH版本变更自动放行 — PATCH版本变更直接放行，无需额外检查。
5. 规则5：废弃API版本检测 — 如果制品引用了Kubernetes已废弃的API版本（如 extensions/v1beta1），则发出警告并建议迁移。

以下是一个基于SemVer的准入决策流程：

3.5 兼容性检查的代码示例

以下是一个使用Go语言实现的简易API兼容性检查函数，用于制品库准入：

// CheckAPIVersionCompatibility 检查新制品的API版本是否兼容
// 返回: (是否允许准入, 警告信息列表)
func CheckAPIVersionCompatibility(currentVersion, newVersion string) (bool, []string) {
    var warnings []string

    // 解析SemVer
    current, err := semver.Parse(currentVersion)
    if err != nil {
        return false, []string{"当前版本格式不合法: " + currentVersion}
    }
    next, err := semver.Parse(newVersion)
    if err != nil {
        return false, []string{"新版本格式不合法: " + newVersion}
    }

    // MAJOR变更：阻断
    if next.Major > current.Major {
        warnings = append(warnings, "MAJOR版本变更，需提交兼容性评估报告")
        return false, warnings
    }

    // MINOR变更：记录
    if next.Minor > current.Minor {
        warnings = append(warnings, "MINOR版本变更，已记录变更日志")
        return true, warnings
    }

    // PATCH变更：自动放行
    return true, nil
}