研发消息集成把代码提交、合并请求、流水线结果、缺陷变更、发布审批等研发事件，按统一规则转换成消息，再路由到对应的人、群或工单渠道，并保留可追溯记录。落地时先确定事件清单与消息字段，再定义路由规则和分级策略，随后选择接入方式，最后用去重、聚合、失败重试和送达核对保证消息可信。本文按事件、路由、接入、分工、示例与核对六个环节展开。
要点总览（TL;DR）
- 研发消息集成先定事件清单：按代码托管、流水线、缺陷与需求、发布与审批四类来源，逐条标注触发条件、接收角色、期望动作和时效要求，并区分实时推送与汇总推送。
- 消息统一六项必备字段（事件类型、项目/仓库、责任人、严重级别、链接、发生时间），路由按项目、团队、值班角色和严重级别组合，两到三个维度即可覆盖多数场景。
- 接入方式按来源系统是否支持主动推送、延迟要求和是否已有集成平台选择，配置依次完成凭证与回调地址、触发条件、测试消息、送达确认四步。
- 平台管理员、研发团队负责人、值班响应人三类角色分别对应配置维护、口径确认、接收处理，交付物包括事件清单、字段规范、配置记录和运行记录。
- 上线前核对事件覆盖、测试送达、凭证与权限，运行中关注消息量异常、重复漏发和失败重试，并随组织调整定期复核清单与规则。
先定事件清单：哪些研发动作需要变成消息
消息集成的第一步是划定范围：把研发活动中值得通知的动作逐条列出来，形成事件清单。清单没有定下来就配置渠道，容易出现该通知的没通知、不重要的事件刷屏、上线后不断补配置的情况。事件清单的完成标志是：每个事件都能说清来源系统、触发条件、接收角色、期望动作和时效要求，并且研发团队负责人确认过范围。
按研发阶段梳理来源系统，可以避免遗漏：
- 代码托管：合并请求创建、评审通过、合并完成、分支删除、保护分支被直接推送。
- 流水线：构建失败、构建恢复、部署到测试或生产环境、流水线超时。
- 缺陷与需求：缺陷被指派、缺陷升级为严重级别、需求状态变更、验收未通过。
- 发布与审批：发布单提交、审批通过或驳回、发布窗口开始、回滚触发。
每个事件在清单中标注五项信息：触发条件（什么情况下产生消息）、接收角色（谁需要知道）、期望动作（收到后要做什么）、时效要求（实时还是汇总）、来源系统（事件从哪里产生）。期望动作这一列最容易被忽略，但它决定了消息是否值得发——如果接收人收到后没有明确动作，这条消息大概率是噪音。
时效要求需要做一次明确区分。流水线失败、生产发布审批、严重缺陷指派这类事件影响当前工作，适合实时推送；代码提交明细、每日构建统计、缺陷存量变化这类事件适合按小时或按天汇总后推送。把可汇总的事件做成实时推送，是消息量失控的常见原因。
| 事件名称 | 来源系统 | 触发条件 | 接收角色 | 期望动作 | 时效要求 |
|---|---|---|---|---|---|
| 流水线构建失败 | 流水线平台 | 主干或发布分支构建失败 | 提交人、项目负责人 | 定位失败阶段并修复或回滚 | 实时 |
| 合并请求待评审 | 代码托管 | 合并请求创建且超过约定时长未评审 | 指定评审人 | 完成评审或转交 | 实时 |
| 严重缺陷指派 | 缺陷管理 | 缺陷级别为严重及以上且被指派 | 责任人、测试负责人 | 确认并给出处理计划 | 实时 |
| 发布审批通过 | 发布审批 | 发布单审批状态变为通过 | 发布执行人、值班 | 按窗口执行发布 | 实时 |
| 每日构建统计 | 流水线平台 | 每日固定时间汇总 | 研发团队负责人 | 关注趋势异常 | 汇总 |
事件与工作项状态本身是联动的：缺陷指派、需求状态变更、发布审批结果都对应工作项上的一次状态变化。ONES 可以承载研发工作项与状态流转，消息通知围绕这些状态变化发出，适合把事件清单中的“期望动作”落到具体工作项上，便于后续追溯。具体通知配置方式以实际环境为准。
设计消息字段与路由规则
事件清单确定后，要解决两个问题：消息里写什么，发给谁。字段规范保证同一种事件在任何渠道里表述一致，路由规则保证消息落到能处理它的人手里。这两份规范应在配置渠道之前定稿，否则每条消息都要单独调整。
消息必备字段建议统一为六项：
- 事件类型：与事件清单中的名称一一对应，便于检索和统计。
- 项目或仓库标识：说明消息属于哪个项目、哪个仓库或哪个分支。
- 责任人：当前需要处理的人，没有明确责任人时标注责任团队。
- 严重级别：用于路由和提醒强度，级别口径由研发团队负责人确认。
- 链接：指向日志、合并请求、缺陷单或发布单，接收人点开即可处理。
- 发生时间：事件产生的时间，便于判断消息是否延迟。
路由维度通常组合使用：按项目分发到项目群，按团队分发到团队群，按值班角色分发到当班人，按严重级别决定是否同时登记工单或升级到更高层级。组合时要控制层级数量，两到三个维度足够覆盖多数场景，维度过多会让规则难以维护、难以排查。
消息模板与命名规范解决表述不一致的问题。同一事件在不同渠道出现“构建挂了”“流水线失败”“CI 失败”等多种说法，会增加检索和统计成本。建议为每个事件类型固定一个标题格式，例如“【流水线失败】项目名 / 分支 / 失败阶段”，正文按字段顺序排列，链接放在固定位置。
| 字段 | 定义 | 是否必填 | 示例 |
|---|---|---|---|
| 事件类型 | 事件清单中的标准名称 | 必填 | 流水线构建失败 |
| 项目/仓库 | 所属项目与仓库、分支 | 必填 | 订单服务 / main |
| 责任人 | 当前处理人或责任团队 | 必填 | 提交人姓名 |
| 严重级别 | 按团队确认的口径标注 | 必填 | 高 |
| 链接 | 日志、单据或详情页地址 | 必填 | 构建日志地址 |
| 发生时间 | 事件产生时间 | 必填 | 具体到分钟 |
路由规则表按“条件—目标渠道—提醒方式”三列记录，例如：严重级别为高且属于生产发布的事件，发送到发布值班群并同时创建工单；普通构建失败只发送到项目群并@提交人。规则表定稿后，配置工作就是逐条实现这张表，排查问题时也能直接对照。
选择接入方式并完成配置
接入方式决定消息如何从来源系统到达渠道。常见方式有四类，选择依据是来源系统是否支持主动推送、对延迟的要求以及团队是否已有集成平台。
| 接入方式 | 适用情况 | 注意事项 |
|---|---|---|
| Webhook 推送 | 来源系统支持事件回调，要求实时 | 需校验回调地址，处理重复投递 |
| 开放接口轮询 | 来源系统只提供查询接口 | 轮询间隔决定延迟，需记录上次拉取位置 |
| 消息机器人 | 目标是群聊渠道，消息格式较简单 | 机器人权限范围要限定在目标群 |
| 集成平台中转 | 来源系统多、路由规则复杂 | 平台本身成为需要维护的组件 |
配置按固定顺序推进，每一步都有完成标志：
- 创建凭证与回调地址：在来源系统或集成平台生成访问凭证，登记回调地址。完成标志是凭证归属人明确、地址记录在配置记录中。
- 设置触发条件：按事件清单配置哪些动作产生消息，与路由规则表逐条对应。完成标志是触发条件与清单一致。
- 发送测试消息：用真实或构造的事件触发一次，检查字段是否齐全、格式是否符合模板。完成标志是测试消息内容与字段规范一致。
- 确认送达：在目标群、个人或工单中确认收到，并核对发送时间与事件时间。完成标志是接收方确认收到且延迟在可接受范围。
权限与安全有三项前提需要在上线前落实：凭证由固定角色保管并记录归属，避免离职后无人知晓；回调地址做来源校验，防止伪造请求触发消息；消息内容对密钥、内网地址等敏感信息做脱敏，链接指向需要登录才能访问的详情页，不直接暴露日志全文。
角色分工与交付物
消息集成上线后失管，通常不是技术问题，而是职责没有落到人。三类角色需要在上线前明确，每类角色对应固定的交付物。
| 角色 | 职责 | 交付物 | 确认人 |
|---|---|---|---|
| 平台/工具管理员 | 维护接入配置、凭证与渠道，处理发送失败 | 配置记录、运行记录 | 研发团队负责人 |
| 研发团队负责人 | 确认事件范围、路由对象与严重级别口径 | 事件清单、字段规范、路由规则表 | 平台管理员 |
| 值班或响应人 | 接收消息，按约定动作处理并反馈结果 | 处理记录、闭环回填 | 研发团队负责人 |
交付物归属要写清楚：事件清单由研发团队负责人确认，配置记录由平台管理员维护，运行记录由平台管理员按周期整理，处理反馈由值班或响应人在消息或工单中回填。四份交付物中，运行记录最容易被省略，但它是判断消息量是否异常、失败重试是否生效的依据，应在机制建立时就确定记录位置和更新频率。
职责边界也需要说明：平台管理员负责通道可用，不负责判断某条消息该不该发；研发团队负责人负责口径，不直接操作配置；值班响应人负责处理，不修改路由规则。规则调整走负责人确认、管理员执行的路径，避免配置被随意改动。
示例：一条流水线失败消息的完整链路
以下为演示情景，用于说明各环节如何衔接，实际字段和渠道按团队规范调整。
触发：订单服务仓库的 main 分支触发流水线，构建阶段失败。流水线平台产生一条构建失败事件，包含项目、分支、失败阶段和提交人信息。
转换：按字段规范生成消息，标题为“【流水线失败】订单服务 / main / 构建阶段”，正文包含责任人（提交人）、严重级别（主干分支失败，标为高）、发生时间和构建日志链接。
路由：按路由规则表，主干分支失败属于高严重级别，消息发送到项目群并@提交人，同时在缺陷或工单系统中登记一条待处理记录，关联对应工作项。
响应与闭环：提交人在群内确认收到，定位到依赖版本问题，修复后重新触发流水线。构建恢复后，提交人在工单记录中回填处理结果，工单关闭。平台管理员在运行记录中登记本次消息的发送与恢复时间，用于后续核对延迟和重复情况。
这条链路可以迁移到其他事件：把“构建失败”换成“发布审批驳回”，把“项目群+工单”换成“发布值班群+发布单状态回退”，字段、路由、响应、闭环四个环节的结构保持不变。迁移时只需修改事件清单中的一行和路由规则表中的对应条件。
完成检查：上线前与运行中的核对项
消息集成是否可用，用两份清单判断：上线前确认机制完整，运行中确认持续可控。每项检查都应有通过标准和负责人，避免检查流于形式。
| 阶段 | 检查项 | 通过标准 | 负责人 | 复核周期 |
|---|---|---|---|---|
| 上线前 | 事件覆盖 | 事件清单中的每个事件都已配置并有测试记录 | 平台管理员 | 上线前一次 |
| 上线前 | 测试送达 | 每类事件至少一条测试消息在目标渠道确认收到 | 平台管理员 | 上线前一次 |
| 上线前 | 凭证与权限 | 凭证归属人明确，回调地址校验生效，敏感字段已脱敏 | 平台管理员 | 上线前一次 |
| 运行中 | 消息量 | 每日消息量与事件清单预期量级相符，无突增 | 平台管理员 | 每周 |
| 运行中 | 重复与漏发 | 抽样核对来源事件与送达消息，重复和漏发可被发现并记录 | 平台管理员 | 每月 |
| 运行中 | 失败重试 | 发送失败有重试记录，重试结果可查 | 平台管理员 | 每月 |
| 定期复核 | 清单与规则更新 | 组织、项目或值班安排调整后，事件清单与路由规则同步更新 | 研发团队负责人 | 每季度或组织调整时 |
运行中还要关注两类信号：消息量明显偏离预期，通常意味着触发条件过宽或出现重复投递；某类事件长期没有消息，可能是来源系统变更导致回调失效。两类信号都应进入运行记录，由平台管理员排查后更新配置或规则。
定期复核的重点是清单与规则是否还匹配当前组织。项目合并、团队调整、值班轮换都会让原有路由失效，复核时逐条对照事件清单中的接收角色和路由规则表中的目标渠道，确认仍然有效，失效的条目当场修订并记录变更时间。
常见问题
事件清单定下来之后，业务又提出新的通知需求，应该怎么处理？
把新需求先补进事件清单，而不是直接去改配置。补录时同样填写触发条件、接收角色、期望动作和时效要求，由研发团队负责人确认后再由平台管理员配置。这样新事件与已有事件使用同一套字段和路由口径，避免出现临时规则。如果新需求与现有事件重复，优先调整原事件的接收角色或路由条件，减少事件数量。
消息量突然变大，通常先查哪里？
先对照运行记录看增量集中在哪类事件，再检查三个位置：触发条件是否被放宽（例如把分支范围从主干扩大到全部分支）、是否存在重复投递（同一事件短时间多次送达）、是否有可汇总的事件被改成了实时推送。排查顺序从触发条件开始，因为这一层改动最常见，也最容易恢复。
来源系统只提供查询接口、不支持主动推送，还能做消息集成吗？
可以，采用开放接口轮询的方式。需要确定轮询间隔（间隔决定消息延迟）、记录上次拉取位置以避免漏读或重复，并把轮询任务本身纳入运行记录。轮询方式对实时性要求高的事件不太合适，这类事件可考虑由集成平台中转或推动来源系统开放回调。
值班轮换或项目合并后，路由规则要怎么跟着调整？
把这类调整纳入定期复核：值班轮换时更新按值班角色分发的目标人，项目合并时合并对应项目群并清理失效条目，团队调整时同步修改接收角色。每次变更记录变更时间和确认人，避免出现消息仍发往已解散群组的情况。复核周期建议每季度一次，组织调整时立即执行。
消息里包含日志链接和内网地址，安全上要注意什么？
三项措施在上线前落实：凭证由固定角色保管并登记归属人；回调地址做来源校验，防止伪造请求触发消息；消息正文对密钥、内网地址等敏感信息脱敏，链接指向需要登录才能访问的详情页，不直接暴露日志全文。消息渠道的可见范围也应限定在目标群或目标人。
