Token Macro 插件是 Jenkins 自动化生态中一块不可或缺的"基础设施"。它通过将宏扩展能力抽象为一个公共服务，消除了重复建设，统一了用户体验，并为整个 Jenkins 的灵活性和可扩展性奠定了坚实基础。对于使用者而言，掌握其语法和常见宏，能极大地提升配置效率和通知的实用性；对于开发者而言，遵循其规范进行扩展，可以让自己开发的插件更快地融入 Jenkins 生态。无论是简单的构建编号替换，还是复杂的动态信息组装，Token Macro 都是 Jenkins 高级用户和插件开发者手中一把强大的利器。
1. 插件概述：什么是 Token Macro？
在 Jenkins 的生态系统中，许多插件都需要在配置中嵌入动态内容，例如在邮件主题中显示构建编号，或在构建描述中显示 Git 提交 ID。早期，每个插件都不得不自行实现一套解析和替换这些"令牌"（Token）的机制，这不仅造成了功能重复，也导致了使用体验的不一致。
Token Macro 插件 正是为了解决这一问题而诞生的。它的核心定位是一个 "可重用的宏扩展能力提供者" [reference:0]。插件本身并不直接面向最终用户提供 UI 功能，而是作为底层引擎，为其他需要动态内容替换的插件（如 Email Extension、Description Setter 等）提供统一、强大的宏（Macro）解析与扩展服务[reference:1]。
简单来说，它定义了像 ${BUILD_NUMBER}、${GIT_REVISION,length=8} 这样的宏语法标准，并提供了执行这些宏扩展的公共接口。其他插件只需调用 Token Macro 提供的 API，即可获得统一的宏扩展能力，从而专注于自身的业务逻辑。
2. 安装与配置
Token Macro 插件的安装遵循 Jenkins 插件的标准流程：
- 进入 Jenkins 管理界面，依次点击 "系统管理" -> "插件管理" -> "可选插件"。
- 在搜索框中输入 "Token Macro"。
- 在搜索结果中找到该插件，勾选并点击"安装"即可。
- 安装完成后，通常需要重启 Jenkins 以使插件生效。
值得注意的是，Token Macro 作为一个基础服务插件，通常会在你安装其他依赖它的插件（如 Email Extension）时被自动安装。
3. 核心概念与使用方法
3.1 宏的基本语法
Token Macro 定义的宏语法直观且灵活，主要格式如下[reference:2]：
- 无参数宏 ：
${MACRO_NAME}或简化写法$MACRO_NAME。例如${BUILD_NUMBER}。 - 带参数宏 ：
${MACRO_NAME,param1=value1,param2=value2}。例如${GIT_REVISION,length=8}表示只取 Git 提交哈希的前8位[reference:3]。 - 多值参数 ：一个参数可以接受多个值，格式为
${MACRO_NAME,param=v1,param=v2,param=v3}。
3.2 在支持插件中使用宏
Token Macro 的能力通过其他插件展现。以下是一些典型的使用场景：
- Email Extension Plugin ：在邮件的主题 和内容 中广泛使用宏。你可以这样设置邮件主题：
构建 #${BUILD_NUMBER} - ${BUILD_STATUS}，使得每封通知邮件都能清晰反映本次构建的编号和结果[reference:4]。 - Description Setter Plugin ：在构建后步骤中，使用一个宏表达式来动态设置本次构建的显示描述。例如，表达式
构建于 ${BUILD_TIMESTAMP}，分支：${GIT_BRANCH}可以让构建历史一目了然[reference:5]。 - Instant Messaging Plugin：在配置发送给即时通讯工具（如 Slack）的消息模板时，使用宏来插入关键构建信息[reference:6]。
3.3 宏的转换操作
Token Macro 支持对宏展开后的结果进行类似 Bash shell 的字符串转换，这大大增强了其灵活性[reference:7]：
${#MACRO_NAME}：返回宏展开后结果的字符长度。${MACRO_NAME:START:LENGTH}：返回结果的子串。例如${GIT_REVISION:0:7}等同于${GIT_REVISION,length=7}。${MACRO_NAME#PATTERN}：移除结果开头匹配的 PATTERN。${MACRO_NAME%PATTERN}：移除结果末尾匹配的 PATTERN。
3.4 开发自定义宏
对于插件开发者，Token Macro 提供了清晰的扩展接口。创建一个自定义宏通常需要继承 DataBoundTokenMacro 类，它简化了参数绑定[reference:8]。
例如，Git 插件中定义的 GIT_REVISION 宏，其核心实现是解析构建数据，并根据 length 参数截取对应长度的提交 SHA1 字符串[reference:9]。社区或用户也可以遵循此模式开发满足特定需求的宏，如从特定文件中读取属性、调用外部 API 获取数据等。
4. 典型应用场景
- 增强通知可读性 ：在邮件、即时消息等通知中，通过宏动态插入项目名、构建编号、状态、触发原因、构建时长、代码变更者等信息，使通知内容精准且丰富。
- 动态构建描述：利用 Description Setter 插件，将 Git 分支、最后提交信息、版本号等关键信息自动设置为构建描述，便于在构建历史列表中快速定位。
- 条件化流程控制 ：在参数化构建或其他脚本中，通过宏获取环境信息（如
${NODE_NAME}），并基于此判断执行不同的逻辑步骤。 - 信息聚合与报告 ：在构建后步骤中，使用宏组合多个信息（如
构建 ${JOB_NAME} 在第 ${BUILD_NUMBER} 次运行中于节点 ${NODE_NAME} 上完成），并将其写入文件或发送到报告系统。 - 简化复杂配置：对于需要重复引用复杂路径或 URL 的场景，可以开发自定义宏来封装，从而简化各个作业的配置。
5. 最佳实践
- 优先使用内置宏 ：在尝试自定义开发前，先查阅 Token Macro 及已安装插件（如 Git、SVN）提供的内置宏列表。许多常见需求，如获取构建信息、环境变量、SCM 信息等，已有现成实现。
- 转义特殊字符 ：当模板中的美元符号
$需要作为普通字符使用时，必须使用$$进行转义，防止被误解析为宏的起始符[reference:10]。 - 在安全上下文中测试 ：宏扩展可能涉及敏感信息（如密码、密钥）。在正式使用前，务必在测试作业或使用
TokenMacro.expandAPI 的脚本中验证扩展结果是否符合预期，避免信息泄露。 - 关注性能影响：虽然单次宏扩展开销很小，但在一个模板中过度使用复杂宏，或在巨量构建中频繁调用，可能对性能产生累积影响。避免在循环或高频任务中嵌入计算密集型的自定义宏。
- 文档化自定义宏：如果你开发了供团队使用的自定义宏，必须为其编写清晰的文档，说明宏的名称、参数、返回值以及使用示例，这是维护团队协作效率的关键。
- 注意插件兼容性：在升级 Jenkins 或相关插件（尤其是 Token Macro 本身）时，需留意版本发布说明。虽然向后兼容性通常良好，但重大版本升级可能引入语法或 API 的变化，需要测试原有宏功能是否正常。