流水线变量管理完整指南

Skill 概述

Skill 名称: Pipeline Variable Management
适用场景: 流水线变量的全生命周期管理与字段扩展
重要性: ⭐⭐⭐⭐ (高优先级)
文档版本: 2.0
最后更新: 2025-01

流水线变量是 BK-CI 流水线中的核心功能，支持在流水线编排、构建执行过程中动态传递和管理数据。本 Skill 提供变量管理的两大核心主题：

1. 变量生命周期 - 变量从创建到销毁的完整流程
2. 变量字段扩展 - 如何扩展变量的数据结构

---

一、变量管理架构概览

1.1 变量的定义与作用

流水线变量是流水线中用于存储和传递数据的核心机制，支持：

• ✅ 配置参数化 - 将流水线配置中的固定值替换为变量
• ✅ 数据传递 - 在不同 Stage/Job/Task 之间传递数据
• ✅ 动态计算 - 运行时动态生成和更新变量值
• ✅ 用户输入 - 手动触发时由用户输入参数值
• ✅ 系统内置 - 提供系统级别的预定义变量

1.2 变量的两种核心模型

BK-CI 中流水线变量存在两种数据模型的双向转换：

1. BuildFormProperty（后端内部模型）

• 位置: common-pipeline/src/main/kotlin/.../BuildFormProperty.kt
• 用途: 微服务内部使用，数据库存储格式
• 特点: 完整的字段定义，包含 Swagger 注解
• 应用: Process 模块内部处理、数据持久化

2. Variable（YAML 模型）

• 位置: common-pipeline-yaml/src/main/kotlin/.../yaml/v3/models/Variable.kt
• 用途: YAML 流水线定义，对外 API 交互
• 特点: Jackson 注解，支持 JSON 序列化
• 应用: PAC 流水线、OpenAPI 接口

3. 转换器（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

内容包含：

1. 变量生命周期全景图
2. 六个关键阶段详解
3. 变量存储表结构
4. 变量传递机制
5. 调试方法与常见问题

3.2 场景 2：扩展变量字段

问题示例：

• "如何为变量添加一个新的 allowModify 字段？"
• "如何扩展变量的可选值列表？"
• "如何确保新字段在 YAML 和内部模型之间正确转换？"

操作： 查阅 reference/2-extension.md

内容包含：

1. 变量字段扩展完整路径
2. BuildFormProperty 字段定义
3. Variable (YAML) 字段定义
4. VariableTransfer 转换器实现
5. 前端字段同步
6. 测试与验证

---

四、核心类与文件速查

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