交付流水线图要能指导实际交付，核心是把阶段、门禁和角色写清楚。本文按“定边界—拆阶段—标门禁—分角色—做走查—完成检查”的顺序展开，适用于单个服务或应用版本的端到端交付流程设计，平台对接与发布审批规则不在本文展开。
要点总览（TL;DR）
- 先锁定交付对象（单个服务、应用版本或发布批次）和起止事件，把平台对接与发布审批规则显式排除在图外。
- 阶段以“能否独立判定通过与否”为界，通常六到八个阶段，每段写清输入、执行动作、产出物和完成标志。
- 门禁要标明判定位置、条件和阻断方式，并与失败回退路径成对出现；人工审批节点单独标注触发条件。
- 每个阶段标注责任人与协作人，交接物具体到制品、测试报告、变更说明和发布记录，并写明记录位置。
- 用一次近期真实交付走查图与执行的一致性，修正后指定维护人和更新时机。
先确定流水线图的交付对象与起止边界
设计流水线图的第一步是回答“这张图描述什么”。同一张图如果既想覆盖单个服务的日常发布，又想覆盖一次多服务发布批次，阶段和门禁会互相冲突，最后谁也无法按图判断进度。建议先锁定一个交付对象，再确定起点和终点事件。
交付对象通常有三种选择：单个服务、一个应用版本、一次发布批次。单个服务适合微服务架构下各服务独立发布的团队；应用版本适合多模块打包发布的单体或聚合应用；发布批次适合需要多个服务协同上线的场景。选择哪一种，取决于团队日常按什么单位判断“一次交付完成”。
起点和终点决定图的读取方式。起点可选代码合并到主干、构建触发或需求进入开发；终点可选制品入库、测试环境部署完成或生产发布完成。起点越靠前，图覆盖的协作环节越多；终点越靠后，图与发布操作的耦合越深。常见做法是以代码合并为起点、以生产发布完成为终点，这样图能覆盖从变更产生到用户可用的完整链路。
边界外内容要显式列出，避免图越画越大。平台对接细节（如流水线工具与代码库的接口配置）和发布审批的组织规则（如谁有权批准上线）通常不在本图展开，只在图中标注“此处对接外部系统”或“此处进入审批流程”即可。
| 边界项 | 填写内容 | 示例 |
|---|---|---|
| 交付对象 | 这张图描述的最小交付单位 | 订单服务的一个应用版本 |
| 起点事件 | 图开始计数的触发事件 | 代码合并到主干分支 |
| 终点事件 | 判定一次交付结束的事件 | 生产环境发布完成并验证通过 |
| 不在图内的内容 | 明确排除的环节 | 流水线工具接口配置、发布审批权限规则 |
按阶段拆分并定义每段的输入、动作与产出
阶段拆分的标准是“能否独立判定通过与否”。一个阶段如果无法单独给出通过或失败的结论，说明它和相邻阶段混在一起了。按这个标准，常见的端到端阶段包括：提交与构建、静态检查与单元测试、制品归档、环境部署、集成与验收测试、发布。
每个阶段都要写清四要素：输入、执行动作、产出物、完成标志。只画方框不写这四项，图就退化成示意图，无法用来判断卡点。下面是一张可直接填写的阶段定义表：
| 阶段 | 输入 | 执行动作 | 产出物 | 完成标志 |
|---|---|---|---|---|
| 提交与构建 | 合并后的代码提交 | 拉取代码、编译打包 | 构建产物、构建日志 | 构建成功且产物可下载 |
| 静态检查与单元测试 | 构建产物、源码 | 执行代码规范检查、单元测试 | 检查报告、测试报告 | 检查无阻断项、单测全部通过 |
| 制品归档 | 通过检查的构建产物 | 打版本号、写入制品库 | 带版本号的制品 | 制品入库且版本号唯一 |
| 环境部署 | 归档制品、环境配置 | 部署到测试环境 | 部署记录、环境访问地址 | 服务启动正常、健康检查通过 |
| 集成与验收测试 | 已部署的测试环境 | 执行集成测试、验收用例 | 测试报告、缺陷清单 | 约定用例全部通过、无高等级缺陷 |
| 发布 | 验收通过的制品 | 部署到生产、执行发布验证 | 发布记录、验证结果 | 生产验证通过、发布记录归档 |
阶段粒度要控制。过细会把一个构建拆成“拉代码”“编译”“打包”三个框，图变得难以阅读；过粗会把构建和测试合成一个框，失败时无法定位是编译问题还是用例问题。以“可独立判定通过与否”为界，通常六到八个阶段足够覆盖一次端到端交付。
并行阶段要画清汇合条件。例如静态检查和单元测试可以并行执行，但两者都通过后才能进入制品归档，图中应把两条分支汇合到一个判定点，并注明“两项均通过”。并行分支如果没有汇合条件，读者无法判断是任一通过即可还是全部通过，图就失去了判定价值。
把质量门禁与失败回退画进图里
门禁是流水线图区别于流程示意图的关键。它回答“什么条件下可以继续往下走”。常见门禁类型包括测试通过率、缺陷等级、代码评审完成情况、安全扫描结果。每类门禁都要在图中标明判定位置、判定条件和阻断方式。
判定位置指门禁放在哪个阶段之后。测试通过率通常放在单元测试或集成测试阶段之后；代码评审完成情况放在提交与构建之前或合并环节；安全扫描结果放在制品归档之前，避免带风险的制品进入环境。阻断方式要写明是硬阻断（不通过则流程停止）还是软阻断（记录问题但允许继续，需负责人确认）。
| 门禁类型 | 判定位置 | 判定条件示例 | 阻断方式 | 不通过后的走向 |
|---|---|---|---|---|
| 单元测试通过率 | 单元测试阶段后 | 用例全部通过 | 硬阻断 | 退回开发修复，重新触发构建 |
| 缺陷等级 | 验收测试阶段后 | 无高等级未关闭缺陷 | 硬阻断 | 转缺陷修复，修复后重跑验收 |
| 代码评审完成 | 代码合并前 | 至少一名评审人通过 | 硬阻断 | 补充评审后再合并 |
| 安全扫描结果 | 制品归档前 | 无高危漏洞 | 硬阻断或负责人确认后放行 | 修复漏洞或走例外确认 |
失败回退路径要和门禁成对出现。回退有三种常见走向：回到上一阶段（如测试失败退回开发修复）、回滚部署（如生产验证失败回滚到上一版本）、转人工处理（如安全扫描出现需人工判断的告警）。图中用带箭头的回退线表示，并在线旁注明触发条件和处理责任人。
人工审批节点要单独标注。审批节点与自动门禁的区别在于它需要人做判断，图中用不同形状或颜色区分，并注明触发条件（如涉及数据库变更、涉及对外接口变更）和审批人角色。审批节点不宜过多，否则流水线会在等待中停滞；只在风险确实需要人工判断的环节设置。
角色分工与交接物怎么在图上体现
图要能追责，就必须标明每个阶段谁负责、交接什么。角色划分通常包括开发、测试、运维、发布负责人。开发对提交与构建、单元测试负责；测试对集成与验收测试负责；运维对环境部署和发布执行负责；发布负责人对发布决策和发布记录负责。同一人可兼任多个角色，但图中角色名称要写清。
每个阶段标注责任人和协作人。责任人对该阶段的完成标志负责，协作人提供输入或配合执行。例如环境部署阶段，运维是责任人，开发是协作人（提供部署配置说明）。标注方式可以在阶段框下方写“责任人：运维；协作：开发”。
| 阶段 | 责任人 | 协作人 | 交接物 | 交接确认方式 |
|---|---|---|---|---|
| 提交与构建 | 开发 | — | 构建产物、构建日志 | 构建状态自动记录 |
| 静态检查与单元测试 | 开发 | 测试 | 检查报告、测试报告 | 报告归档并关联工作项 |
| 制品归档 | 开发 | 运维 | 带版本号的制品 | 制品库入库记录 |
| 环境部署 | 运维 | 开发 | 部署记录、环境地址 | 部署记录留痕 |
| 集成与验收测试 | 测试 | 开发 | 测试报告、缺陷清单 | 测试结论签字或系统确认 |
| 发布 | 发布负责人 | 运维、开发 | 变更说明、发布记录 | 发布记录归档并通知相关方 |
交接物要具体到可核验的物件：制品、测试报告、变更说明、发布记录。交接确认方式要写清记录在哪里——是制品库的入库记录、测试管理中的报告状态，还是工作项上的附件与评论。记录位置不明确，交接就退化成口头通知，事后无法追溯。
当团队使用 ONES 管理研发过程时，可以把阶段推进与工作项状态对应起来：需求或研发任务关联代码提交后，工作项上能看到代码研发进展；集成 Jenkins、GitLab CI 等第三方流水线工具后，ONES 会同步流水线数据并更新执行状态和日志，流水线与项目关联后可在项目、迭代、需求中查看代码提交、构建和发布过程。这样阶段交接物中的测试报告、发布记录可以挂在工作项或文档上，走查时直接对照记录核对，减少“图上有、记录找不到”的情况。具体集成配置与版本支持需按实际环境核验。
用一次真实交付校验流水线图
图画完后，用一次近期真实交付做走查，检验图与执行是否一致。选取样本时优先选刚完成、记录较全的一次交付，避免选年代久远、记录缺失的案例。走查的目标是找出图中缺失的阶段、未标注的门禁和责任不明的环节。
走查按以下步骤进行：
- 调出这次交付的实际执行记录，包括构建记录、测试报告、部署记录和发布记录。
- 按图中阶段顺序逐步对照，确认每个阶段在实际交付中是否发生、发生顺序是否与图一致。
- 记录偏差：实际存在但图中没有的阶段、实际执行了但图中未标注的门禁、实际由他人完成但图中未写责任人的环节。
- 对每处偏差判断是图的问题还是执行的问题。图漏画则补图；执行跳步则记录为例外并明确后续约束。
- 修正图后更新版本号，同步到团队实际使用的文档或工作项中，并通知相关角色。
走查记录建议包含：样本交付名称、对照日期、偏差清单、修正内容和修正后的图版本。走查不必每次交付都做，但在图首次定稿、阶段调整或团队人员变动后应各做一次，确保图与执行保持同步。
完成检查：流水线图是否可用
最后用一份检查清单判断图是否达到可执行、可维护的程度。逐项核对，全部满足才视为可用。
| 检查项 | 通过标准 | 核对结果 |
|---|---|---|
| 阶段完整性 | 每个阶段都有输入、执行动作、产出物和完成标志 | □ 通过 □ 不通过 |
| 门禁标注 | 每类门禁标明判定位置、条件和阻断方式 | □ 通过 □ 不通过 |
| 失败路径 | 每个门禁都有对应的回退或转人工走向 | □ 通过 □ 不通过 |
| 角色与交接 | 每阶段有责任人和协作人，交接物与记录位置明确 | □ 通过 □ 不通过 |
| 边界说明 | 交付对象、起点、终点和边界外内容已写明 | □ 通过 □ 不通过 |
| 走查一致性 | 已用一次真实交付走查，偏差已修正 | □ 通过 □ 不通过 |
| 维护责任 | 有明确的维护人和更新时机（如阶段调整、工具变更后） | □ 通过 □ 不通过 |
维护责任人和更新时机容易被忽略。图定稿后如果无人维护，几次流程调整后就会与实际执行脱节。建议指定一名流程负责人作为图的维护人，并在阶段增减、门禁条件变化、流水线工具更换时触发更新。更新后重新做一次走查，保证图始终能回答“这次交付走到哪一步、卡在什么条件上”。
常见问题
流水线图应该画到生产发布为止，还是画到制品入库就够了？
取决于团队用什么事件判断“一次交付完成”。如果发布操作由独立团队执行、流水线只负责产出可部署制品，画到制品入库即可；如果团队需要追踪从变更到用户可用的完整链路，建议画到生产发布完成并验证通过。终点越靠后，图与发布操作的耦合越深，维护成本也越高，需要有人持续跟进。
门禁设成硬阻断还是软阻断，怎么取舍？
看违规后果是否可逆。测试不通过、高危漏洞未修复这类问题一旦流入生产代价高，适合硬阻断；格式规范、低等级告警这类问题可以软阻断，记录后由负责人确认放行。软阻断要写明确认人和确认记录位置，否则容易变成默认放行。
团队规模小、角色由一人兼任，图里还要标角色吗？
要标。角色标注的作用是明确每个阶段的完成标志由谁负责，兼任时可以在角色后注明同一人，但阶段责任不能合并省略。人员变动时，图能直接指出哪些阶段需要交接，避免出现无人认领的环节。
走查发现实际执行跳过了图中某个阶段，应该改图还是改执行？
先判断该阶段是否承担必要的判定作用。如果它产出的是后续阶段必需的输入或门禁结论，属于执行跳步，应记录为例外并明确后续约束；如果它只是历史遗留、实际不产生判定价值，可以合并或删除，同步更新图版本并通知相关角色。
图定稿后多久需要复核一次？
没有固定周期，按触发条件更新更实际：阶段增减、门禁条件变化、流水线工具更换、团队人员变动后各做一次走查。日常可以指定一名流程负责人作为维护人，收集执行中的偏差反馈，积累到一定程度统一修订，避免图频繁改版导致团队无所适从。
