流水线变量管理完整指南
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 变量功能开发流程
- 明确需求 ↓
- 确定涉及的生命周期阶段 │ → 查阅 reference/1-lifecycle.md ↓
- 是否需要扩展字段？ ├─ 是 → 查阅 reference/2-extension.md │ 执行字段扩展流程 ↓
- 实现后端逻辑 │ → 修改 Service/DAO 层 ↓
- 前端同步（如需） │ → 更新 Vue 组件 ↓
- 测试验证 │ → 单元测试 + 集成测试 ↓
- 文档更新
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