在基于TCP的自定义协议里，消息边界需要靠应用层自己维护，最常见的做法就是“长度前缀 + 消息体”。Ruby从3.1开始引入了IO::Buffer这个底层缓冲区抽象，其中write_with_length方法可以直接把数据连同长度前缀一起写入缓冲区，省去了手工拼接的麻烦。但不少人在第一次使用时会疑惑：这个4字节的长度前缀到底是大端还是小端？对方用Go或者Java写的服务端能不能正确解析？这篇文章就来把这个问题讲透，并给出不同字节序需求下的完整实现方案。
write_with_length的字节序行为剖析
先看方法本身。write_with_length属于IO::Buffer的实例方法，调用形式是buffer.write_with_length(data)，它的作用是在当前读写位置写入一个32位整数表示数据长度，紧接着写入数据本身，然后返回写入的总字节数（前缀4字节 + 数据长度）。可以这样验证：
require 'io/buffer'
buf = IO::Buffer.new(64)
buf.write_with_length("hello")
puts buf.inspect
# 输出中可以看到前4字节为 05 00 00 00从输出可以直观看到，前4个字节是05 00 00 00，也就是低字节在前——这是典型的小端序（little-endian），也就是本机字节序在x86平台上的表现。事实上，write_with_length内部写入长度前缀时并没有强制做字节序转换，它按本机字节序直接写入。这意味着在不同架构的机器上，同一个方法产生的字节序列可能不同。x86、ARM等主流平台都是小端，所以日常开发中你几乎总会看到小端结果，但如果你在PowerPC之类的大端机器上运行，输出就会变成00 00 00 05。
这一点非常关键：如果你的协议对端是大端解析（大多数网络协议标准采用大端，也叫网络字节序），直接用write_with_length的输出就会解析出错。反过来，如果通信双方约定小端，并且都在小端机器上运行，那这个方法非常方便。简单说，write_with_length是一个“便利方法”而不是“协议方法”，它没有替你做字节序规范化，规范化的责任在开发者自己。
配合set_value手动控制字节序
当协议要求大端长度前缀，或者要求非4字节（比如2字节或8字节）的长度字段时，就需要放弃write_with_length，改用底层的set_value方法手动写入。set_value的签名是set_value(类型, 偏移, 值)，类型可以是:U8、:U16、:U32、:U64等，还可以加上:big或:little后缀来显式指定字节序，例如:U32_big。显式指定后缀是最推荐的做法，因为它与本机架构完全解耦。
下面是一个标准的“大端4字节长度前缀 + 消息体”的实现：
def pack_frame_big_endian(payload, buf)
# 确保缓冲区足够容纳 4 字节前缀 + 数据
needed = 4 + payload.bytesize
buf.resize(needed) if buf.size < needed
# 显式指定大端序写入 U32 长度
buf.set_value(:U32_big, 0, payload.bytesize)
# 紧跟着写入消息体
buf.set_string(payload, 4, payload.bytesize)
needed
end
buf = IO::Buffer.new(64)
len = pack_frame_big_endian("hello", buf)
puts buf.get_value(:U32_big, 0) # => 5
puts buf.get_string(4, 5) # => "hello"这个写法有几个细节值得注意。第一，set_value和set_string都是按绝对偏移写入，不会改变缓冲区的内部读写位置（pos），这一点和write_with_length不同——后者是顺序写入，会推进pos。第二，set_string的第三个参数是长度，如果你传入的数据比缓冲区剩余空间大，会抛出IO::Buffer::AccessError，所以写入前最好做容量检查或调用resize。第三，类型符号写成:U32_big是显式大端，:U32_little是显式小端，而不带后缀的:U32则使用本机字节序，跨平台代码应尽量避免不带后缀的写法。
如果协议用的是小端序，只需把:U32_big换成:U32_little即可。同理，2字节长度字段用:U16_big，8字节用:U64_big，灵活性远高于write_with_length固定的4字节本端格式。
读取端的对偶处理与完整通信示例
写入端搞清楚了，读取端也要对偶地处理。读取用get_value(类型, 偏移)取长度前缀，再用get_string(偏移, 长度)取消息体。假设我们要从socket收到的字节流中解析帧，可以先读4字节判断长度是否完整到达：
def parse_frame(buf) # 至少要有 4 字节才能读出长度前缀 raise IncompleteError if buf.size < 4 length = buf.get_value(:U32_big, 0) raise IncompleteError if buf.size < 4 + length payload = buf.get_string(4, length) [payload, 4 + length] # 返回消息体和已消费的字节数 end
这里强烈建议读取端的字节序类型与写入端严格一致，都用:U32_big或都用:U32_little。一个常见的线上事故就是写入端用了本机序（不带后缀），而服务端部署在大端机器上用同样的符号解析，结果长度读出一个天文数字，直接导致缓冲区分配失败或连接被踢。字节序一旦在协议文档里约定，两端代码里都应该用带后缀的类型符号把它“钉死”，不要依赖运行环境。
另外补充一点与write_with_length配套的顺序读写知识：IO::Buffer的顺序读写方法如write、read、write_with_length、read_with_length都维护一个内部位置指针，而set_value、get_value、set_string、get_string是随机访问，不触碰指针。两种风格不要混用，否则位置状态会变得难以推理。如果只是想在内存里快速拼一个帧然后一次性send出去，随机访问方式配合each_byte或to_s是最可控的；如果是在流式解析场景中，顺序读写的read_with_length配合小端约定则更简洁。理解了这一层，字节序和长度字段的处理在你手里就再也不会出错了。
Ruby IO::Bufferwrite_with_length字节序修改时间：2026-09-12 06:34:33