第五章变量系统与步骤引用，如何深入理解其应用和原理？
摘要：layout: default title: "第五章：变量系统与步骤引用" 第五章：变量系统与步骤引用 GeoPipeAgent 流水线中有两种核心数据传递机制：变量替换（${var}）
第五章：变量系统与步骤引用
GeoPipeAgent 流水线中有两种核心数据传递机制：变量替换（${var}）和步骤引用（$step-id）。本章深入解析这两种机制的工作原理和使用技巧。
5.1 变量替换：${var_name}
5.1.1 基本用法
在 pipeline.variables 中定义变量，在步骤 params 中用 ${变量名} 引用：
pipeline:
variables:
input_path: "data/roads.shp"
buffer_dist: 500
output_crs: "EPSG:4326"
steps:
- id: load
use: io.read_vector
params:
path: "${input_path}" # → "data/roads.shp"
- id: buffer
use: vector.buffer
params:
input: "$load"
distance: "${buffer_dist}" # → 500 (数值类型)
- id: reproject
use: vector.reproject
params:
input: "$buffer"
target_crs: "${output_crs}" # → "EPSG:4326"
5.1.2 类型保留
当整个参数值是单一 ${var} 引用时，变量的原始 Python 类型被保留：
variables:
buffer_dist: 500 # int
tolerance: 0.001 # float
auto_fix: true # bool
fields: ["name", "type"] # list
# 传入步骤时类型不变
params:
distance: "${buffer_dist}" # → 500 (int)
tolerance: "${tolerance}" # → 0.001 (float)
auto_fix: "${auto_fix}" # → True (bool)
required_fields: "${fields}" # → ["name", "type"] (list)
5.1.3 字符串插值
当 ${var} 嵌入字符串中时，变量被转为字符串拼接：
variables:
project: "highway-2024"
suffix: ".geojson"
params:
path: "output/${project}${suffix}" # → "output/highway-2024.geojson"
layer: "buffer_${project}" # → "buffer_highway-2024"
5.1.4 通过 --var 在命令行覆盖
--var 参数以 key=value 格式传入，值始终是字符串。框架会尝试进行类型转换（字符串→数字/布尔）：
# 整数
geopipe-agent run pipeline.yaml --var buffer_dist=1000
# 浮点数
geopipe-agent run pipeline.yaml --var tolerance=0.005
# 布尔值（"true"/"1"/"yes" 转为 True）
geopipe-agent run pipeline.yaml --var auto_fix=true
# 字符串路径
geopipe-agent run pipeline.yaml --var input_path=data/new_roads.shp
# 多个变量
geopipe-agent run pipeline.yaml \
--var input_path=data/new.shp \
--var buffer_dist=200 \
--var output_path=output/new_buffer.geojson
注意：通过 --var 传入的值优先于 YAML 文件中 variables 的定义，且会修改 PipelineDefinition.variables 字典，影响所有引用该变量的步骤。