7.3 数据类型与序列化：词库的字节级写法

7.3 数据类型与序列化规范

本节摘要：词库的写法层——数据类型编号体系、小端字节序、属性级序列化（类型编号加定长或带长度前缀的载荷），以及标度元数据如何把整数还原成物理量。本节用一条真实报文的逐字节解读收束第七章，也补齐"抓包能看懂"的最后一块拼图。

一、类型编号：每个值都自报家门

词库给每种数据类型一个八位编号，属性与命令参数必须声明类型。核心几类要认得：无符号八位整数、带符号八位、无符号十六位、带符号十六位、三十二位两档、布尔（八位，零为假非零为真，注意没有一位布尔）、枚举八位、字符串（带一字节长度前缀）、八位与十六位标度数（整数值配两个标度属性还原物理量）、时间戳、网络密钥这样的定长集合类型。类型自描述是属性发现能工作的前提——工具读到"属性编号加类型编号加值"的三元组，不需要外部文档就能解析任意属性，这是声明式互操作在字节层的地基。

字节序采用小端（低字节在前），与多数底层硬件一致以省换算。定长类型直接按宽度排布；字符串与集合类型带长度前缀。没有对齐与填充——序列化是紧凑流，为省每一个字节。

温度值属性的序列化（带符号十六位 · 标度数）：

值 225 = 0x00E1，小端序列化为  E1 00
配合簇属性：标度 = -1（10 的负一次方），精度 = 2（两位有效数字）
还原：225 × 10 的 -1 次方 = 22.5 摄氏度

一条"读温度应答"的簇载荷（概念字节流）：
  命令: 读属性应答(0x01) | 属性编号: 0x0000(温度值) | 状态: 0x00(成功)
  类型: 0x29(带符号16位标度数) | 值: E1 00
十六进制全景：01 00 00 00 29 E1 00
​

二、标度机制：整数的量纲还原

上一节的例子暴露了词库最重要的工程妥协：不用浮点。低功耗微控制器的浮点运算又慢又费电，词库干脆把所有物理量压成整数，配两个元数据属性还原——标度属性（十的幂次）与精度属性（有效位数）。温度的百分之零点一度、功率的瓦、色温的兆分之一开尔文，都是这个机制的实例。做集成时先读标度属性再乘幂次，硬编码倍数是跨型号翻车的经典姿势（不同厂商标度可以不同）。

⚠️ 常见坑：把带符号类型当无符号解析。冬季温度序列化后最高位是一（补码负数），按无符号解析会显示几万度——"传感器冬天发疯"多半是解析端的符号位丢了。

三、帧结构：簇命令的完整封装

一条簇命令帧的载荷区（应用层之上）结构为：帧控制（命令类别、厂商特定标志、方向、禁止缺省应答标志）加顺序号加命令编号加命令载荷。方向位标明这是客户端发往服务端还是反向（应答类帧要置反）；顺序号用于配对命令与应答，也支撑可选的缺省应答（出错时回一条带状态码的应答而不是业务应答）。厂商特定标志打开后，命令编号落入厂商自定义区段——第四章私有簇边界的字节层开关。

开关簇"关"命令的载荷封装（概念）：

帧控制   : 0x01（簇特定命令 · 客户端到服务端 · 允许缺省应答）
顺序号   : 0x2A（配对应答用）
命令编号 : 0x00（关）
载荷     : 空
十六进制全景：01 2A 00
加上外层：网络层头 + 应用支撑子层头(端点1→端点1 · 簇0x0006 · 规范标识) + 本载荷
​

图：一条簇命令帧的纵向解剖

四、写法层的演化

早期各分支对序列化细节（字符串编码、标度取值）留过自由度，跨厂商联调时才暴露——同样的温度属性，一家标度负一一家负二，读代码不做标度适配就翻车。统一版的词库收口包括：类型编号目录冻结、标度元数据强制实现、发现属性必须如实报告类型。这些字节级的小约束不起眼，却是"开箱即互操作"的最后一公里。抓包排障的完整技能链在本节闭合：链路帧到属性值的每一层都能对上号，协议栈对你再无黑盒。

本节要点回顾

• 类型自描述：属性三元组（编号、类型编号、值）让工具零文档解析任意设备；
• 小端紧凑流：低字节在前，无对齐无填充，字符串带长度前缀，能省的字节都省；
• 标度机制：整数加十的幂次与精度元数据规避浮点，集成必须动态读标度而非硬编码；
• 符号位与顺序号：带符号类型按无符号解析是冬季怪值首因，顺序号配对应答；
• 帧纵向解剖：链路头、网络头、应用支撑子层头、簇载荷逐层剥开，抓包不再黑盒；
• 本节坐标：词库三部曲完结，第八章看统一版如何把全栈打包成顺滑的开箱体验。

延伸：序列化与抓包的闭环

本节与第十章的抓包工具构成闭环：分析仪解码到簇载荷层后，剩余的字节流就要靠本节的规则人工还原——帧控制拆位、顺序号配对、按类型编号读值、标度换算。练一个例子胜过读十遍规则：抓一条温度上报帧，手工解析载荷并还原成摄氏度，全流程走通一次，序列化知识就真正落地了。这也是认证预测试中"报文正确性"类失败项的自查手段。

常见问题

字符串属性的长度前缀是几字节？

一字节，因此属性内字符串最长二百五十五字符。需要更长内容（如描述文本）时拆多属性或走厂商特定机制——这是紧凑设计里"够用就好"的又一例。

速查：类型编号记忆

• 布尔：八位 · 零假非零真；
• 无符号八位与带符号八位：温度差值类小量的常用档；
• 带符号十六位标度数：温度值的经典类型；
• 无符号十六位：湿度与功率常用；
• 字符串：一字节长度前缀 · 最长二百五十五；
• 字节序一律小端 · 紧凑无填充。

补数据序列化的字节序陷阱。ZCL 的多字节数据是小端序（低字节在前）——与网络编程惯用的大端序相反，这是跨平台开发的高频错误来源：温度 23.5 度编码为 1853（0x073D），小端序列化为 3D 07，习惯大端的工程师写反就会在抓包里看到诡异的数值。同类陷阱还有布尔与位图的混用（bitmap 类型的每一位是独立开关，不能当整数读写）、枚举值的越界（枚举类型的合法值域是协议定义的，写了未定义值对端可能丢弃整个消息）。序列化层的测试建议：写一组边界值的编码单元测试（0、-1、最大值、最小值），对照协议文本的编码示例逐一验证——ZCL 的数据类型章是协议文本里最"工程"的一章，每个类型都给了精确的字节布局，照抄不会有错，自作聪明才会错。序列化层的正确性是一切上层互操作的物理前提——字节序都错了，再正确的协议逻辑也无法互相理解。