进阶 · 10 分钟
HTTP 接口触发与幂等
MES 调一个接口就能出纸。难的不是「能调通」,是「调重了不会多打一张」——这是接口对接和接口对接到不出错的分界线。
两个必须理解的规则
必须带数据行
请求里要有 rows,一条数据一行。空请求不触发打印——这样「调通了但没数据」不会被误当成一次打印任务。
默认按请求 ID 判重
同一个请求 ID 在保留期内只处理一次。不按报文内容判重——因为产线上「同一张标连打两张」是合法业务,按内容去重会吞单。
第 1 步:建流程,加 HTTP 触发节点
给触发节点起个别名(如 line3-print),别名就是接口路径的一部分,改名等于换地址,联调后别乱改。
幂等配置两项:
- 判重字段:默认取请求 ID(如
request_id) - 保留时长:重复请求在多长时间内算重投,例如 86400 秒(一天)
如果对接方连请求 ID 都给不了,才改成「按报文指纹」判重——这是降级方案,要先确认业务上不存在合法的重复报文。
第 2 步:接加工与出纸
HTTP 触发(别名=line3-print,幂等=request_id,保留 86400s)
→ 条件过滤(material_no 非空 且 qty > 0)
→ 字段加工(机台={{machine}},班次={{shift}},日期={{#date}})
→ 条件分叉(qty >= 500 => 1 / * => 2)
→ 打印机(出口 1 → 3 号线;出口 2 → 本机)
→ 记录(runId + 来源)
第 3 步:发一次请求
curl -X POST "http://<本机IP>:<端口>/api/v1/flow/line3-print" \
-H "Content-Type: application/json" \
-d '{
"request_id": "MO-20261116-0001",
"rows": [
{"material_no":"A-1001","qty":12,"machine":"MJ-03","shift":"早班"}
]
}'
具体端口、鉴权头与字段名以软件内该节点的说明为准,不同版本可能略有差异。
第 4 步:重投验幂等
把同一条请求原样再发一次。正确的行为是:
- 返回 409,并且带上原来那次的 runId
- 一张纸都不多出
- 运行记录里只有一次执行
如果第二次又打了一批,说明幂等没开、或判重字段没对上(比如字段名写成了 requestId)。
联调顺序(少走弯路)
- 先本机用 curl 打通,确认出纸与字段都对
- 再跨机从 MES 服务器调,检查防火墙与端口
- 最后压重投故意连发三次同一个请求 ID,确认只打一次
- 留一份样例报文给客户 IT,写在交接文档里
常见问题
返回 404 / 找不到流程
三种可能:流程没发布(草稿不执行)、流程没启动、别名打错。发布与启动是两个动作,都要做。
返回成功但没出纸
看运行记录:如果节点在「条件过滤」处就结束了,说明数据行被过滤掉了(字段为空或不满足条件);如果卡在「刷新数据源」,说明查不到关联数据,这一路被停住。
重投时返回 200 不是 409
请求 ID 不相同(比如对方每次都生成新 ID),或者判重字段配的不是这个字段。跟对接方确认 ID 的生成规则——必须是业务幂等的 ID,不能是随机 UUID。
能不能直接调打印机端口 9100?
不能,那是打印机原始指令通道。接口触发要打到 LabelGo 的开放接口上,由软件负责模板、流水号、防重与记录。
并发调用会怎样?
同一时刻最多 2 批在处理,多余的排队(最多 20 批),队列满会丢批并写警告日志。上游要有节流,别一次推一百批。