IO::Buffer是Ruby 3.1引入的底层二进制缓冲区抽象，它提供了零拷贝读写、内存映射等能力，特别适合用来处理自定义二进制协议。在TCP通信中，一种非常经典的帧格式是「长度前缀 + 消息体」，也就是在消息体前面用固定字节数（比如4字节）表示消息体长度。接收方先读长度，再按长度读取完整消息，从而解决TCP粘包拆包问题。但很多刚接触IO::Buffer的开发者会发现一个问题：write_with_length这个方法名看起来像是帮忙写入长度字段的，可实际上它并不负责字节序转换，直接用它写入的长度在跨机器通信时往往会出问题。这篇文章就来把这个概念彻底讲清楚。
write_with_length到底做了什么
首先需要澄清一个常见的误解：write_with_length并不是「把数据长度作为字段写入缓冲区」的方法。它的真实作用是把数据写入缓冲区，并在写入的数据前面额外追加一个表示这次写入了多少字节的长度值，形成一个「带长度的记录」。这个方法通常用于日志结构化存储、消息队列落盘这类自描述数据块的场景，而不是网络协议中的长度前缀帧。
来看一个基本用法示例：
require 'io/buffer'
buf = IO::Buffer.new(64)
# 写入一段数据，前面自动带上8字节的长度
written = buf.write_with_length("hello world", 8)
p written
# => [20, 8] # 总共写入了20字节（8字节长度 + 12字节数据），偏移量为8
p buf.get_string(8, 12)
# => "hello world"第二个参数指定长度字段占用几个字节，可以是1、2、4、8等。注意观察返回值是一个数组，包含写入的总长度和当前偏移位置。写入的长度值本身是按照主机字节序（小端序，在x86机器上）存放的，方法内部不会帮你做任何网络字节序转换。这意味着，如果你的对端是Java程序并且用DataInputStream的readInt读取，收到的长度值就会是反的，这就是很多「长度字段看起来是乱码」问题的根源。
换句话说，write_with_length适合的场景是「自己写、自己读」，读写双方都在同一个进程或同一类机器上。一旦涉及跨平台网络传输，你就必须自己控制长度字段的字节序。
大端序与小端序：为什么协议偏爱大端序
字节序指的是多字节数据在内存中的存放顺序。小端序（Little Endian，IO::Buffer中的符号是:LE）把低位字节放在低地址，大端序（Big Endian，符号:BE）把高位字节放在低地址。举个例子，数值0x00000099，小端序在内存中的字节序列是99 00 00 00，大端序则是00 00 00 99。
网络协议几乎统一采用大端序，也就是所谓的「网络字节序」。TCP/IP协议头中的端口号、IP地址、长度字段全部是大端序。历史原因是早期ARPANET的设备体系差异，最终形成了这个约定俗成的标准。所以在设计自定义协议时，除非通信双方都明确约定了小端序，否则长度字段默认应该用大端序写入。
IO::Buffer提供了get_value和set_value两个方法用于按指定字节序读写标量值，它们都接受一个类型符号和一个端序符号作为参数：
require 'io/buffer' buf = IO::Buffer.new(16) # set_value(偏移, 类型, 值, 端序) buf.set_value(:U32, 4096, :BE) # 按大端序写入 p buf.get_value(:U32, 0, :BE) # => 4096 # 对比小端序，同样的字节读出来值完全不同 p buf.get_value(:U32, 0, :LE) # => 1638400 左右的值（具体取决于字节排列）
类型符号的含义是：:U16表示无符号16位整数占2字节，:U32占4字节，:U64占8字节，还有:S32表示有符号32位整数。第三个参数端序可以是:BIG或:LITTLE（也接受:NETWORK作为大端序别名，取决于Ruby版本，建议直接用:BIG或:BE形式，具体以所用版本的文档为准）。
实现带字节序转换的长度前缀写入
理解了上面的原理，正确的做法就清晰了：先用set_value按大端序把长度写入缓冲区头部，再用write把消息体写到后面。下面封装一个通用的写帧函数：
require 'io/buffer' # 将字符串以「4字节大端序长度 + 消息体」的格式写入buffer # 返回写入的总字节数 def write_frame(buf, offset, payload) length = payload.bytesize # 先写入4字节大端序长度字段 buf.set_value(:U32, length, :BE) # 偏移由set_value自动推进，接着写入消息体 _, written = buf.write(payload) 4 + written end # 使用示例 buf = IO::Buffer.new(1024) total = write_frame(buf, 0, "你好，协议世界") p total # => 4 + 19 = 23（UTF-8中文字符一般占3字节） # 验证：读取长度字段 p buf.get_value(:U32, 0, :BE) # => 19
注意Ruby 3.1早期版本的set_value签名是set_value(type, offset, value, endianness)，从Ruby 3.3开始改为偏移量可选并调整了参数顺序，上面代码采用新签名写法。如果你的项目需要兼容多个Ruby版本，最稳妥的方案是完全不依赖set_value，改用Array#pack生成字节串：
require 'io/buffer'
def write_frame_pack(buf, payload)
# N 表示32位无符号、网络字节序（大端）
length_bytes = [payload.bytesize].pack('N')
buf.write(length_bytes)
buf.write(payload)
end
# 读取端对应的解包方式
def read_frame(data)
length = data[0, 4].unpack1('N')
payload = data[4, length]
[length, payload]
endpack模板字符N专门表示32位网络字节序无符号整数，n表示16位版本，它们天生就是大端序，语义清晰且跨版本稳定，是处理协议字段字节序最常用的手段。
接收端如何按字节序解析长度字段
写帧解决了，读帧同样要遵循相同的字节序约定。如果直接在IO::Buffer上解析，可以按固定步长循环读取：先取4字节长度，验证其合法性（防止恶意或损坏数据导致超大分配），再取出对应长度的消息体。
require 'io/buffer'
def read_frames_from_buffer(buf)
frames = []
offset = 0
size = buf.size
while offset + 4 <= size
length = buf.get_value(:U32, offset, :BE)
break if length == 0 || length > 1_048_576 # 限制单帧最大1MB
break if offset + 4 + length > size # 数据不完整，等待更多数据
frames << buf.get_string(offset + 4, length)
offset += 4 + length
end
frames
end这里有两点工程实践值得强调。第一，一定要对读出的长度做上限校验，否则一个被污染的长度值就可能让你的进程试图分配几个GB的内存。第二，当offset + 4 + length > size时不要报错，而是保留剩余数据等待下一次读取拼接，这正是处理TCP半包的标准姿势：把IO::Buffer当作累积缓冲区，每收到一段数据就追加进来，再尝试解析出所有完整的帧。
最后做一个方案小结：如果数据只在Ruby进程内部或同构机器间流转，write_with_length用起来最省事；一旦走网络跨平台通信，长度字段必须自己控制字节序，首选pack的N/n模板字符，其次是用IO::Buffer的set_value配合:BE端序符号。把这两种手段封装成统一的frame编解码模块，你的二进制协议代码会清晰且可靠得多。
Ruby IO::Bufferwrite_with_length字节序转换修改时间：2026-08-31 19:01:12