制品版本标识要解决的是“这个制品到底由哪次提交、哪次构建产生”的问题。做法分四步：先确定标识由版本号、构建序号、提交标识、环境或渠道标记等字段组成；再规定组合格式和唯一性约束；然后让流水线在构建产物时自动生成并写入标识；最后通过反查源码提交与构建记录完成校验。核心变化是把版本号从人工填写改为规则定格式、流水线生成、记录可核验。
要点总览（TL;DR）
- 制品版本标识由语义化版本号、构建序号、提交哈希和按需的预发布或渠道后缀组成，版本号面向使用者，构建序号与提交哈希面向排障追溯。
- 用固定模板组合字段，例如 2.4.1-137-a1b2c3d-rc.1，分隔符统一，人工不拼接标识；唯一性由单调递增的构建序号和提交哈希共同保证。
- 标识在编译完成之后、打包之前由流水线生成，写入制品元数据、镜像标签或清单文件，并同步登记到构建记录，形成制品到源码提交的关联。
- 已发布标识不可复用或覆盖，重新构建生成新的构建序号，旧标识保留并标记废弃；规则变更只对变更后产生的制品生效。
- 用抽查验证落地：随机取已发布制品反查源码提交与构建记录，检查是否存在撞号、覆盖或手工改写标识的情况。
先定标识字段：版本号里放什么
字段设计决定标识能回答哪些问题。一个可用的标识通常同时承担两类信息：面向使用者的版本含义，以及面向排障的构建来源。前者用语义化版本号表达，后者用构建序号和提交哈希表达。字段不必求多，但每个字段都要有明确来源，避免出现人工填写、无法核对的字段。
| 字段名 | 含义 | 示例值 | 是否必填 | 生成来源 |
|---|---|---|---|---|
| 主版本号 | 对外可见的不兼容变化 | 2 | 必填 | 发布计划人工确认 |
| 次版本号 | 向后兼容的功能新增 | 4 | 必填 | 发布计划人工确认 |
| 修订号 | 向后兼容的问题修复 | 1 | 必填 | 发布计划人工确认 |
| 构建序号 | 同一版本下第几次构建，单调递增 | 137 | 必填 | 流水线构建计数器 |
| 提交哈希 | 制品对应的源码提交 | a1b2c3d | 必填 | 版本控制系统 |
| 预发布标记 | 区分预发布与正式发布 | rc.2 | 按需 | 流水线按分支或发布类型写入 |
| 渠道或环境标记 | 区分交付渠道或目标环境 | gray、prod | 按需 | 流水线按发布任务写入 |
| 制品类型 | 区分同一版本下的不同产物 | jar、tar.gz | 按需 | 打包步骤写入 |
语义化版本号承载兼容性承诺，适合让使用方判断升级风险；构建序号和提交哈希承载可追溯性，适合排障时定位到具体代码。两者组合使用，前者保证可读，后者保证可查。环境或渠道标记只在同一版本需要向多个渠道交付时使用，避免把所有场景都塞进版本号。唯一性主要由构建序号和提交哈希保证，可读性则由版本号保证，字段设计时按这个分工取舍。
标识生成规则与唯一性约束
字段确定后，需要用固定模板把它们组合起来，并明确什么情况下会撞号。模板写法建议采用“版本号+构建序号+提交哈希短码”的主干，后缀按需追加，分隔符统一使用连字符，各段内部不再出现连字符，便于解析。
一个可参照的格式模板为：主.次.修订-构建序号-提交哈希短码[-预发布标记][-渠道标记]，例如 2.4.1-137-a1b2c3d、2.4.1-138-a1b2c3d-rc.2。模板一旦写入规则文档，流水线按同一模板生成，人工不拼接标识。
唯一性由三个机制共同保证：构建序号在同一版本内单调递增，保证同一版本下每次构建不同；提交哈希标识源码状态，保证不同代码产生不同标识；时间戳可作为补充手段，用于构建序号被重置等异常场景。预发布与正式发布的区分通过后缀完成，预发布制品带 rc 等标记，正式发布不带预发布后缀，两者在制品仓库中分目录存放。
不可变原则是规则的底线：已发布的标识不得复用或覆盖。发现问题需要重新构建时，生成新的构建序号，旧标识保留在原处并标记为废弃。这样任何一份历史制品都能对应到唯一的源码提交和构建记录，回滚和审计才有依据。
在流水线中自动生成并写入制品
标识的生成时机放在编译完成之后、打包之前。此时源码提交已确定，构建序号已由流水线分配，标识可以一次性算好并传给后续步骤。发布前只做校验，不再改写标识。
具体步骤按输入、动作、输出和完成标志展开：
- 输入：源码提交记录、流水线构建计数器、发布计划中的版本号。动作：流水线读取提交哈希短码，与版本号和构建序号按模板拼接。输出：本次构建的标识字符串。完成标志：标识在构建日志中打印且格式符合模板。
- 输入：标识字符串、打包脚本。动作：打包时将标识写入制品元数据，例如包管理器的版本字段、镜像标签、清单文件中的版本条目。输出：带标识的制品文件。完成标志：解包或查询元数据能看到与日志一致的标识。
- 输入：标识、提交记录、构建任务编号。动作：将三者写入构建记录，形成制品到源码的关联。输出：一条可查询的构建记录。完成标志：用标识能检索到对应提交和构建任务。
- 输入：制品文件、构建记录。动作：上传制品仓库并登记台账。输出：仓库中的制品条目。完成标志：台账中的标识与仓库条目一致。
人工干预的边界要写清楚：版本号的主次修订由发布计划确认，属于人工决策；构建序号、提交哈希、后缀标记由流水线自动生成，不允许手工修改。例外情况如紧急修复需要复用版本号时，仍生成新的构建序号，并在发布记录中注明原因，保留旧标识不动。
标识生成并写入制品后，制品本身还需要与需求、任务和发布记录建立关联，才能支撑影响分析和交付回溯。ONES 的 ALM 研发管理方案围绕需求、基线、版本和变更建立统一管理对象，并把测试用例、缺陷、版本和发布过程关联到需求链路中，可用于承载这类关联管理；制品文件本身仍存放在制品仓库，标识作为关联键使用。
角色分工与交付物
规则要落地，需要明确谁定、谁实现、谁校验。分工可以按团队规模调整，小团队允许一人兼任多个角色，但校验环节应保留独立执行。
| 角色 | 职责 | 交付物 |
|---|---|---|
| 研发或构建负责人 | 确定字段组成与命名格式，评审规则变更 | 标识规则文档，含字段清单与格式模板 |
| 流水线维护者 | 在流水线中实现标识生成、写入与记录关联 | 流水线配置及构建记录 |
| 发布负责人 | 确认发布版本号，核对发布制品标识 | 发布记录，含标识与发布范围 |
| 质量或配置管理角色 | 抽查唯一性与可追溯性，检查已发布标识是否被改写 | 校验记录与问题清单 |
规则变更的触发条件包括：新增交付渠道需要扩展后缀、版本号策略调整、发现撞号或覆盖问题。变更时更新规则文档并同步修改流水线配置，历史标识的解析方式保持不变，新规则只对变更后产生的制品生效。
一个完整示例：从提交到可追溯标识
假设某服务发布 2.4.1 版本，修复了一个兼容性问题。开发提交哈希为 a1b2c3d9e8f7，流水线第 137 次构建，目标为预发布环境。按模板生成的标识为 2.4.1-137-a1b2c3d-rc.1，打包时写入镜像标签和清单文件的版本字段，同时构建记录登记提交哈希、构建任务编号和该标识。
验证发布时，从制品仓库取该标识的镜像，查询构建记录得到提交 a1b2c3d9e8f7，在版本控制系统中确认该提交属于 2.4.1 的修复分支，发布记录中登记的标识与仓库条目一致，追溯闭环成立。正式发布时生成 2.4.1-138-a1b2c3d，不带预发布后缀，与预发布制品分开存放。
常见错误标识可以对照识别：只写 2.4.1 无法区分同一版本下的多次构建；写 latest 无法反查源码；手工拼接的 2.4.1-fix 缺少构建序号和提交信息；已发布后覆盖同名制品会导致历史记录失真。这些情况都应通过规则和流水线约束排除。
完成检查：标识是否真的可用
机制是否落地，用抽查和核对来验证，不依赖规则文档本身。以下清单可逐项执行：
| 检查项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 唯一性抽查 | 随机抽取若干已发布制品，标识互不重复，同一版本下构建序号连续递增 | 制品仓库条目列表与构建记录 | 质量或配置管理角色 |
| 可追溯性验证 | 任取一个制品标识，能反查到源码提交和构建任务记录，三者一致 | 构建记录、版本控制提交页 | 质量或配置管理角色 |
| 已发布标识不可变性 | 已发布标识对应的制品未被覆盖，重新构建产生新标识 | 仓库操作日志、发布记录 | 发布负责人 |
| 规则变更兼容 | 规则变更后，历史标识仍可解析和查询，新制品按新规则生成 | 规则文档版本记录、新旧制品对照 | 研发或构建负责人 |
| 人工干预边界 | 构建序号、提交哈希、后缀均由流水线生成，无手工改写记录 | 流水线配置与构建日志 | 流水线维护者 |
抽查发现撞号或覆盖时，先冻结相关发布，补齐构建记录，再按新规则重新生成标识。检查通过的标准是每个已发布制品都能用标识反查到唯一的源码提交与构建记录，且历史标识保持可解析。做到这一步，制品版本标识才真正成为交付与追溯的可靠依据。
常见问题
同一版本需要多次构建时，版本号要不要跟着改？
不需要。版本号的主、次、修订号表达对外可见的兼容性变化，同一版本下的多次构建由构建序号区分，例如 2.4.1-137-a1b2c3d 和 2.4.1-138-a1b2c3d 属于同一版本的不同构建。这样使用方看到的版本含义保持稳定，排障时又能定位到具体构建。只有兼容性承诺发生变化时，才调整版本号。
预发布制品转正式发布时，是改标识还是重新构建？
建议重新构建并生成正式标识，预发布制品保留原标识不动。预发布与正式发布通过后缀区分，例如预发布带 rc 标记，正式发布不带；两者在制品仓库中分开存放。如果直接改写预发布制品的标识，历史记录会失真，后续追溯时无法确认当时验证的到底是哪份产物。
流水线构建序号被重置或迁移后，唯一性怎么保证？
构建序号重置属于异常场景，可以用提交哈希作为主要区分手段，必要时补充时间戳字段。处理方式是在规则文档中写明重置后的起始序号和过渡期规则，并在构建记录中保留重置说明。已经发布的标识不受影响，继续按原标识查询；重置后新产生的制品按新序号生成，避免与历史标识重复。
标识写入制品后，还需要在研发管理系统中登记吗？
需要。制品文件存放在制品仓库，标识作为关联键，把制品与需求、任务、发布记录关联起来，才能支撑影响分析和交付回溯。ONES 的 ALM 研发管理方案围绕需求、基线、版本和变更建立统一管理对象，并把测试用例、缺陷、版本和发布过程关联到需求链路中，可用于承载这类关联管理；制品文件本身仍存放在制品仓库。
小团队人手有限，角色分工可以简化到什么程度？
可以一人兼任多个角色，但建议保留独立的校验环节。规则定义和流水线实现由同一人完成时，抽查唯一性与可追溯性的工作交给另一人执行，或者至少隔一段时间由本人按检查清单逐项核对并留下记录。校验的价值在于用实际制品验证规则，而不是复核文档本身，因此保留这个环节比保留角色名称更重要。
