# MQTTX 1.11.0 发布：Topic Tree 与 Avro Schema

> 本次发布引入了 Topic Tree 可视化功能，提供了一种按层级组织和监控 MQTT 主题的强大新方式。

> Language: zh-CN · Published: 2024-10-29 · Category: 版本发布 · Version: 1.11.0 · Canonical: https://mqttx.app/zh/blog/mqttx-1-11-0-release-notes · Translation: [English](https://mqttx.app/blog/mqttx-1-11-0-release-notes.md)

我们非常高兴地宣布，MQTTX 1.11.0 现已发布！

本次发布引入了 Topic Tree 可视化功能，提供了一种按层级组织和监控 [MQTT 主题](https://www.emqx.com/zh/blog/advanced-features-of-mqtt-topics)的强大新方式。同时，我们在 Desktop 和 CLI 客户端中增加了对 Avro Schema 和 Message Pack 格式的支持，进一步扩展了 MQTTX 的数据格式处理能力。这些更新为用户提供了更强大的工具，帮助理解 [MQTT](https://www.emqx.com/zh/blog/the-easiest-guide-to-getting-started-with-mqtt) 消息流并管理复杂的数据结构。

> **_在此下载最新版本：_** [**_https://mqttx.app/zh/downloads_**](https://mqttx.app/zh/downloads)

## Topic Tree

从 v1.11.0 开始，MQTTX Desktop 引入了 **Viewer** 功能，提供 MQTT 数据可视化能力，帮助用户更好地理解和监控消息流。

**Topic Tree** 目前处于 `Beta` 版本，是一款强大的可视化工具，可将 MQTT 主题和消息转换为直观的层级结构。它以树状形式展示 MQTT 主题关系和消息流，使 MQTT 数据更易于理解和管理。

**Topic Tree** 位于 **Viewer** 菜单中，会随着已订阅主题收到消息而自动更新。界面提供搜索框用于快速筛选主题、用于操作树的按钮，以及展示具体消息数据的详细信息面板。

Topic Tree 将节点分为三个层级：

- 根节点显示客户端连接详情，包括客户端 ID 和主机信息。
- 中间节点表示主题层级及其子主题。
- 叶子节点包含消息详情，包括接收时间、Retain 标志和 QoS 值。

![MQTT Topic Tree](https://assets.emqx.com/images/c6712e791d2df6025b60a1059d110986.png?x-image-process=image/resize,w_1520/format,webp)

用户可以切换到可视化树状图模式，获得不同的查看视角。该模式以更图形化的方式呈现主题结构，提供可调整的展开层级（默认为 4 层）和交互功能。用户可以将鼠标悬停在节点上，查看主题路径、消息数量、子主题数量和消息内容。

![Topic Tree 可视化](https://assets.emqx.com/images/21f0b0ce3a37e7686c3f72f745cde078.png?x-image-process=image/resize,w_1520/format,webp)

> 注意：Topic Tree 功能目前处于 Beta 阶段，可能存在功能不完整的情况。我们欢迎您的反馈和建议。如果您遇到任何问题或有改进想法，请访问 [https://github.com/emqx/MQTTX/issues](https://github.com/emqx/MQTTX/issues) 分享您的想法。

## Avro Schema 支持

> 该功能来自社区用户 [**@LAST7**](https://github.com/LAST7) 的贡献

MQTTX 1.11.0 引入了 Avro Schema 支持，进一步扩展了消息格式测试能力。这一增强使开发者能够充分测试使用 Avro 进行数据序列化的 MQTT 应用，确保消息在通信流程中正确编码和解码。

在将消息发布到生产环境之前，您现在可以验证 JSON 数据是否正确转换为 Avro 格式，并确认订阅端能够成功将 Avro 消息解码回 JSON。这一测试能力有助于在开发周期早期发现潜在的序列化问题，节省时间并减少生产环境中的调试工作。

### Desktop

Desktop 客户端在 `Script` → `Schema` 页面中提供了直观的 Avro Schema 测试界面。您可以在此：

- 使用标准 `.avsc` 格式定义 Avro Schema。
- 在发布前测试 JSON 到 Avro 的编码。
- 验证已订阅消息的 Avro 到 JSON 解码。
- 在测试面板中即时查看转换结果。

示例 Schema：

```json
{
  "type": "record",
  "name": "Person",
  "fields": [
    { "name": "id", "type": "int" },
    { "name": "name", "type": "string" }
  ]
}
```

![`Script` → `Schema` 页面](https://assets.emqx.com/images/aef3b5b57c6b2b509814289767d6928b.png?x-image-process=image/resize,w_1520/format,webp)

### CLI

对于自动化测试场景或命令行操作，MQTTX CLI 通过 `-Ap` 或 `--avsc-path` 选项集成 Avro 支持：

| -Ap, --avsc-path <PATH> | 定义 AVRO 编码所用 Avro Schema 的 .avsc 文件路径 |
| ----------------------------- | ------------------------------------------------ |

```
# Publish: Test your JSON to Avro encoding
mqttx pub -t 'msg/avro' -m '{"id": 1, "name": "hello"}' -Ap ./Person.avsc

# Subscribe: Verify Avro to JSON decoding
mqttx sub -t 'msg/avro' -Ap ./Person.avsc
```

这一功能增强了 MQTTX 测试结构化数据通信的能力，非常适合 IoT 设备开发和数据管道构建，确保 MQTT 应用中的 Avro Schema 消息得到准确处理。

## Message Pack 格式支持

> 该功能来自社区用户 [**@lantica**](https://github.com/lantica) 的贡献

MQTTX 1.11.0 现已支持 Message Pack，这是一种高效的二进制序列化格式。这一新增能力使您能够处理需要更高效数据传输、同时保留结构化数据格式的 MQTT 应用。通过在 JSON、Base64 和 CBOR 之外支持 Message Pack，MQTTX 处理多样化 MQTT 消息场景的能力进一步增强。

### Desktop

Desktop 客户端已在发布和订阅界面中完整集成 Message Pack 格式：

- 发布：以 Message Pack 格式发送 MQTT 消息，自动将 JSON 数据转换为紧凑的二进制格式。
- 订阅：接收 Message Pack 格式的 MQTT 消息，并以可读的 JSON 形式展示，简化消息查看和理解。

![Message Pack](https://assets.emqx.com/images/e876bab4b35b1c0a9c1448801000ea07.png?x-image-process=image/resize,w_1520/format,webp)

### CLI

CLI 通过 `-f` 或 `--format` 选项支持 Message Pack 格式：

```shell
# Send messages in Message Pack format
mqttx pub -t 'msg/msgpack' -m '{"value": 123}' -f msgpack

# Receive Message Pack formatted messages
mqttx sub -t 'msg/msgpack' -f msgpack
```

这一增强提升了 MQTTX 作为测试工具的通用性，尤其适用于消息大小效率至关重要的 IoT 场景。无论您是在测试已经使用 Message Pack 的系统，还是为 MQTT 通信探索更高效的消息格式，MQTTX 现在都具备处理这种紧凑二进制格式的能力。

## CLI 支持自定义 WebSocket Headers

MQTTX 1.11.0 为 CLI 客户端引入了自定义 WebSocket Headers 支持，这是社区强烈要求的功能。该增强允许用户在建立 WebSocket 连接时添加自定义 Header，特别适用于需要特殊认证或自定义数据传输的场景。

使用 `-wh` 或 `--ws-header` 选项指定自定义 WebSocket Header：

```shell
mqttx sub -t test -wh "Authorization: Bearer token123" -wh "Custom-Header: value" -l ws -p 8083
```

> 注意：该功能仅在 Node.js 环境中运行的 CLI 客户端中可用。由于浏览器的安全限制，Desktop 和 Web 版本无法修改 WebSocket Headers，这是浏览器 WebSocket 实现中的已知限制。

该功能满足了 WebSocket MQTT 连接中的常见需求，尤其适用于以下场景：

- 添加认证 Token
- 包含自定义标识 Header
- 设置特殊的连接参数

这一新增能力使 MQTTX CLI 成为测试 [MQTT over WebSocket](https://www.emqx.com/zh/blog/connect-to-mqtt-broker-with-websocket) 连接更灵活的工具，特别是在需要自定义 Header 实现安全或路由的企业环境中。

## 可配置的 QoS 0 消息存储

MQTTX 1.11.0 引入了忽略 QoS 0 消息的选项，可优化大量消息流场景下的性能。QoS 0 消息是最基本的消息投递形式，不保证送达，现在可以配置为仅显示而不在本地存储。

在设置页面的高级区域中，您会看到「忽略 QoS 0 消息」选项，默认关闭。启用后：

- QoS 0 消息会正常显示，但不会存储在本地。
- 在高频消息场景中减少存储开销。
- 之前已保存的 QoS 0 消息保持不变。

该功能在测试会产生大量 QoS 0 消息的 MQTT 应用时特别有用。它让您可以专注于需要投递保证的消息，同时保持最佳性能并减少存储空间占用。

![忽略 QoS 0 消息](https://assets.emqx.com/images/9a65db1c7939f1049c1f104bbd26f745.png?x-image-process=image/resize,w_1520/format,webp)

## 其他改进

### 客户端配置增强

- **支持空客户端 ID**：在 [MQTT 5.0](https://www.emqx.com/zh/blog/introduction-to-mqtt-5) 中引入对空客户端 ID 的支持，允许服务器自动分配客户端 ID。这一增强可以更准确地模拟 MQTT 5.0 场景。
- **默认会话过期时间**：对于 clean start 设置为 false 的 MQTT 5.0 连接，将会话过期时间的默认值调整为 7200 秒（2 小时）。这一变更与 EMQX 的默认配置保持一致，并优化了服务器端资源管理。

### MQTT 操作改进

- **通配符主题匹配**：修复了使用 `#` 的通配符主题匹配错误匹配非预期主题的问题（例如 `foo/#` 匹配到 `foobar/#`）。
- **版本表示**：将 CLI 中的 MQTT 版本表示从 `5` 更新为 `5.0`，提升清晰度和一致性。

### AI Copilot 增强

- **默认模型更新**：将默认模型切换为 GPT-4o，带来更好的性能和能力。
- **新增模型支持**：扩展支持更多 GPT 模型，例如 GPT-4o-mini 和 o1-preview。
- **集成 DeepSeek**：为中国用户引入 DeepSeek 模型支持，提供高性价比的语言模型选择。

### 常规修复

- 修复了连接名称样式问题。
- 改进了 benchmark 订阅主题的日志输出。
- 修正了 Desktop 客户端中的一些拼写错误。

## 路线图

- **Topic Tree Milestone-2**：增强主题的组织和可视化。
- **消息图表可视化增强 - MQTTX Viewer**：

  - **Diff View**：轻松比较不同的消息或 Payload。
  - **Dashboard View**：提供可自定义的 MQTT 活动总览，获得个性化洞察。
  - **JSON View**：改进 JSON 格式数据的处理和展示。
  - **System Topic View**：用于查看系统相关 [MQTT 主题](https://www.emqx.com/zh/blog/advanced-features-of-mqtt-topics)的专用视图。

- **支持可配置的断开连接属性（MQTT 5.0）**：通过可自定义的断开连接设置增强连接管理。
- **IoT 场景数据模拟**：将该功能引入桌面客户端，简化 IoT 场景测试。
- **支持 [Sparkplug B](https://www.emqx.com/en/solutions/mqtt-sparkplug)**：扩展 MQTTX 功能以支持 Sparkplug B。
- **MQTT GUI 调试功能**：新增用于调试 MQTT 通信的功能。
- **插件功能**：引入插件系统，支持 [CoAP](https://www.emqx.com/zh/blog/coap-protocol) 和 [MQTT-SN](https://www.emqx.com/zh/blog/connecting-mqtt-sn-devices-using-emqx) 等协议扩展。
- **JSON Schema**：提供 JSON Schema 的编码和解码能力。
- **脚本测试自动化（Flow）**：简化自动化测试工作流的创建和管理。