用 HTTP 接口把中控系统接进业务平台

接口设计定好幂等、超时、错误区分与安全边界，后续接入只是加一个接口

为什么用 HTTP 打通业务系统

中控系统内部用串口和 TCP 控制设备，但对外对接排程系统、预约平台、运维监控时，HTTP 接口几乎是默认选择。原因是它跨语言、跨平台、有成熟的调试工具，对方系统的开发人员不需要了解你的设备协议，只要按约定发一个请求就能触发控制。

三类典型交互

• 下发指令：业务系统调用接口，要求执行某个动作，比如"把 3 号会议室切到视频会议模式"。

• 查询状态：业务系统或运维平台定时拉取设备状态、在线情况、当前模式。

• 事件回调：现场发生异常（设备离线、指令执行失败、面板被操作）时，中控系统主动通知业务平台。

三者里最容易忽略的是第三类。只做下发不做回调，业务系统就永远是"盲发"状态，出了问题只能靠人去现场看。

接口设计上的几个要点

• 幂等：同一条指令重复请求不应造成重复动作，或者要能安全地重复执行。做法是让调用方带上请求标识，服务端对短时间内的相同标识直接返回上次结果。

• 超时约定：中控动作可能需要几秒才完成（比如升降设备走完全程），接口不能一直挂着。合理做法是立即返回"已受理"，再用回调或状态查询告知最终结果。

• 状态码要能区分责任：参数错误、设备离线、执行失败、系统内部异常，应返回可区分的错误信息，而不是统一返回一个失败。

• 版本：接口地址里带上版本号，后续扩展字段时不会影响既有调用方。

认证与安全

中控接口能动真实的物理设备，权限控制不能省。基本做法是接口密钥加在请求头里，配合来源 IP 限制；对外网开放的场合必须走 HTTPS，并限制可调用的动作范围——比如只允许查询状态，不允许执行升降、断电这类不可逆动作。

断网了怎么办

业务系统和中控之间的网络不是永远通畅的，尤其是跨网段、跨楼层部署时。下发指令应有明确失败返回，不能静默丢弃；事件回调要带重试机制和本地补发队列，网络恢复后把积压的事件按顺序补发。中控侧还应保留最近一段时间的操作记录，方便事后核对到底是谁触发了什么。

小结

HTTP 接口是把中控系统从"现场设备"变成"可被编排的服务"的关键一步。设计时把幂等、超时、错误区分、安全边界这四件事定下来，后续接入新系统就只是加一个接口的事。