飞书报错提醒策略实战教程：把集成平台的异常第一时间推送到群

这个策略解决什么问题

在一个有 6 条同步策略的销售订单集成链路里，只要其中任意一条方案报错——比如目标系统鉴权过期、字段映射缺失、限流被拦截——值班同学就要尽快知道。传统做法是人工登录集成平台查看「方案错误明细」，等于是把发现问题的责任压在「记得去看」上。

「飞书报错提醒」这条策略做的是一件事：让集成平台自己开口说话。源端每隔几分钟轮询一次错误明细接口，把状态为「错误」的记录筛出来，组装成结构化消息，扔给飞书机器人 webhook。值班同事在群里就能看到「哪个方案、哪条数据、什么时候、出了什么问题」。它本身不搬运业务数据，只搬运「平台自身的健康状态」，是链路里典型的「元集成」策略。

数据流向与字段映射

整条链路是「平台 → 平台内部错误表 → 飞书机器人」，没有业务系统参与。关键字段对照如下：

需要注意，strategy_name 在源端是「number」维度的标识（接口分页键），在目标端变成展示文案，两边同名不同义，写映射脚本时不要想当然地复制字段值。

在轻易云上如何配置

在轻易云数据集成平台（Qeasy）中，这条策略由两个 WebAPI 组成，中间用「方案 ID 列表」做串接。

源端配置 StrategyErrorDetail，类型为查询型 WebAPI，请求体由 recentSeconds、ids、status 三段组成。ids 直接写死要监控的方案 ID 列表，多个 ID 用英文逗号分隔；status 默认填 3，意思是只看错误；如果想顺带把「重复」「队列中」也纳入监控，改成 3,1,5 即可，但告警噪音会明显上升，新上线阶段不建议。

目标端是飞书自定义机器人的 incoming webhook，路径 /bot/v2/hook，方法是 POST。这里有四个常见应对模式值得在客户现场复用：

1. 编码映射集中管理：webhook_id 不要散落在策略里，而是放到平台级的「参数配置」中统一维护，切换群或新建群只改一处。
2. 表头表体分阶段：告警消息建议先实现表头（方案名 + 时间），表体（错误明细链接）后续再补，避免一次性把模板做复杂导致上线延期。
3. 增量与全量双轨：源端用 recentSeconds 做增量轮询；如果担心遗漏，再单独配一条全量回查策略，固定在凌晨跑一次，做兜底。
4. 占位符命名规范：{{strategy_name}}、{{number}}、{{response_at\|datetime}} 这种写法直接照搬素材，不要临时换名，否则脚本解析会报错。

实施步骤

我们把上线分成三个阶段。

阶段一：增量起点。 第一次只配源端 StrategyErrorDetail 的查询，把 recentSeconds 设为 60、方案 ID 只写一个、status 固定 3。在轻易云里手动执行一次，确认返回结构里有 strategy_name、strategy_id、number、response_at 这几个字段，缺一个就补映射。

阶段二：全量触发。 把目标端 webhook 接上，飞书群里先用一个测试机器人验证消息体是否完整。重点验证两点：一是 {{response_at\|datetime}} 是否被正确格式化，二是超长 problem 字段是否被截断。飞书卡片对长文本有上限，超长要么做截断，要么换成 markdown 链接跳转到方案详情页。

阶段三：调度频率。 源端策略按 1-59/8 * * * * 触发，意思是每 8 分钟一次，错开整分钟避免堆积；目标端策略按 3-59/8 8-23 * * * 触发，工作时间内的第 3 分钟起跑。两个 cron 都刻意避开整点，并且目标端比源端晚 2 分钟，确保源端错误已经落库。这种「错峰 + 错分钟」是大量客户现场验证过的小细节。

踩坑复盘

1. 典型错误是 status 只传 3。客户第一次上线时只监控错误，结果半夜「队列中」堆积，第二天才发现。稳妥的做法是先把 status 设成 3,5，观察一周告警量再收敛。
2. 方案 ID 漏配。ids 字段如果不填或填错，会查到大量无关策略的旧错误。客户现场常见做法是把所有要监控的方案 ID 维护成一个常量，新增策略时同步追加。
3. webhook 被风控。飞书自定义机器人对单个 webhook 有频率限制，告警风暴时容易被限流。稳妥的做法是给同一类告警加去重，5 分钟内同一方案同一 number 只发一条。
4. 时间占位符忘加 \|datetime。{{response_at}} 原样输出是 ISO 时间戳，加 \|datetime 才会转成 YYYY-MM-DD HH:mm:ss。
5. 多租户混告警。如果平台是多租户共用，lessee_name 一定要带上，否则不同客户的错误会被推到同一个群里，排查时串线。

适用场景与不适用场景

适用：多策略并行、需要 7×24 监控、值班同学在飞书协作、希望「异常即消息」的中小型集成链路。不适用：日均错误量极大（万级以上）的场景，这种应该走专业的日志告警平台；也不适用对消息延迟容忍度极高的离线批处理链路，那条线人工巡检更划算。