1. 灰度开关版本标识规范
本章定义灰度开关在版本控制中的四元组标识规范，确保每个开关版本在生产、预发、测试等环境之间可追溯、可比较、可回滚。规范的版本标识是灰度发布的“身份证”，缺少任何一部分都可能导致版本混淆或回滚失败。
适用场景
- 灰度开关配置需要标记版本，用于对比当前配置与历史配置的差异。
- 多团队并行修改灰度开关时，需要通过版本号避免覆盖冲突。
- 生产环境回滚开关配置时，需要根据版本标识精准定位目标快照。
- 灰度发布流水线自动生成新版本，需要统一、机器可读的标识格式。
前置条件
- 灰度开关版本管理服务已部署（如 Consul KV、Etcd、自研 Config Center）。
- 版本号生成策略已确认：语义化版本 vs. 时间戳方案需在项目启动时二选一。本章采用 混合方案（语义化 + 构建号 + 环境标记 + 时间戳）。
- 参与灰度发布的研发、QA、运维人员已理解规范约定。
操作步骤
- 确定主版本号：基于语义化版本 2.0.0 规范，记录 API 或配置结构的非兼容变更。代码库 Tag 的版本号与此保持同步。
- 追加构建号：由 CI/CD 流水线自动生成（如 Jenkins Build Number 或 Git Commit Count）。构建号确保同一语义版本下的多次构建可区分。
- 插入环境标记：使用预定义的短编码——
dev、stg、pp、prd，分别对应开发、测试、预发、生产环境。 - 附加时间戳：以 ISO 8601 紧凑格式（
YYYYMMDDTHHmmssZ）附加在末尾，提供秒级精确的发布时间。 - 拼接完整标识：将上述四部分以连字符（
-）连接，格式如下：
示例：<MAJOR.MINOR.PATCH>-<BUILD_NUMBER>-<ENV_TAG>-<TIMESTAMP>2.1.3-4089-pp-20250820T143021Z - 写入版本管理后端：将完整版本标识作为 key 或 label 写入灰度开关配置中心，同时推荐在 Git 仓库的
version.txt中归档。
输入输出物
| 类别 | 输入物 | 输出物 |
|---|---|---|
| 标识元素 | 语义化版本号（如 2.1.3） 构建号（如 4089） 环境标记（如 pp） 时间戳（如 20250820T143021Z） |
完整版本标识字符串（如 2.1.3-4089-pp-20250820T143021Z） |
| 关联资产 | 灰度开关配置 JSON/YAML CI/CD 构建产物 |
版本化开关快照 版本追溯清单（Changelog 表） |
责任边界
- 版本管理者（Release Manager）：批准语义化版本的升级（Major/Minor/Patch），维护版本号基线。
- 开发/测试团队：确保构建号由流水线自动注入，禁止手动修改；环境标记严格按部署环境填写。
- 运维/SRE：保证时间戳使用 UTC 时间，杜绝服务器本地时间偏移引起的版本先后误判。
最佳实践提示： 在灰度开关配置中心（如 Consul）的 key 中包含版本标识，可无缝支持多版本并行和按版本回滚。例如：
/grayscale/user-flag/2.1.3-4089-pp-20250820T143021Z
记录材料
- 灰度开关版本发行说明（Release Notes）：记录每次版本变更请的语义化版本号、变更摘要、影响范围。
- 版本标识来源登记表：包含 Git Commit Hash、CI 构建 URL、构建编号、时间戳，确保四元组可溯源。
异常处理
| 异常场景 | 处理办法 |
|---|---|
| 构建号冲突（同一流水线重复编号） | 采用 Git Commit Count + Pipeline Run ID 组合值替代纯数字构建号。 |
| 环境标记遗漏或错误 | 在 CI/CD 阶段增加环境变量强制校验，未携带合法环境标记的工件直接拒绝部署。 |
| 时间戳溢出或空值 | 在版本管理模块守护进程中运行 NTP 时间同步，版本生成时若获取时间失败则抛异常中断构建。 |
| 标识字符串超长（超出存储长度限制） | 使用哈希缩短算法（如取标识前 48 位 SHA-1）作为后备；同时在元数据字段保留完整字符串。 |
验收标准
- 生成的版本标识符合
<MAJOR.MINOR.PATCH>-<BUILD>-<ENV>-<TIMESTAMP>格式，且每个字段非空。 - 相同语义版本号、构建号、环境标记的标识，若时间戳不同则视为独立版本；若完全一致则直接复用现有版本（幂等行为）。
- 灰度开关配置中心内任意 key 的版本标识均可在 Git 仓库
version.txt中找到对应记录。 - 通过自动化测试验证：随机抽取 10 个版本标识，反解析出的四个成分与原始输入一致。