> For the complete documentation index, see [llms.txt](https://mcxiaoke.gitbook.io/mqtt/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mcxiaoke.gitbook.io/mqtt/01-introduction.md).

# 第一章 - MQTT介绍

## 1.1 MQTT协议的组织结构 Organization of MQTT

本规范分为七个章节：

* [第一章 – 介绍](/mqtt/01-introduction.md)
* [第二章 – MQTT控制报文格式](/mqtt/02-controlpacketformat.md)
* [第三章 – MQTT控制报文](/mqtt/03-controlpackets.md)
* [第四章 – 操作行为](/mqtt/04-operationalbehavior.md)
* [第五章 – 安全](/mqtt/05-security.md)
* [第六章 – 使用WebSocket](/mqtt/06-websocket.md)
* [第七章 – 一致性目标](/mqtt/07-conformance.md)
* [附录B – 强制性规范声明](/mqtt/08-appendixb.md)

## 1.2 术语 Terminology

本规范中用到的关键字 **必须** MUST，**不能** MUST NOT，**要求** REQUIRED，**将会** SHALL，**不会** SHALL NOT，**应该** SHOULD，**不应该** SHOULD NOT，**推荐** RECOMMENDED，**可以** MAY，**可选** OPTIONAL 都是按照 IETF RFC 2119 [\[RFC2119\]](/mqtt/01-introduction.md#anchor-RFC2119) 中的描述解释。

**网络连接 Network Connection**

MQTT使用的底层传输协议基础设施。

* 客户端使用它连接服务端。
* 它提供有序的、可靠的、双向字节流传输。

例子见4.2节。

**应用消息 Application Message** MQTT协议通过网络传输应用数据。应用消息通过MQTT传输时，它们有关联的服务质量（QoS）和主题（Topic）。

**客户端 Client**\
使用MQTT的程序或设备。客户端总是通过网络连接到服务端。它可以

* 发布应用消息给其它相关的客户端。
* 订阅以请求接受相关的应用消息。
* 取消订阅以移除接受应用消息的请求。
* 从服务端断开连接。

**服务端 Server**\
一个程序或设备，作为发送消息的客户端和请求订阅的客户端之间的中介。服务端

* 接受来自客户端的网络连接。
* 接受客户端发布的应用消息。
* 处理客户端的订阅和取消订阅请求。
* 转发应用消息给符合条件的已订阅客户端。

**订阅 Subscription**\
订阅包含一个主题过滤器（Topic Filter）和一个最大的服务质量（QoS）等级。订阅与单个会话（Session）关联。会话可以包含多于一个的订阅。会话的每个订阅都有一个不同的主题过滤器。

**主题名 Topic Name**\
附加在应用消息上的一个标签，服务端已知且与订阅匹配。服务端发送应用消息的一个副本给每一个匹配的客户端订阅。

**主题过滤器 Topic Filter**\
订阅中包含的一个表达式，用于表示相关的一个或多个主题。主题过滤器可以使用通配符。

**会话 Session**\
客户端和服务端之间的状态交互。一些会话持续时长与网络连接一样，另一些可以在客户端和服务端的多个连续网络连接间扩展。

**控制报文 MQTT Control Packet**\
通过网络连接发送的信息数据包。MQTT规范定义了十四种不同类型的控制报文，其中一个（PUBLISH报文）用于传输应用消息。

## 1.5 数据表示 Data representations

### 1.5.1 二进制位 Bits

字节中的位从0到7。第7位是最高有效位，第0位是最低有效位。

### 1.5.2 整数数值 Integer data values

整数数值是16位，使用大端序（big-endian，高位字节在低位字节前面）。这意味着一个16位的字在网络上表示为最高有效字节（MSB），后面跟着最低有效字节（LSB）。

### 1.5.3 UTF-8编码字符串 UTF-8 encoded strings

后面会描述的控制报文中的文本字段编码为UTF-8格式的字符串。UTF-8 \[[RFC3629](/mqtt/01-introduction.md#RFC3629)] 是一个高效的Unicode字符编码格式，为了支持基于文本的通信，它对ASCII字符的编码做了优化。

每一个字符串都有一个两字节的长度字段作为前缀，它给出这个字符串UTF-8编码的字节数，它们在[图例 1.1 UTF-8编码字符串的结构](https://mcxiaoke.gitbook.io/mqtt/pages/-LvE6CZAL71Wbg46dKY6#_Figure_1.1_Structure) 中描述。因此可以传送的UTF-8编码的字符串大小有一个限制，不能超过 65535字节。

除非另有说明，所有的UTF-8编码字符串的长度都必须在0到65535字节这个范围内。

**图例 1.1 UTF-8编码字符串的结构 Structure of UTF-8 encoded strings**

| **二进制位**  | 7-0                      |
| --------- | ------------------------ |
| byte 1    | 字符串长度的最高有效字节（MSB）        |
| byte 2    | 字符串长度的最低有效字节（LSB）        |
| byte 3 …. | 如果长度大于0，这里是UTF-8编码的字符数据。 |

UTF-8编码字符串中的字符数据**必须**是按照Unicode规范 \[[Unicode](/mqtt/01-introduction.md#Unicode)] 定义的和在RFC3629 \[[RFC3629](/mqtt/01-introduction.md#RFC3629)] 中重申的有效的UTF-8格式。特别需要指出的是，这些数据**不能**包含字符码在U+D800和U+DFFF之间的数据。如果服务端或客户端收到了一个包含无效UTF-8字符的控制报文，它**必须**关闭网络连接 \[MQTT-1.5.3-1]。

UTF-8编码的字符串**不能**包含空字符U+0000。如果客户端或服务端收到了一个包含U+0000的控制报文，它**必须**关闭网络连接 \[MQTT-1.5.3-2]。

数据中**不应该**包含下面这些Unicode代码点的编码。如果一个接收者（服务端或客户端）收到了包含下列任意字符的控制报文，它**可以**关闭网络连接：

* U+0001和U+001F之间的控制字符
* U+007F和U+009F之间的控制字符
* Unicode规范定义的非字符代码点（例如U+0FFFF）
* Unicode规范定义的保留字符（例如U+0FFFF）

UTF-8编码序列0XEF 0xBB 0xBF总是被解释为U+FEFF（零宽度非换行空白字符），无论它出现在字符串的什么位置，报文接收者都不能跳过或者剥离它 \[MQTT-1.5.3-3]。

#### 非规范示例 Non normative example

> 例如，字符串 A𪛔 是一个拉丁字母A后面跟着一个代码点U+2A6D4(它表示一个中日韩统一表意文字扩展B中的字符)，这个字符串编码如下：

**图例 1.2 UTF-8编码字符串非规范示例 UTF-8 encoded string non normative example**

| **Bit** | **7**            | **6** | **5** | **4** | **3** | **2** | **1** | **0** |
| ------- | ---------------- | ----- | ----- | ----- | ----- | ----- | ----- | ----- |
| byte 1  | 字符串长度 MSB (0x00) |       |       |       |       |       |       |       |
|         | 0                | 0     | 0     | 0     | 0     | 0     | 0     | 0     |
| byte 2  | 字符串长度 LSB (0x05) |       |       |       |       |       |       |       |
|         | 0                | 0     | 0     | 0     | 0     | 1     | 0     | 1     |
| byte 3  | ‘A’ (0x41)       |       |       |       |       |       |       |       |
|         | 0                | 1     | 0     | 0     | 0     | 0     | 0     | 1     |
| byte 4  | (0xF0)           |       |       |       |       |       |       |       |
|         | 1                | 1     | 1     | 1     | 0     | 0     | 0     | 0     |
| byte 5  | (0xAA)           |       |       |       |       |       |       |       |
|         | 1                | 0     | 1     | 0     | 1     | 0     | 1     | 0     |
| byte 6  | (0x9B)           |       |       |       |       |       |       |       |
|         | 1                | 0     | 0     | 1     | 1     | 0     | 1     | 1     |
| byte 7  | (0x94)           |       |       |       |       |       |       |       |
|         | 1                | 0     | 0     | 1     | 0     | 1     | 0     | 0     |

### 1.6 编辑约定 Editing conventions

本规范用黄色高亮的文本标识一致性声明，每个一致性声明都分配了一个这种格式的引用：\[MQTT-x.x.x-y]。

### 项目主页

* [MQTT协议中文版](https://github.com/mcxiaoke/mqtt)