3. SDK版本管理与语义化版本

SDK治理的核心矛盾之一，是“接口在演进、调用方在增长、依赖在叠加”，而版本号是唯一能同时约束这三者的契约载体。如果版本命名随意、依赖解析不确定、漂移无人发现、升级没有策略，SDK就会从“能力复用”退化为“故障放大器”。本节围绕版本命名规范、依赖解析、版本漂移检测与升级策略四个环节，给出可落地的工程做法。

一、版本命名规范：语义化版本是契约，不是装饰

语义化版本（SemVer）的标准格式为 MAJOR.MINOR.PATCH，并可附加预发布标识与构建元数据，例如 2.4.1-beta.2+build.20240513。其核心约定是：

• MAJOR：出现不兼容的接口变更时递增，例如删除公开方法、修改参数类型、改变返回结构。
• MINOR：以向后兼容方式新增能力时递增，例如新增可选参数、新增接口、新增枚举值。
• PATCH：向后兼容的问题修复时递增，例如修正边界条件、修复内存泄漏、优化日志。

企业级SDK还需要补充两条内部规范。第一，预发布版本不得进入生产依赖，如 -alpha、-beta、-rc 只能用于联调与灰度验证；第二，构建元数据不参与比较，1.2.3+build.1 与 1.2.3+build.2 在依赖解析中视为同一版本。此外，SDK的公开API应通过工具生成API基线文件（如 api-baseline.json），在CI中对比本次提交与基线的差异，自动判定应递增哪一位版本号，避免“靠人记”导致版本语义失真。

二、依赖解析：从“能装上”到“可复现”

依赖解析的目标不是让构建通过，而是让同一份声明在不同机器、不同时间解析出完全一致的依赖图。以Maven为例，解析遵循“最近优先”和“先声明优先”规则；Gradle默认选择最高版本；npm则采用扁平化与嵌套并存的策略。不同策略会导致同一SDK在不同构建工具下引入不同版本的传递依赖，进而引发 NoSuchMethodError 或行为不一致。

工程上应做到三点：第一，锁定传递依赖，使用 dependencyLock、package-lock.json 或 gradle.lockfile 固化解析结果；第二，统一版本对齐，通过BOM（Bill of Materials）或 dependencyManagement 集中声明SDK及其依赖版本；第三，冲突显式化，在CI中执行依赖树分析，发现同一坐标出现多版本时输出告警而非静默选择。下面是一个Gradle依赖约束示例：

dependencies {
    constraints {
        implementation('com.example:payment-sdk:2.4.1') {
            because '统一支付SDK版本，避免传递依赖漂移'
        }
        implementation('com.example:logging-core:1.8.0') {
            because '日志核心库与支付SDK 2.4.x 兼容'
        }
    }
}

三、版本漂移检测：让“悄悄变化”变成“可见事件”

版本漂移指实际解析到的依赖版本与基线声明不一致，常见于传递依赖被上游升级、镜像仓库缓存了不同构件、或开发者本地手动改动了版本。漂移不会立刻报错，却可能在灰度或生产环境触发兼容性问题。检测手段包括：

• 基线比对：将当前解析出的依赖清单与 baseline-dependencies.json 逐项比对，输出新增、删除、版本变化三类差异。
• 定时扫描：每日对主干分支执行依赖解析，发现漂移即生成工单，而不是等到发布前才检查。
• 制品校验：对SDK构件计算SHA-256并与仓库元数据比对，防止同名不同内容的构件被引入。

下图展示了从版本声明到漂移判定、再到升级决策的完整链路，其中“解析结果 vs 基线”是漂移检测的关键判断点。

四、升级策略：按变更类型分级，而不是“一刀切”

升级策略应与版本号语义严格对应。PATCH升级通常只包含缺陷修复，风险最低，可在CI通过后自动合并并进入下一轮发布；MINOR升级引入新能力，虽然向后兼容，但可能改变默认行为或性能特征，应先在小流量灰度环境验证，观察错误率、延迟和关键业务指标无异常后再全量；MAJOR升级包含不兼容变更，必须人工评审，评估调用方改造量、迁移窗口和回滚方案，禁止自动升级。

为了让策略可执行，建议维护一份升级决策表，把“版本变化类型、影响范围、验证方式、审批角色”固定下来。例如：

此外，升级不是单向动作，必须配套回滚能力。每次升级前记录当前锁定版本与制品哈希，升级后若在观察窗口内出现错误率上升超过阈值（例如P95延迟上升20%或错误率翻倍），应能一键回退到上一锁定版本。版本治理的成熟标志，不是“永远不升级”，而是“每次升级都可解释、可验证、可回退”。

把版本命名、依赖解析、漂移检测和升级策略串成闭环后，SDK的演进就从“靠经验”变成“靠机制”。调用方能够预期变更边界，平台方能够量化风险，治理工作也才能真正沉淀为可复用的工程能力。