tencentblueking/bk-ci/pipeline-model-architecture

BK-CI 流水线模型架构

适用场景

• 理解 Model -> Stage -> Container -> Element 的层级关系
• 修改流水线模型字段、结构或校验逻辑
• 新增容器类型、插件类型或模型辅助结构
• 排查模型序列化、版本兼容、YAML 转换问题
• 判断一个需求应该落在模型定义、运行时状态还是持久化层

不适用场景

• 只是调度资源分配、构建机执行或插件运行问题
• 只是普通后端接口开发，不涉及流水线模型本身
• 只是数据库脚本设计，不涉及模型结构和模型存储

快速指导

1. 先把问题归到下面 5 类之一，再继续读对应参考文档：

• 结构定义：看 reference/1-core-structure.md
• 持久化与版本：看 reference/2-persistence-versioning.md
• 运行时、YAML、校验、扩展：看 reference/3-runtime-conversion-extension.md

1. Model 是流水线配置的核心载体，但不是所有运行时状态的权威来源。运行中的状态、耗时、重试等字段要区分“配置态”和“运行态”。
2. 触发容器是模型入口，默认位于第一个 Stage 的第一个 Container。很多参数、触发器和启动逻辑都从这里进入。
3. Container 和 Element 都是多态结构。新增类型时，不能只改一个类定义，通常还要一起检查：

• Jackson 多态序列化配置
• 前端编排模型
• 后端转换与校验
• 运行引擎或 Worker 识别逻辑

1. 版本兼容和 YAML 转换要一起考虑。模型字段一旦进入存量数据，就不能只从“当前新建流程”角度看。
2. 如果你修改的是流程控制、执行条件、Finally、Matrix 之类能力，优先确认它影响的是 Stage、Job 还是 Element 层。

高信号规则

• Model 关心的是“流水线如何定义”，Process 更关心“流水线如何被编排执行”
• Stage 表达阶段边界和流程控制，Container 更接近 Job，Element 更接近具体任务或插件
• id、stageIdForUser、插件 code、运行时状态字段，不是同一层次的概念，不能混用
• 只要涉及模型新增字段，就要同时检查序列化、兼容、默认值和历史版本读取

关键陷阱

• 把运行时字段直接当成持久化配置字段来修改，导致旧构建详情或历史快照异常
• 只改 Element/Container 类定义，不补多态声明、校验或前端侧映射
• 忽略 Finally、Matrix、运行条件这些特殊结构，按普通 Stage/Job 处理
• 只验证 UI 新建流程，没验证历史 Model 回放、重试、版本切换和 YAML 转换
• 看到问题出现在模型字段，就直接改模型，实际上问题可能在 Process 的执行链或转换层

延伸阅读

• 核心结构：reference/1-core-structure.md
• 持久化与版本：reference/2-persistence-versioning.md
• 运行时、转换与扩展：reference/3-runtime-conversion-extension.md
• 涉及执行链路归属时：先看 process-module-architecture
• 涉及 YAML/PAC 时：再看 yaml-pipeline-transfer