本文基于 HarmonyOS 5（API 12+）讲解 MQTT 在鸿蒙应用中的完整使用流程，从协议原理、环境搭建、MQTT Broker 部署、HarmonyOS SDK 封装、连接管理、自动重连、消息订阅发布、SSL/TLS、安全认证、断线重连、心跳机制，到企业级最佳实践，适合零基础到进阶开发者阅读。

---

一、MQTT 简介

MQTT（Message Queuing Telemetry Transport）是一种基于 发布/订阅（Publish/Subscribe） 模型的轻量级消息传输协议。

它最大的特点：

• 协议简单
• 网络开销小
• 支持弱网
• 支持长连接
• 非常适合 IoT（物联网）

目前广泛应用于：

• HarmonyOS IoT
• 智能家居
• 智能门锁
• 智能手表
• 鸿蒙设备互联
• IM 即时聊天
• 实时消息推送
• 数据采集

---

二、MQTT 工作原理

MQTT 不同于 HTTP。

HTTP：

Client
   │
Request
   │
Server
   │
Response

MQTT：

         Broker
        /   |   \
       /    |    \
 Client1 Client2 Client3

所有客户端：

连接 Broker

Broker 负责：

• 转发消息
• 保存离线消息
• 权限控制
• Topic 管理

---

三、MQTT 基本概念

1、Broker

MQTT 服务器。

例如：

EMQX

Mosquitto

HiveMQ

阿里云 MQTT

华为云 IoTDA

---

2、Client

HarmonyOS App。

手机客户端。

---

3、Topic

类似：

chat/room1

device/light

device/temp

user/10001

所有消息都通过 Topic 转发。

例如：

发布：

chat/room1

Hello

所有订阅：

chat/room1

都会收到。

---

4、Publish

发布消息。

client.publish()

---

5、Subscribe

订阅消息。

client.subscribe()

---

四、MQTT QoS

MQTT 最经典就是 QoS。

QoS0

最多一次

发送一次

不保证收到

速度最快。

例如：

天气

日志

---

QoS1

至少一次

一定收到

可能重复

应用最多。

---

QoS2

只有一次

绝不会重复

四次握手。

速度最慢。

适合：

支付

订单

库存同步

---

五、HarmonyOS 为什么选择 MQTT

例如：

聊天室。

HTTP：

A

POST

Server

B

轮询

GET

Server

延迟高。

MQTT：

A

Publish

↓

Broker

↓

B

Subscribe

实时。

---

六、HarmonyOS 中 MQTT 实现方案

目前主要有两种：

方案一：

Java MQTT SDK（推荐）

例如：

Paho MQTT

HarmonyOS Next 可以通过兼容 Java 库（结合 ArkTS 工程配置）或使用适配版本。

方案二：

自己实现 MQTT 协议

工作量巨大。

一般不用。

---

七、准备 MQTT Broker

最简单：

Docker：

docker run -d \
--name emqx \
-p 1883:1883 \
-p 8083:8083 \
-p 18083:18083 \
emqx/emqx

后台：

http://IP:18083

默认：

admin

public

---

八、HarmonyOS 集成 MQTT SDK

项目中导入 MQTT SDK 后，创建一个统一管理类。

MQTTManager

职责：

连接

断开

订阅

发布

重连

监听

---

九、创建 MQTTManager

例如：

class MQTTManager {

    connect(){}

    disconnect(){}

    publish(){}

    subscribe(){}

}

统一管理。

不要每个页面都创建 Client。

---

十、建立连接

配置：

host

port

clientId

username

password

例如：

const option = {
    host:"tcp://192.168.1.10",
    port:1883,
    clientId:"HarmonyOS"
}

连接：

client.connect(option)

成功：

Connected

---

十一、监听连接状态

例如：

client.onConnect(()=>{

})

失败：

client.onFailure(()=>{

})

断开：

client.onClose(()=>{

})

建议统一监听。

---

十二、订阅 Topic

例如：

client.subscribe(
    "chat/room1",
    1
)

QoS：

1

---

十三、发布消息

例如：

client.publish(
    "chat/room1",
    "Hello HarmonyOS"
)

Broker：

收到。

所有订阅：

同步收到。

---

十四、监听消息

例如：

client.onMessage((topic,msg)=>{

})

打印：

console.info(topic)

console.info(msg)

---

十五、完整流程

connect

↓

subscribe

↓

publish

↓

receive

↓

disconnect

---

十六、封装发布方法

publish(topic:string,msg:string){

}

调用：

mqtt.publish(
    "chat",
    "hello"
)

页面无需关心 SDK。

---

十七、封装订阅

subscribe(topic:string){

}

支持：

多个 Topic

批量订阅

---

十八、支持自动重连

网络断开：

WiFi

↓

4G

↓

WiFi

需要：

Reconnect

例如：

autoReconnect=true

或者：

5 秒重连一次

---

十九、心跳机制（KeepAlive）

MQTT：

默认：

60 秒

发送：

PINGREQ

Broker：

PINGRESP

保持连接。

---

二十、遗嘱消息（Last Will）

客户端异常退出：

Broker：

自动发布：

offline

例如：

device/1001/status

消息：

offline

其他客户端立即知道设备离线。

---

二十一、保留消息（Retained Message）

例如：

publish(
status,
online,
retain=true
)

新的订阅者：

立即收到：

online

无需等待下一次发布。

---

二十二、Clean Session

true：

重新连接

重新订阅

false：

Broker 保存：

订阅

离线消息

推荐：

IM：

false

---

二十三、SSL/TLS

生产环境：

不要：

1883

建议：

8883

开启：

TLS

避免：

明文密码

---

二十四、用户名密码认证

例如：

username

password

Broker：

验证。

失败：

拒绝连接。

---

二十五、Token 认证

更推荐：

JWT

AccessToken

每次连接：

验证 Token。

---

二十六、Topic 权限

例如：

用户：

1001

只能：

user/1001/#

不能：

user/1002

Broker 控制。

---

二十七、通配符订阅

单层：

+

例如：

chat/+/msg

匹配：

chat/1/msg

---

多层：

#

例如：

chat/#

匹配：

chat/a

chat/a/b

chat/a/b/c

---

二十八、消息格式

建议：

JSON。

例如：

{
  "cmd":"login",
  "uid":1001,
  "time":1750000000
}

不要：

abc|123|xxx

后期维护困难。

---

二十九、HarmonyOS 页面监听

推荐：

MQTTManager

↓

EventBus

↓

UI

避免：

MQTT 与页面强耦合。

---

三十、断开连接

退出登录：

disconnect()

释放：

Socket

Listener

Timer

---

三十一、异常处理

建议处理：

• 网络断开
• Broker 不可达
• 用户认证失败
• Topic 无权限
• 消息格式错误
• 超时
• 重复连接

---

三十二、性能优化

避免：

100ms

Publish

建议：

批量发送。

例如：

20 条

一次发送

减少网络开销。

---

三十三、企业级 MQTTManager 设计

建议采用单例模式：

App
 │
MQTTManager（Singleton）
 │
 ├── Connect
 ├── Disconnect
 ├── Publish
 ├── Subscribe
 ├── Reconnect
 ├── Heartbeat
 ├── Listener
 ├── Cache
 └── EventBus

这样可以统一管理 MQTT 生命周期，避免重复连接和资源浪费。

---

三十四、典型应用场景

场景	是否推荐 MQTT
实时聊天	⭐⭐⭐⭐⭐
智能家居	⭐⭐⭐⭐⭐
设备控制	⭐⭐⭐⭐⭐
IoT 数据采集	⭐⭐⭐⭐⭐
实时报警	⭐⭐⭐⭐⭐
消息推送	⭐⭐⭐⭐☆
股票行情	⭐⭐⭐⭐☆
普通 REST 接口	⭐☆☆☆☆

---

三十五、最佳实践总结

在 HarmonyOS 5 中使用 MQTT，建议遵循以下原则：

1. 使用单例 MQTTManager 管理全局连接。
2. 启用自动重连，并结合指数退避策略避免频繁重连。
3. 根据业务选择合适的 QoS：日志用 QoS0、聊天用 QoS1、支付等关键业务用 QoS2。
4. 使用 JSON 作为统一消息格式，便于扩展和维护。
5. 开启 TLS（8883）并使用 Token/JWT 等方式进行身份认证，避免明文传输。
6. 合理设计 Topic 层级（如 app/{uid}/message、device/{id}/status），避免混乱。
7. 处理好断线、重连、离线消息、遗嘱消息、保留消息等场景，提升用户体验。
8. 将 MQTT 与 UI 解耦，通过事件总线或状态管理框架通知页面更新。
9. 在应用退出或用户登出时主动断开连接，释放资源。
10. 对连接、订阅、发布、异常日志进行统一封装，方便后续维护和排查问题。

---

总结

MQTT 是 HarmonyOS 5 开发中构建实时通信能力的重要技术，尤其适用于物联网、智能设备控制、即时通讯和消息推送等场景。通过合理封装 MQTTManager、设计 Topic 规范、启用 TLS 与自动重连机制，并结合 HarmonyOS 的状态管理和事件机制，可以构建出高性能、高可靠、易维护的实时通信系统。

对于企业级项目，推荐将 MQTT 作为统一的消息总线，与 REST API 配合使用：REST 负责业务请求，MQTT 负责实时消息同步，从而兼顾可靠性与实时性。