3. 管道参数基础：分类、作用域与优先级规则

在 Collector 管道配置中，参数是驱动数据采集、转换与输出的核心指令。理解参数的分类、作用域及优先级规则，是进行管道调优与故障排查的前提。本章将系统性地解析这三项基础概念，帮助你在配置过程中做出精准决策。

3.1 参数分类：必选、可选与高级

Collector 管道参数按使用场景与配置必要性分为三类。下表列出了每类参数的定义、典型示例及配置建议：

3.2 参数作用域：全局、组件级与任务级

参数的作用域决定了该参数在管道配置层次中的生效范围。Collector 管道采用三层作用域模型：

• 全局作用域（Global）：定义在管道配置文件的顶层，作用于整个管道实例，包括所有组件与任务。常用于设置日志级别、全局超时、共享密钥引用等。
• 组件级作用域（Component）：定义在特定组件（Source、Processor、Sink）的配置块内，仅对该组件及其子任务生效。例如，为某个 Source 单独设置采集间隔。
• 任务级作用域（Task）：定义在组件内部的子任务或线程配置中，作用范围最小，仅影响单个执行单元。适用于细粒度控制，如为某个数据转换任务指定不同的序列化格式。

下图展示了三层作用域在管道配置中的层级关系：

3.3 参数优先级规则

当同一参数名在不同作用域或不同配置源中出现时，Collector 管道遵循明确的优先级规则来决定最终生效值。理解这些规则可避免配置冲突导致的意外行为。

优先级从高到低排列如下：

1. 运行时环境变量：通过 COLLECTOR_<PARAM_NAME> 格式注入的变量，优先级最高，用于临时覆盖或敏感信息注入。
2. 任务级配置：组件内部子任务块中显式定义的参数。
3. 组件级配置：组件块（Source/Processor/Sink）中定义的参数。
4. 全局配置：管道配置文件顶层定义的参数。
5. 框架默认值：Collector 引擎内置的默认值，仅在以上层级均未定义时生效。

下表通过一个具体示例展示优先级覆盖过程：

3.4 参数冲突与合并策略

除了简单的覆盖规则外，部分参数（如标签列表、过滤器链）支持合并而非覆盖。Collector 管道采用以下合并策略：

• 标量参数（字符串、数字、布尔值）：严格遵循优先级覆盖规则，高优先级值完全替换低优先级值。
• 列表参数：默认采用“追加合并”，即高优先级列表追加到低优先级列表之后。可通过 override=true 标记强制覆盖。
• 映射参数（键值对）：按 key 进行深度合并，相同 key 的值按优先级覆盖，不同 key 的值共存。

以下代码片段展示了列表参数的合并行为：

# 全局配置
tags: ["env:prod", "team:platform"]

# 组件级配置（Source）
tags: ["source:kafka"]  # 默认追加合并

# 最终生效 tags：["env:prod", "team:platform", "source:kafka"]

# 若组件级配置显式声明 override：
tags: ["source:kafka"]
tags_override: true
# 最终生效 tags：["source:kafka"]