我做了一个 Jenkins 插件：让流水线按中国工作日运行

很多 Jenkins 流程都和日期有关，比如：

• 定时任务

• 发布流程

• 节假日停跑

• 调休上班时继续执行

但在中国语境里，工作日不等于周一到周五，周末也不一定都休息。

如果 Jenkins 只是简单按 weekday / weekend 判断，就很容易出现：

• 节假日误执行

• 调休工作日没触发

• Jenkinsfile 里到处写硬编码日期

所以我做了一个插件：Chinese Workday Plugin。

它能做什么？

它做的事情其实很简单：

让 Jenkins 按中国法定节假日和调休规则判断日期。

目前支持：

• isChineseWorkday(...)

• isChineseHoliday(...)

• chineseWorkdaySupportedYears()

也就是说，你可以直接在 Pipeline 里判断“今天是不是中国工作日”，而不是自己维护一套日期规则。

最常见的用法，就是控制某个 stage 只在中国工作日执行：

pipeline {
    agent any
    stages {
        stage('Release') {
            when {
                expression {
                    isChineseWorkday()
                }
            }
            steps {
                echo 'Release runs only on a Chinese workday.'
            }
        }
    }
}

为什么这个插件有用？

因为这类逻辑一旦分散在每个 Jenkinsfile 里，后面通常只会越来越难维护。

尤其是：

• 每年节假日会变

• 周末可能调休上班

• 未来年份可能还没准备好数据

所以我更希望把这件事沉淀成一个插件能力：

• 规则由插件统一实现

• 日期数据按年份维护

• 管理员可以在系统配置里补未来年份日历

这样，Jenkinsfile 只表达业务意图，不再承担节假日规则维护的责任。

实现原理

如果从实现角度看，这个插件并不是简单去判断“今天是不是周末”，而是把“中国工作日规则”拆成了日期解析、日历加载、规则判定三个步骤。

这样设计的核心目的，是把变化频繁的节假日数据，和相对稳定的判断逻辑分开。

1. 先确定要判断的日期

无论是 isChineseWorkday(...) 还是 isChineseHoliday(...)，插件都会先解析目标日期：

• 如果没有传 date，就使用 Asia/Shanghai 下的当前日期

• 如果传了 date，就按 yyyy-MM-dd 解析

这里固定使用 Asia/Shanghai，是为了避免 Jenkins 控制器所在机器时区不同而导致的判断偏差。对于这类和节假日相关的逻辑，先把“时间语义”统一，比后面补救要可靠得多。

2. 再加载“这一年”的有效日历

日期确定之后，插件会去加载“这一年”的有效日历。内部会把节假日数据按年份组织，再按统一优先级合并：

• 内置资源

• 外部文件覆盖

• Jenkins 系统配置覆盖

也就是说，默认先使用插件内置的数据；如果管理员额外补了配置，则以后者为准。

这套机制带来两个直接好处：

• 插件可以开箱即用

• 下一年数据还没内置时，或者无法升级插件时，管理员也能先补临时配置，不必等插件升级

3. 最后按规则判断是否为工作日

真正进入判定阶段时，顺序并不是“先看今天是周几”，而是：

• 先看是否命中调休工作日

• 再看是否命中法定节假日 / 非工作日

• 最后才回退到普通周末规则

这个顺序很关键，因为中国场景里最容易出错的，恰恰就是这些“例外规则”：

• 周末调休上班

• 工作日放假

换句话说，插件判断的不是“自然日历”，而是更贴近实际业务安排的“业务日历”。

为什么这样设计？

因为中国工作日规则本质上是数据驱动的，而不是一段可以长期写死的逻辑。

如果只是把规则硬编码在 Jenkinsfile 或 Java 代码里，后面很快就会遇到这些问题：

• 每年都要改

• 不方便管理员补数据

• 多个任务容易出现不一致实现

把它拆成“日期解析 + 年份日历加载 + 规则判断”这三层之后，职责会更清楚，后续扩展和维护也会更稳。

这也是为什么我更希望把它做成插件能力，而不是一段临时脚本：
规则应该统一，数据应该可维护，Pipeline 则只需要表达“什么时候执行”。

现在已经可用

如果你的 Jenkins 流程需要遵循中国节假日和调休安排，可以试试：

• Jenkins Plugin Site: https://plugins.jenkins.io/chinese-workday/

• GitHub: https://github.com/jenkinsci/chinese-workday-plugin

如果你也有类似场景，欢迎体验和反馈。