aiot-platform-cloud/viewsh-module-iot/viewsh-module-iot-gateway/src/test/resources/tcp-binary-packet-examples.md

# TCP 二进制协议数据包格式说明

## 1. 协议概述

TCP 二进制协议是一种高效的自定义协议格式，采用紧凑的二进制格式传输数据，适用于对带宽和性能要求较高的 IoT 场景。

### 1.1 协议特点

- **高效传输**：完全二进制格式，减少数据传输量
- **版本控制**：内置协议版本号，支持协议升级
- **类型安全**：明确的消息类型标识
- **简洁设计**：去除冗余字段，协议更加精简
- **兼容性**：与现有 `IotDeviceMessage` 接口完全兼容

## 2. 协议格式

### 2.1 整体结构

```
+--------+--------+--------+---------------------------+--------+--------+
| 魔术字 | 版本号 | 消息类型|         消息长度(4字节)          |
+--------+--------+--------+---------------------------+--------+--------+
|           消息 ID 长度(2字节)        |      消息 ID (变长字符串)         |
+--------+--------+--------+--------+--------+--------+--------+--------+
|           方法名长度(2字节)        |      方法名(变长字符串)         |
+--------+--------+--------+--------+--------+--------+--------+--------+
|                        消息体数据(变长)                              |
+--------+--------+--------+--------+--------+--------+--------+--------+
```

### 2.2 字段详细说明

| 字段 | 长度 | 类型 | 说明 |
|------|------|------|------|
| 魔术字 | 1字节 | byte | `0x7E` - 协议识别标识，用于数据同步 |
| 版本号 | 1字节 | byte | `0x01` - 协议版本号，支持版本控制 |
| 消息类型 | 1字节 | byte | `0x01`=请求, `0x02`=响应 |
| 消息长度 | 4字节 | int | 整个消息的总长度（包含头部） |
| 消息 ID 长度 | 2字节 | short | 消息 ID 字符串的字节长度 |
| 消息 ID | 变长 | string | 消息唯一标识符（UTF-8编码） |
| 方法名长度 | 2字节 | short | 方法名字符串的字节长度 |
| 方法名 | 变长 | string | 消息方法名（UTF-8编码） |
| 消息体 | 变长 | binary | 根据消息类型的不同数据格式 |

**⚠️ 重要说明**：deviceId 不包含在协议中，由服务器根据连接上下文自动设置

### 2.3 协议常量定义

```java
// 协议标识
private static final byte MAGIC_NUMBER = (byte) 0x7E;
private static final byte PROTOCOL_VERSION = (byte) 0x01;

// 消息类型
private static final byte REQUEST = (byte) 0x01;   // 请求消息
private static final byte RESPONSE = (byte) 0x02;  // 响应消息

// 协议长度
private static final int HEADER_FIXED_LENGTH = 7;      // 固定头部长度
private static final int MIN_MESSAGE_LENGTH = 11;      // 最小消息长度
```

## 3. 消息类型和格式

### 3.1 请求消息 (REQUEST - 0x01)

请求消息用于设备向服务器发送数据或请求。

#### 3.1.1 消息体格式
```
消息体 = params 数据(JSON格式)
```

#### 3.1.2 示例：设备认证请求

**消息内容：**
- 消息 ID: `auth_1704067200000_123`
- 方法名: `auth`
- 参数: `{"clientId":"device_001","username":"productKey_deviceName","password":"device_password"}`

**二进制数据包结构：**
```
7E                              // 魔术字 (0x7E)
01                              // 版本号 (0x01)
01                              // 消息类型 (REQUEST)
00 00 00 89                     // 消息长度 (137字节)
00 19                           // 消息 ID 长度 (25字节)
61 75 74 68 5F 31 37 30 34 30   // 消息 ID: "auth_1704067200000_123"
36 37 32 30 30 30 30 30 5F 31 
32 33
00 04                           // 方法名长度 (4字节)
61 75 74 68                     // 方法名: "auth"
7B 22 63 6C 69 65 6E 74 49 64   // JSON参数数据
22 3A 22 64 65 76 69 63 65 5F   // {"clientId":"device_001",
30 30 31 22 2C 22 75 73 65 72   //  "username":"productKey_deviceName",
6E 61 6D 65 22 3A 22 70 72 6F   //  "password":"device_password"}
64 75 63 74 4B 65 79 5F 64 65
76 69 63 65 4E 61 6D 65 22 2C
22 70 61 73 73 77 6F 72 64 22
3A 22 64 65 76 69 63 65 5F 70
61 73 73 77 6F 72 64 22 7D
```

#### 3.1.3 示例：属性数据上报

**消息内容：**
- 消息 ID: `property_1704067200000_456`
- 方法名: `thing.property.post`
- 参数: `{"temperature":25.5,"humidity":60.2,"pressure":1013.25}`

### 3.2 响应消息 (RESPONSE - 0x02)

响应消息用于服务器向设备回复请求结果。

#### 3.2.1 消息体格式
```
消息体 = 响应码(4字节) + 响应消息长度(2字节) + 响应消息(UTF-8) + 响应数据(JSON)
```

#### 3.2.2 字段说明

| 字段 | 长度 | 类型 | 说明 |
|------|------|------|------|
| 响应码 | 4字节 | int | HTTP状态码风格，0=成功，其他=错误 |
| 响应消息长度 | 2字节 | short | 响应消息字符串的字节长度 |
| 响应消息 | 变长 | string | 响应提示信息（UTF-8编码） |
| 响应数据 | 变长 | binary | JSON格式的响应数据（可选） |

#### 3.2.3 示例：认证成功响应

**消息内容：**
- 消息 ID: `auth_response_1704067200000_123`
- 方法名: `auth`
- 响应码: `0`
- 响应消息: `认证成功`
- 响应数据: `{"success":true,"message":"认证成功"}`

**二进制数据包结构：**
```
7E                              // 魔术字 (0x7E)
01                              // 版本号 (0x01)
02                              // 消息类型 (RESPONSE)
00 00 00 A4                     // 消息长度 (164字节)
00 22                           // 消息 ID 长度 (34字节)
61 75 74 68 5F 72 65 73 70 6F   // 消息 ID: "auth_response_1704067200000_123"
6E 73 65 5F 31 37 30 34 30 36
37 32 30 30 30 30 30 5F 31 32
33
00 04                           // 方法名长度 (4字节)
61 75 74 68                     // 方法名: "auth"
00 00 00 00                     // 响应码 (0 = 成功)
00 0C                           // 响应消息长度 (12字节)
E8 AE A4 E8 AF 81 E6 88 90 E5   // 响应消息: "认证成功" (UTF-8)
8A 9F
7B 22 73 75 63 63 65 73 73 22   // JSON响应数据
3A 74 72 75 65 2C 22 6D 65 73   // {"success":true,"message":"认证成功"}
73 61 67 65 22 3A 22 E8 AE A4
E8 AF 81 E6 88 90 E5 8A 9F 22
7D
```

## 4. 编解码器标识

```java
public static final String TYPE = "TCP_BINARY";
```

## 5. 协议优势

- **数据紧凑**：二进制格式，相比 JSON 减少 30-50% 的数据量
- **解析高效**：直接二进制操作，减少字符串转换开销
- **类型安全**：明确的消息类型和字段定义
- **设计简洁**：去除冗余字段，协议更加精简高效
- **版本控制**：内置版本号支持协议升级

## 6. 与 JSON 协议对比

| 特性   | 二进制协议       | JSON协议 |
|------|-------------|--------|
| 数据大小 | 小（节省30-50%） | 大      |
| 解析性能 | 高           | 中等     |
| 网络开销 | 低           | 高      |
| 可读性  | 差           | 优秀     |
| 调试难度 | 高           | 低      |
| 扩展性  | 良好          | 优秀     |

**推荐场景**：
- ✅ **高频数据传输**：传感器数据实时上报
- ✅ **带宽受限环境**：移动网络、卫星通信
- ✅ **性能要求高**：需要低延迟、高吞吐的场景
- ✅ **设备资源有限**：嵌入式设备、低功耗设备
- ❌ **开发调试阶段**：调试困难，建议使用 JSON 协议
- ❌ **快速原型开发**：开发效率低