飞书卡片消息构建实战：从文本到可交互富卡片-开发者社区

这是「飞书对接」小专题的第2篇，共5篇，从《MCP实战手记（十一）：MCP接飞书，从机器人到事件订阅的三层深度接入》延伸（对应正文第2层自建应用卡片消息）。

第1层群机器人只能POST一段文本，店长看到的是一行字。但零售场景里，店长要的是"一张能看的卡"：销售数字、库存水位、补货按钮。文本到富卡片，是飞书对接从"能通知"到"能用"的跨越。卡片怎么搭、按钮回调怎么接、以及生产最容易翻车的出站频控，一次性讲清。

卡片1.0还是2.0？

飞书卡片有两套协议，字段结构不同：

卡片1.0：顶层config+header+elements，文本用text.tag = lark_md。兼容最广，本文实测跑通用这套。
卡片2.0：schema: "2.0"+body.elements，文本用text.tag = markdown。新项目可用，迁移时注意字段差异。

本篇示例用1.0，先把链路跑通最重要。

一张门店数据卡怎么搭

把@Tool查回来的结果渲染成 interactive card，店长一眼看到重点，还能直接点按钮：

{"config":{"wide_screen_mode":true},"header":{"title":{"tag":"plain_text","content":"门店助手·查询成功"},"template":"green"},"elements":[{"tag":"div","text":{"tag":"lark_md","content":"**指令**：查库存ST001\n\nSKU-1001库存23（安全线50）"}},{"tag":"action","actions":[{"tag":"button","text":{"tag":"plain_text","content":"补货"},"value":{"sku":"SKU-1001"}}]}]}

wide_screen_mode宽屏更适配桌面飞书；template: green是卡片头配色；action里的button带value，点下去会把sku回传回去。

按钮回调怎么接

店长点"补货"，飞书会发一个卡片回调事件（action 触发），服务端要处理它。两层都要配：

应用后台登记"卡片回调"地址（和事件订阅同一个长连接/回调通道）。
handler 里读action.value，按sku调补货工具，再回一张新卡。

// 卡片action回调（节选自 dispatch）if("补货".equals(action.getActionTag())){Stringsku=action.getValue().get("sku");// 取回按钮带的 skuRestockResultr=storeService.suggestRestock(storeCode,sku);apiClient.im().message().reply(buildCard("补货建议",r));// 回一张新卡}

关键点：按钮的value是状态通道，别在卡片里塞大段业务数据——只带最小标识（sku/storeCode），真查还在服务端做。

出站频控 + 退避重试（生产必加）

飞书消息发送不是无限发，有频控+失败重试语义。裸发容易踩RateLimitException。技术4.4要求生产加退避重试：

// 退避重试（飞书频控 + 瞬时失败）：指数退避 + 随机抖动intattempt=0;while(attempt<3){try{apiClient.im().message().send(req);break;}catch(RateLimitExceptione){longbase=(1L<<attempt)*500;// 0.5s / 1s / 2slongjitter=ThreadLocalRandom.current().nextLong(0,500);// 抖动，错开重试Thread.sleep(base+jitter);attempt++;}}