📚 课程目录第4章项目整体架构

4、项目整体架构：前端可视化面板、后端服务、MQTT Broker、设备模拟器的职责与交互流程

核心原理：四层解耦的物联网数据链路

在动手编写任何代码之前，必须先理解本项目的整体架构。MQTT物联网可视化面板并非一个单体应用，而是由四个独立进程/模块协作构成的分布式系统。它们各自承担明确职责，通过标准化的消息协议完成数据流转。这种设计直接继承了物联网系统中最核心的“发布-订阅”思想：数据生产者不关心谁在消费数据，数据消费者也不关心数据来自哪里，双方只通过一个中间代理（Broker）进行异步通信。

四个核心模块的职责划分如下：

设备模拟器（Device Simulator）：数据源头。它模拟真实传感器（如温湿度计、电表），定期采集数据并通过MQTT协议发布到Broker的指定主题（Topic）。它只负责“发”，不关心数据去向。
MQTT Broker（消息代理）：数据中枢。它接收所有发布的消息，并根据主题匹配规则将消息路由给所有订阅了该主题的客户端。它本身不存储业务数据（除非开启retain或持久化），只做实时转发。
后端服务（Backend Service）：业务逻辑核心。它一方面作为MQTT客户端订阅设备原始数据主题，将数据解析后存入数据库（如MySQL或时序数据库）；另一方面提供RESTful API供前端调用，同时通过WebSocket主动推送数据变更给前端。
前端可视化面板（Frontend Dashboard）：用户交互层。它通过HTTP从后端获取历史数据，通过WebSocket接收实时数据推送，将数据渲染为图表、仪表盘或地图。它不直接与MQTT Broker通信，避免将Broker的端口和凭证暴露给浏览器。

架构要点：前端不直连MQTT Broker是本项目最重要的安全设计。如果浏览器直接通过WebSocket连接MQTT（如MQTT over WebSocket），则必须将Broker的账号密码或证书下发到浏览器端，这极易导致凭证泄露。引入后端作为“代理网关”，可以统一处理鉴权、数据清洗、协议转换（MQTT转WebSocket/REST），使系统更安全、更易维护。

方法流程：一条消息从传感器到屏幕的完整旅程

为了更直观地理解交互流程，我们以“温度传感器上报数据”为例，梳理一条消息从产生到展示的完整时序路径。该流程涉及四个模块间的三次关键握手。

设备模拟器                MQTT Broker                后端服务                前端面板
    |                          |                        |                       |
    |--1.发布消息-------------->|                        |                       |
    |   topic: device/001/temp |                        |                       |
    |   payload: {"v": 26.5}   |                        |                       |
    |                          |--2.转发消息（匹配订阅）-->|                       |
    |                          |                        |--3.解析JSON并存储---->|
    |                          |                        |   (MySQL/Redis)       |
    |                          |                        |                       |
    |                          |                        |--4.广播WebSocket------>|
    |                          |                        |   event: data_update  |
    |                          |                        |   payload: {temp:26.5}|
    |                          |                        |                       |--5.渲染图表/仪表

上述流程可拆解为五个关键步骤：

发布（Publish）：设备模拟器每2秒向Broker的device/001/temp主题发布一条QoS 0或QoS 1的消息。消息体为JSON格式，包含设备ID、数值、时间戳等字段。
路由（Route）：Broker根据主题通配符（如device/+/temp）找到所有匹配的订阅者，将消息副本推送给后端服务。此过程延迟通常在毫秒级。
持久化（Persist）：后端服务收到消息后，先校验JSON格式，再提取温度值、设备ID、时间戳，写入数据库。若数据异常（如温度超过80℃），则触发告警逻辑。
推送（Push）：后端服务通过WebSocket连接向所有在线的前端面板广播一条data_update事件，事件负载中包含最新的温度值及设备ID。
渲染（Render）：前端面板收到WebSocket消息后，更新内存中的数据结构，并调用图表库（如ECharts）的setOption方法动态更新折线图或仪表盘指针。

案例/场景：设备离线与数据补传的架构应对

理解了理想流程后，我们再看一个真实场景：设备模拟器因网络抖动离线30秒，恢复后需要补传离线期间的数据。这一场景最能体现四层架构中“职责分离”的价值。

在传统HTTP轮询架构中，设备离线会导致数据丢失，因为服务器无法主动感知设备状态。而在本MQTT架构中，处理方式如下：

离线检测：Broker通过心跳机制（Keep Alive）发现设备连接断开，会向后端服务订阅的$SYS/broker/connection/device_001/state主题发送一条offline消息。后端服务收到后，将设备状态标记为“离线”，并通过WebSocket通知前端更新设备列表中的状态指示灯。
数据缓存：设备模拟器自身维护一个本地环形缓冲区（容量100条）。当它检测到MQTT连接断开时，不再尝试发送，而是将带时间戳的数据写入缓冲区。
重连补传：设备模拟器每5秒尝试重连Broker。一旦重连成功，它首先发布一条device/001/status消息（payload: {"online": true}），然后按时间顺序将缓冲区中的历史数据逐条发布到device/001/temp主题。由于每条消息都携带原始时间戳，后端服务在存储时不会覆盖或错序。
前端一致性：后端服务在收到补传数据时，会额外触发一次history_sync事件。前端面板收到该事件后，主动调用REST APIGET /api/devices/001/history?start=xxx&end=yyy拉取完整历史数据并全量刷新图表，避免因逐条推送导致图表闪烁或数据空洞。

  架构复盘：此场景中，Broker负责连接状态感知，设备模拟器负责数据缓存策略，后端服务负责状态持久化与事件转发，前端负责按需拉取。四个模块各司其职，没有出现“某个模块越权处理其他模块事务”的情况。如果采用单体架构，设备离线逻辑、数据缓存、状态推送、前端刷新全部耦合在一个进程内，代码复杂度将呈指数级上升。

误区/复盘：初学者最容易犯的四个架构错误

在指导学员完成本项目时，以下四个架构设计误区出现频率最高，需要特别警惕：

误区编号	错误做法	后果	正确方案
1	前端直接通过WebSocket连接MQTT Broker（如使用mqtt.js连接ws://broker:8083/mqtt）	Broker的账号密码暴露在浏览器控制台中；浏览器跨域限制导致连接不稳定；无法在Broker与前端之间增加数据清洗逻辑	前端只连接后端提供的WebSocket接口（如ws://api.local/ws），由后端统一订阅MQTT主题并转发
2	后端服务同时订阅所有设备主题，但未使用通配符，而是为每台设备单独写一个回调函数	设备数量增多时代码冗余严重；新增设备类型需要修改后端代码并重启服务	使用主题通配符（如`device/+/temp`）加单一消息处理入口，通过解析Topic字段动态分发到不同处理逻辑
3	设备模拟器发送数据时未指定QoS级别，且未处理Broker的ACK确认	网络抖动时消息静默丢失，前端图表出现断点且无法追溯	对关键数据（如告警）使用QoS 1，并设置合理的重发间隔；对普通遥测数据使用QoS 0以降低网络开销
4	前端收到WebSocket推送后立即调用REST API查询数据库，导致数据库压力过大	高频推送（如每100ms一条）时数据库连接池被耗尽，页面卡死	前端维护一个内存数据窗口（如最近5分钟数据），WebSocket推送只更新内存，仅当用户点击“刷新历史”时才调用REST API

复盘以上误区，可以发现它们的共同根源是没有严格遵循分层职责边界。MQTT架构的优势在于通过Broker解耦了生产者和消费者，但如果在应用层又错误地将前端与Broker直连、或将后端与设备逻辑耦合，就相当于把解耦后的系统重新“焊死”在一起。正确的做法是始终让消息流单向流动：设备→Broker→后端→前端，任何反向控制（如前端下发指令给设备）也应通过后端API中转，由后端作为MQTT客户端发布控制消息到设备主题。

上图完整展示了四个模块之间的连接关系与数据流向。注意前端面板与MQTT Broker之间没有直接连线，这正是本项目架构安全性的直观体现。所有通信路径均以Broker为中枢，后端服务作为唯一的“协议转换器”和“安全网关”，确保浏览器端永远无法触达内部消息网络。