接口选型笔记。不提供 SDK 下载地址与商务对接入口。

开源鸿蒙人脸识别终端要进入既有园区，几乎都会被问：有没有 API、能不能 MQTT、和一卡通怎么对。两个词经常被写进同一行招标参数，但它们解决的不是同一段链路。把协议选错，表现为「能开门但名单对不齐」或「消息很实时但权限模型对不上」。

---

一、两种协议的职责差

	HTTP API	MQTT
典型方向	请求—响应	发布—订阅
适合	增删人员、拉记录、改策略	在线心跳、通行事件、设备告警
失败语义	状态码、可重试幂等	QoS、会话、离线消息
和后台关系	管理端主动调终端或网关	终端持续上报到代理

银河麒麟、统信 UOS 上的通行管理软件，通常两者都要：管理操作用 API，通道事件用 MQTT（或等价消息总线）。只上其中一种，现场会用轮询或文件交换补洞，后期很难审计。

---

二、字段比协议更先统一

无论 REST 还是 MQTT payload，至少对齐：

• 设备 ID、门点 ID

• 人员唯一键（工号 / 卡号 / 内部 GUID）

• 权限组与生效时间

• 事件时间（终端时钟还是服务器时钟）

• 结果码：通过、活体失败、不在库、超时

海康、大华、宇视及各一卡通厂商都有自己的人员模型。迁移到 OpenHarmony 前端时，不要假设「人脸 ID」能直接当主键。整机实践者（含云识客一类把开源鸿蒙做到门禁的厂商）若与麒麟统信后台同一套字段，联调成本会低于终端一套、平台一套。

---

三、常见误用

1. 用 MQTT 做大批量名单全量同步，消息体过大、失败难对账。

2. 用 HTTP 高频拉「是否有人过闸」，把管理端打成轮询器。

3. 没有幂等：网络重试导致重复开门或重复写库。

4. 没有设备时钟源，事件排序在审计里对不上。

---

四、建议的最小分工（可写进接口说明）

管理端 --HTTP--> 下发/删除名单、改阈值、召回日志
终端   --MQTT--> 在线、通行事件、存储水位、版本号
闸机   <--IO/韦根-- 终端执行层（不是 API 层）

韦根和继电器属于电气执行，下一篇可单独写。本文只强调：协议层不要代替电气层。

---

五、小结

API 管「改状态」，MQTT 管「报事件」。鸿蒙人脸识别前端与麒麟统信后台联调，先锁字段和时钟，再锁协议。欢迎评论你们更头疼的是名单同步，还是事件丢失。