流水线变量管理完整指南 Skill 概述
Skill 名称: Pipeline Variable Management 适用场景: 流水线变量的全生命周期管理与字段扩展 重要性: ⭐⭐⭐⭐ (高优先级) 文档版本: 2.0 最后更新: 2025-01
流水线变量是 BK-CI 流水线中的核心功能，支持在流水线编排、构建执行过程中动态传递和管理数据。本 Skill 提供变量管理的两大核心主题：
变量生命周期 - 变量从创建到销毁的完整流程 变量字段扩展 - 如何扩展变量的数据结构 一、变量管理架构概览 1.1 变量的定义与作用
流水线变量是流水线中用于存储和传递数据的核心机制，支持：
✅ 配置参数化 - 将流水线配置中的固定值替换为变量 ✅ 数据传递 - 在不同 Stage/Job/Task 之间传递数据 ✅ 动态计算 - 运行时动态生成和更新变量值 ✅ 用户输入 - 手动触发时由用户输入参数值 ✅ 系统内置 - 提供系统级别的预定义变量 1.2 变量的两种核心模型
BK-CI 中流水线变量存在两种数据模型的双向转换：
- BuildFormProperty（后端内部模型） 位置: common-pipeline/src/main/kotlin/.../BuildFormProperty.kt 用途: 微服务内部使用，数据库存储格式 特点: 完整的字段定义，包含 Swagger 注解 应用: Process 模块内部处理、数据持久化
- Variable（YAML 模型） 位置: common-pipeline-yaml/src/main/kotlin/.../yaml/v3/models/Variable.kt 用途: YAML 流水线定义，对外 API 交互 特点: Jackson 注解，支持 JSON 序列化 应用: PAC 流水线、OpenAPI 接口
- 转换器（VariableTransfer） 位置: common-pipeline-yaml/src/main/kotlin/.../yaml/transfer/VariableTransfer.kt 职责: 实现 BuildFormProperty ↔ Variable 的双向转换 核心方法: transfer(BuildFormProperty): Variable - 内部模型 → YAML 模型 transfer(Variable): BuildFormProperty - YAML 模型 → 内部模型 1.3 变量的存储与传递 ┌─────────────────────────────────────────────────────────────────┐ │ 变量存储与传递架构 │ └─────────────────────────────────────────────────────────────────┘
┌──────────────────┐ │ 流水线配置存储 │ BuildFormProperty │ (T_PIPELINE_*) │ 存储在 Model JSON 中 └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 构建启动 │ 读取变量定义 │ (StartBuild) │ 初始化变量值 └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 运行时变量存储 │ T_PIPELINE_BUILD_VAR │ (BuildVar) │ 构建级别的变量实例 └────────┬─────────┘ │ ├─────────────────┬─────────────────┐ ▼ ▼ ▼ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ Stage 1 │ │ Stage 2 │ │ Stage 3 │ │ 继承 + 新增 │ │ 继承 + 更新 │ │ 继承 + 输出 │ └────────────────┘ └────────────────┘ └────────────────┘
二、两大核心主题 2.1 变量生命周期管理
覆盖内容：
🔄 变量创建与初始化 📦 变量存储机制 🔀 变量传递与继承 🔄 变量动态更新 🔍 变量查询与调试
典型场景：
理解变量在构建执行过程中的完整流转 开发新的变量初始化逻辑 调试变量传递问题 实现变量的动态更新功能
查阅文档: reference/1-lifecycle.md (1414 行)
2.2 变量字段扩展
覆盖内容：
🆕 新增变量字段 🔧 字段类型定义 🔄 模型转换处理 🎯 前后端字段同步
典型场景：
为变量添加新的属性字段 扩展变量类型 处理历史数据兼容性 同步前后端字段定义
查阅文档: reference/2-extension.md (534 行)
三、使用指南 3.1 场景 1：理解变量生命周期
问题示例：
"变量值是如何从流水线配置传递到构建执行的？" "插件如何获取和更新变量值？" "变量的作用域是如何控制的？"
操作： 查阅 reference/1-lifecycle.md
内容包含：
变量生命周期全景图 六个关键阶段详解 变量存储表结构 变量传递机制 调试方法与常见问题 3.2 场景 2：扩展变量字段
问题示例：
"如何为变量添加一个新的 allowModify 字段？" "如何扩展变量的可选值列表？" "如何确保新字段在 YAML 和内部模型之间正确转换？"
操作： 查阅 reference/2-extension.md
内容包含：
变量字段扩展完整路径 BuildFormProperty 字段定义 Variable (YAML) 字段定义 VariableTransfer 转换器实现 前端字段同步 测试与验证 四、核心类与文件速查 4.1 变量定义类 类名 位置 用途 BuildFormProperty common-pipeline/.../BuildFormProperty.kt 后端内部变量模型 Variable common-pipeline-yaml/.../Variable.kt YAML 变量模型 VariableTransfer common-pipeline-yaml/.../VariableTransfer.kt 模型转换器 4.2 变量处理服务 类名 位置 职责 PipelineVariableService process/biz-base/.../PipelineVariableService.kt 变量业务逻辑 BuildVariableService process/biz-base/.../BuildVariableService.kt 构建变量管理 VariableAcrossInfoUtil process/biz-base/.../VariableAcrossInfoUtil.kt 跨 Job 变量传递 4.3 数据库表 表名 用途 T_PIPELINE_BUILD_VAR 构建级别的变量实例（运行时） T_PIPELINE_SETTING 流水线配置（包含变量定义） T_PIPELINE_MODEL_TASK 插件配置（引用变量） 五、开发流程 5.1 变量功能开发流程 1. 明确需求 ↓ 2. 确定涉及的生命周期阶段 │ → 查阅 reference/1-lifecycle.md ↓ 3. 是否需要扩展字段？ ├─ 是 → 查阅 reference/2-extension.md │ 执行字段扩展流程 ↓ 4. 实现后端逻辑 │ → 修改 Service/DAO 层 ↓ 5. 前端同步（如需） │ → 更新 Vue 组件 ↓ 6. 测试验证 │ → 单元测试 + 集成测试 ↓ 7. 文档更新
5.2 常见开发任务 任务 参考文档 关键类 新增变量类型 2-extension.md BuildFormProperty, Variable 变量初始化逻辑 1-lifecycle.md BuildVariableService 跨 Job 传递 1-lifecycle.md VariableAcrossInfoUtil 变量权限控制 1-lifecycle.md PipelineVariableService 变量表达式解析 - utility-components Skill (reference/2-expression-parser.md) 六、与其他 Skill 的关系 6.1 依赖的 Skill pipeline-model-architecture - 理解变量在 Model 中的位置 process-module-architecture - 理解变量处理的代码架构 utility-components (reference/2-expression-parser.md) - 变量引用的表达式解析 6.2 被引用的场景 PAC 流水线 → 变量在 YAML 中的定义 流水线编排 → 变量的创建和配置 构建执行 → 变量的初始化和传递 插件开发 → 插件如何读取和更新变量 七、详细文档导航 文档 内容 行数 文件大小 1-lifecycle.md 变量生命周期完整流程 1414 78.7KB 2-extension.md 变量字段扩展指南 534 20.2KB
使用建议:
初学者：先阅读本文档了解整体架构，再深入 1-lifecycle.md 开发者：根据具体开发任务直接查阅对应的 reference 文档 调试：优先查阅 1-lifecycle.md 中的调试章节 八、常见问题 FAQ Q1: 变量和参数有什么区别？
A: 在 BK-CI 中，"变量"和"参数"本质上是同一个概念，都是 BuildFormProperty。区别在于使用场景：
参数：流水线启动时用户输入的变量 变量：流水线内部定义和使用的变量 Q2: 如何实现跨 Stage 传递变量？
A: 查阅 reference/1-lifecycle.md 中的"阶段四：跨容器传递"章节，了解 VariableAcrossInfoUtil 的使用。
Q3: 新增字段后前端不显示怎么办？
A: 按照 reference/2-extension.md 的"步骤 4：前端字段同步"章节，确保前端 Vue 组件已同步更新。
Q4: 变量值为空或不正确？
A: 查阅 reference/1-lifecycle.md 中的"调试方法"章节，使用日志和数据库排查。
九、版本历史 版本 日期 更新内容 2.0 2025-01 整合 pipeline-variable-lifecycle 和 pipeline-variable-extension，采用 reference 结构 1.x 2024-12 独立的两个 Skill