BK-CI 项目中 Matrix Job 的 Include/Exclude 语法优化解析

背景介绍

在持续集成/持续交付(CI/CD)领域，Matrix Job是一种强大的功能，它允许开发者通过定义多个维度的变量组合来自动生成并并行执行多个任务。BK-CI作为一款优秀的CI/CD工具，近期对其Matrix Job功能进行了语法优化，特别是针对include/exclude关键字的处理方式进行了改进。

传统Matrix Job语法

在传统的BK-CI配置中，Matrix Job的include/exclude是作为matrix下的保留关键字使用的，其语法结构如下：

strategy:
    matrix: 
        os: [windows, linux]
        version: [10, 12]
        include:
            - os: macos
              version: 14
        exclude:
            - os: windows
              version: 10
    fast-kill: false
    max-parallel: 5

这种语法结构中，matrix定义主要变量组合，include用于添加额外的组合，exclude用于排除特定的组合。这种设计在大多数情况下工作良好，但当所有三个部分(matrix/include/exclude)都需要动态生成时，就显得不够灵活。

语法优化内容

BK-CI团队对Matrix Job语法进行了两项重要优化：

1. 支持与matrix关键字平级：现在include/exclude可以直接与matrix关键字平级，使得三个部分都可以是动态生成的变量。

strategy:
    matrix: "${{ fromJSON(jobs.prepare.steps.set-matrix.outputs.parameters) }}"
    include: "${{ fromJSON(jobs.prepare.steps.set-matrix.outputs.include) }}"
    exclude: "${{ fromJSON(jobs.prepare.steps.set-matrix.outputs.exclude) }}"
    fast-kill: false
    max-parallel: 5

2. 保持向后兼容：原有的将include/exclude作为matrix下保留关键字的语法仍然有效，确保现有配置不会因升级而失效。

技术实现分析

这种语法优化的实现需要考虑几个关键点：

1. 解析器增强：BK-CI的YAML解析器需要能够识别两种不同位置的include/exclude关键字，并正确处理它们的语义。

2. 变量替换机制：支持从JSON字符串动态解析matrix/include/exclude内容，这要求变量替换阶段在解析完成后进行。

3. 组合逻辑一致性：无论采用哪种语法形式，最终生成的Job组合逻辑必须保持一致，即先应用matrix生成基础组合，然后应用include添加特殊组合，最后应用exclude排除特定组合。

实际应用场景

这种语法优化特别适用于以下场景：

1. 复杂参数生成：当matrix参数需要通过前置步骤动态计算得出时，可以将复杂的参数生成逻辑放在专门的prepare job中。

2. 参数来源多样化：当include/exclude规则需要从不同来源获取时，可以分别生成和引用。

3. 配置模板化：在需要复用基础配置但动态调整部分参数的情况下，这种语法提供了更大的灵活性。

最佳实践建议

基于这次语法优化，我们建议：

1. 简单场景：使用传统的嵌套语法，保持配置简洁。

2. 动态复杂场景：采用新的平级语法，将参数生成逻辑分离到专门步骤中。

3. 团队协作：在团队内部统一语法风格，避免混用造成理解困难。

4. 文档注释：对于复杂的动态生成配置，添加充分的注释说明参数来源和生成逻辑。

总结

BK-CI对Matrix Job语法的这次优化，既增强了动态配置的能力，又保持了向后兼容性，体现了工程上的深思熟虑。这种改进使得BK-CI在处理复杂构建矩阵时更加灵活强大，能够满足更广泛的自动化构建需求。对于使用者来说，理解这两种语法形式及其适用场景，将有助于编写出更清晰、更易维护的CI/CD配置。