第 5 章 使用 Buffer 类处理二进制数据

直觉起点

、、、、共同构成本页的观察坐标。区分字符、编码后字节和缓冲区容量，用显式编码与端序完成字符串、数值、JSON 和复制边界。 Node.js 的关键不只是异步 API，而是谁创建资源、谁接收完成通知、错误沿哪条边传播、什么条件下进程可以安全退出。2014 年版接口与现代 Node 的差异会明确标注，不用新 API 冒充原书目录，也不把废弃接口直接推荐给新项目。

六阶段执行链

1. 声明编码

固定 Node 版本、启动参数、环境变量和输入，先预测同步调用栈、异步资源与最终输出。没有版本证据的示例无法区分书中历史行为与当前运行时。

2. 计算字节数

明确数据是字符串、字节、流、报文、请求、事件还是数据库记录，并标出所有者。创建资源的代码必须同时设计 error、timeout、abort 或 close 路径。

3. 分配缓冲区

只保留最小处理器和一个完成出口。回调、Promise 与事件不得为同一操作重复签发结果；监听器注册顺序和一次性语义要能从代码读出。

4. 读写字段

注入一个边界：空输入、长输入、半包、慢消费者、权限拒绝、数据库回滚或客户端断开。停止在首个偏离点，保存错误对象、资源状态与未完成数量。

5. 验证边界

检查旧接口在现代 Node 的状态：仍支持、语义变化、弃用或移出核心。现代替代必须保持原章节要解决的问题，同时说明迁移不能自动保证的兼容行为。

6. 释放引用

清除故障并重放同一输入，等待文件、套接字、连接池和子进程排空。退出码、最终响应和资源计数全部收敛，才算恢复而不是暂时停止报错。

核心机制深挖

区分字符、编码后字节和缓冲区容量，用显式编码与端序完成字符串、数值、JSON 和复制边界。 所有案例统一记录五类证据：输入表示、调度边界、资源所有者、错误出口、关闭条件。输入表示错误会造成编码、分帧或查询歧义；调度边界错误会把同步事件误认为异步回调；所有权不清会留下描述符和连接；错误出口重复会产生二次响应；关闭条件缺失会让进程一直存活或强行丢数据。

本页签发不变量是：字符长度与字节长度不混用，分配、读写偏移和端序都有边界证据，不使用不安全的旧 Buffer 构造方式。 代码必须能回答正常路径完成了什么、边界输入限制在哪里、失败由谁观察、取消怎样传播、关闭等待哪些资源，以及 2014 年 API 在当前版本中是否仍适合新代码。只展示成功日志或最终页面，不能证明这些条件。

版本兼容账本

原书出版于 2014 年，示例所处的 Node、npm、Express、Socket.IO 与数据库驱动生态都早于当前版本。重构保留原书问题与模块身份，但代码采用安全、可运行的现代形式，并为 domain、punycode、旧 Buffer 构造器和旧框架 API 标记历史状态。读者迁移旧项目时应先固定原版本复现，再逐层替换接口与测试，不能一次升级所有依赖后凭报错猜测语义变化。

兼容账本至少包含：原书接口、当时用途、当前支持状态、推荐替代、行为差异和删除旧兼容层的条件。核心原理例如 TCP 无消息边界、流需要背压、事务需要回滚不会因版本改变；具体函数签名、默认超时、模块入口和错误类型则可能变化。把稳定原理与易变 API 分开，才能既忠实复刻知识体系，又不误导今天的新代码。

出版社目录逐项讲解

第5章 使用Buffer类处理二进制数据

区分字符、编码后字节和缓冲区容量，用显式编码与端序完成字符串、数值、JSON 和复制边界。

实验从“声明编码”开始：固定 Node 版本、入口、输入与资源上限，先预测事件、字节或消息怎样流动，再只注入一个超时、断线、权限、背压或版本变化。记录首个偏离点，删除故障后重放同一输入，不能用额外监听器和重复重试掩盖根因。

5.1 创建Buffer对象

现代代码使用 Buffer.alloc 创建清零空间，Buffer.from 从已知数据构造；旧版不安全构造器可能暴露未初始化内存。分配长度来自不可信输入时必须设置上限。

实验从“计算字节数”开始：固定 Node 版本、入口、输入与资源上限，先预测事件、字节或消息怎样流动，再只注入一个超时、断线、权限、背压或版本变化。记录首个偏离点，删除故障后重放同一输入，不能用额外监听器和重复重试掩盖根因。

5.2 字符串的长度与缓存区的长度

JavaScript 字符串 length 计数 UTF-16 代码单元，Buffer.byteLength 按指定编码计算字节。中文、emoji 和组合字符会让三种长度不同，协议字段必须明确计量单位。

实验从“分配缓冲区”开始：固定 Node 版本、入口、输入与资源上限，先预测事件、字节或消息怎样流动，再只注入一个超时、断线、权限、背压或版本变化。记录首个偏离点，删除故障后重放同一输入，不能用额外监听器和重复重试掩盖根因。

5.3 Buffer对象与字符串对象之间的相互转换

Buffer.from(text, encoding) 负责编码，buffer.toString(encoding, start, end) 负责解码。分片边界若切在多字节字符中间会产生替换字符，流式文本应使用 StringDecoder。

实验从“读写字段”开始：固定 Node 版本、入口、输入与资源上限，先预测事件、字节或消息怎样流动，再只注入一个超时、断线、权限、背压或版本变化。记录首个偏离点，删除故障后重放同一输入，不能用额外监听器和重复重试掩盖根因。

5.4 Buffer对象与数值对象之间的相互转换

数值读写方法要求明确位宽、有无符号与大小端，并校验 offset。协议解析先验证帧长度再读字段，避免越界异常或把攻击者字节解释成巨大尺寸。

实验从“验证边界”开始：固定 Node 版本、入口、输入与资源上限，先预测事件、字节或消息怎样流动，再只注入一个超时、断线、权限、背压或版本变化。记录首个偏离点，删除故障后重放同一输入，不能用额外监听器和重复重试掩盖根因。

5.5 Buffer对象与JSON对象之间的相互转换

Buffer 的 JSON 表示通常包含 type 与 data 字节数组，不等于业务对象序列化。跨网络更常见的是先 JSON.stringify 再按 UTF-8 编码，并对长度与 schema 做验证。

实验从“释放引用”开始：固定 Node 版本、入口、输入与资源上限，先预测事件、字节或消息怎样流动，再只注入一个超时、断线、权限、背压或版本变化。记录首个偏离点，删除故障后重放同一输入，不能用额外监听器和重复重试掩盖根因。

5.6 复制缓存数据

copy 会复制字节，subarray 通常共享底层内存。选择取决于后续是否允许修改和源缓冲区生命周期；共享视图能省内存，也可能造成意外联动。

实验从“声明编码”开始：固定 Node 版本、入口、输入与资源上限，先预测事件、字节或消息怎样流动，再只注入一个超时、断线、权限、背压或版本变化。记录首个偏离点，删除故障后重放同一输入，不能用额外监听器和重复重试掩盖根因。

5.7 Buffer类的类方法

concat、compare、isBuffer、byteLength 等类方法处理集合与类型判断。拼接前先计算总长度上限，频繁小块 concat 会重复复制，应优先使用流或预分配。

实验从“计算字节数”开始：固定 Node 版本、入口、输入与资源上限，先预测事件、字节或消息怎样流动，再只注入一个超时、断线、权限、背压或版本变化。记录首个偏离点，删除故障后重放同一输入，不能用额外监听器和重复重试掩盖根因。

5.8 小结

本章小结不是 API 清单，而是复核“声明编码、计算字节数、分配缓冲区、读写字段、验证边界、释放引用”是否闭环：输入从哪里进入、资源由谁持有、错误怎样传播、何时释放，以及现代运行时是否改变了原书接口的支持状态。

实验从“分配缓冲区”开始：固定 Node 版本、入口、输入与资源上限，先预测事件、字节或消息怎样流动，再只注入一个超时、断线、权限、背压或版本变化。记录首个偏离点，删除故障后重放同一输入，不能用额外监听器和重复重试掩盖根因。

资源与失败矩阵

最小可运行实验

const payload = "节点";
const bytes = Buffer.from(payload, "utf8");
const frame = Buffer.alloc(4 + bytes.length);
frame.writeUInt32BE(bytes.length, 0);
bytes.copy(frame, 4);
console.log(frame.readUInt32BE(0), frame.subarray(4).toString("utf8"));

book: Node.js 权威指南
page: ndg-05-buffer-binary
edition: 2014
sample: normal | boundary | failure | recovery
resource_owner_known: true
single_completion: true
close_observed: true

freeze node version + entry + input
predict sync stack + async resources
change exactly one boundary condition
stop at first divergent state
remove fault and replay
wait for every resource to close

常见误区与故障注入

四类样本与验收

目录证据：第5章 使用Buffer类处理二进制数据、5.1 创建Buffer对象、5.2 字符串的长度与缓存区的长度、5.3 Buffer对象与字符串对象之间的相互转换、5.4 Buffer对象与数值对象之间的相互转换、5.5 Buffer对象与JSON对象之间的相互转换、5.6 复制缓存数据、5.7 Buffer类的类方法、5.8 小结。本页按公开目录独立重构，不复制原书正文；每个条目都进入输入、机制、故障、版本和关闭证据链。

练习

小结

• Buffer：对应“声明编码”的核心观察量。
• 字节长度：对应“计算字节数”的核心观察量。
• 编码：对应“分配缓冲区”的核心观察量。
• 端序：对应“读写字段”的核心观察量。
• 边界检查：对应“验证边界”的核心观察量。
• 9 个本页目录条目已全部映射到执行链与版本账本。
• 最终输出只是证据之一，资源关闭和错误传播同样决定是否通过。

术语表