企业官网建设流程全解析

• 物联网
• 后端
• 数据可视化
• 消息队列

导读

在 ThingsBoard 中，当 Edge（边缘节点）与服务器建立或断开连接时，系统可以通过通知规则向租户用户、客户用户发送邮件、短信、Slack 等渠道的提醒。本文围绕 Edge 连接通知模板化文档 展开，系统讲解 Edge 连接通知的可用模板参数、${...}占位符语法、值修饰后缀（upperCase/lowerCase/capitalize）以及基于翻译键的本地化机制，并结合仓库源码说明参数在服务端是如何被填充与处理的。读完本文，你将能够为 ThingsBoard Edge 连接通知编写包含 Edge 名称、连接状态与接收人信息的动态模板，并实现多语言通知。

Edge 连接通知的触发与模板数据来源

在讲解模板参数之前，先了解通知从何而来。ThingsBoard 的通知规则系统里，Edge 连接事件由EDGE_CONNECTION类型的触发器捕获。核心实现位于 EdgeConnectionTriggerProcessor.java：

• matchesFilter()判断当前连接事件是否命中规则配置：事件必须是配置的notifyOn集合中指定的CONNECTED或DISCONNECTED；若规则指定了 Edge 白名单（edges），则只有名单内的 Edge 事件才触发通知，名单为空时表示所有 Edge 都触发；
• constructNotificationInfo()将触发事件转换为EdgeConnectionNotificationInfo，其中eventType根据连接状态被置为字符串"connected"或"disconnected"，同时携带edgeId、edgeName、tenantId、customerId。

这些字段最终通过 EdgeConnectionNotificationInfo.java 的getTemplateData()暴露给模板引擎，成为通知模板中可直接引用的参数来源。

可用模板参数一览

通知的主题（subject）、正文（message）以及动作按钮文本（button）均支持模板化。可用的参数集合由模板类型决定——Edge 连接通知支持的参数如下：

其中edgeId、edgeName、eventType三个参数由触发事件本身提供（见 EdgeConnectionNotificationInfo.java 的getTemplateData()），而recipient*系列参数则由接收人信息动态注入，在发送时由 NotificationProcessingContext.java 的getProcessedTemplate()按接收人逐个填充。这也意味着：同一规则模板发给不同接收人时，recipient*部分会根据各自档案生成不同内容。

${...}占位符与值修饰后缀

参数名必须用${...}包裹才能被模板引擎识别。例如Edge '${edgeName}' is now ${eventType}。

除了直接引用原始值，还可以通过冒号连接的后缀修改参数值的呈现形式，共支持三种修饰后缀：

这些后缀在服务端的统一实现位于 TemplateUtils.java：模板参数通过正则\$\{(.+?)(:[a-zA-Z]+)?\}解析，upperCase、lowerCase、capitalize分别映射到String::toUpperCase、String::toLowerCase与 Apache Commons 的StringUtils::capitalize。

用 translate 后缀实现多语言通知

通知模板同样支持本地化。使用方式是在模板中引用翻译键（translation key）：

${some.translation.key:translate}

translate后缀会把some.translation.key当作翻译键，在接收人语言对应的翻译文件中查找实际文本。核心规则如下：

• 模板本身是接收人语言的翻译源——例如自定义翻译键custom.notifications.greetings的值为Hello, ${recipientFirstName}!，那么模板${custom.notifications.greetings:translate}会被转换成Hello, John!；
• 翻译内容中的嵌套占位符（如recipientFirstName）会继续按接收人信息解析；
• 接收人语言取自其个人档案（profile）中的 locale 设置，未设置时默认使用英语（Locale.US）。这一点与 NotificationProcessingContext.java 中recipient instanceof User user ? user.getLocale() : Locale.US.toString()的逻辑一致：非用户类型的接收人一律回退到英语。

translate后缀可以与值修饰后缀组合使用，例如${custom.notifications.greetings:translate:capitalize}，翻译完成后再对结果做文本修饰。

完整示例：Edge 连接通知模板

以下面这条 Edge 连接通知模板为例（主题或消息均可使用）：

Edge '${edgeName}' is now ${eventType}

当名为DatacenterEdge的 Edge 建立连接时，实际渲染结果为：

Edge 'DatacenterEdge' is now connected

在此基础上可组合各类参数构造更丰富的通知，例如结合recipient参数与修饰后缀：

Hello, ${recipientFirstName:capitalize}! Edge '${edgeName:upperCase}' is now ${eventType} (id: ${edgeId})

若接收人名字为john，首行渲染为Hello, John!；Edge 名datacenter-edge渲染为DATACENTER-EDGE。

配置与调试提示

• Edge 连接通知规则的可配置项（通知事件类型notifyOn与 Edge 白名单edges）定义在 EdgeConnectionNotificationRuleTriggerConfig.java，其中edges为空集合表示全部 Edge 均触发；
• 模板化同样适用于主题、消息与按钮文本（NotificationTemplate及其按投递渠道划分的DeliveryMethodNotificationTemplate结构，见 NotificationProcessingContext.java），即邮件标题、正文、短信内容、Slack 文案等均可使用同一套${...}语法；
• 排错时优先确认：占位符是否拼写正确且已用${}包裹、使用的参数是否属于 Edge 连接通知支持列表、translate引用的翻译键是否存在、接收人档案是否设置了期望的 locale（否则回退英文）。

结语

Edge 连接通知模板化是 ThingsBoard 通知体系中把"事件数据 + 接收人数据 + 翻译文件"三类信息组合成最终文案的核心机制。掌握${edgeName}、${eventType}等参数、upperCase/lowerCase/capitalize修饰后缀与translate本地化后缀，即可针对租户与客户场景构建可读、可国际化、随事件实时变化的连接状态提醒。

• 物联网
• 后端
• 数据可视化
• 消息队列