Go / 系统课时
用 io.Writer 实现编码器
用 io.Writer 实现编码器
编码器的目标不是“把字段写出去”这么简单,而是让同一条消息始终得到确定的字节布局,并把短写、写入错误完整传回调用方。本节用固定帧头和 io.Writer 抽象实现一个可直接复用的 Go 编码器。
学习目标
- 设计包含魔数、消息类型、长度和负载的稳定字节格式。
- 用 io.Writer 解耦编码逻辑与 TCP、文件、缓冲区等具体输出目标。
- 正确处理部分写入、零字节写入和底层写入错误。
先固定字节格式
示例协议把一帧定义为 7 字节帧头加负载:前 2 字节是 ASCII 魔数 GO,第 3 字节是消息类型,后 4 字节使用大端序记录负载长度,随后紧跟原始负载。长度固定后,接收端可以先读满帧头,再按长度读取负载,不需要猜测消息边界。
稳定格式还意味着编码器不能依赖 Go 结构体的内存布局,也不要直接把整数按本机字节序写出。这里显式选择 binary.BigEndian,这样不同机器和不同实现得到的字节流一致。
让编码器只依赖 io.Writer
Encoder 只持有 io.Writer。因此同一套编码逻辑既能写入 net.Conn,也能写入 bytes.Buffer、文件或带统计功能的包装 Writer。真正需要谨慎的是 Write 的返回值:已经成功写入的前 n 字节不能重复发送,剩余部分必须从 p[n:] 继续。
package main
import (
"bytes"
"encoding/binary"
"fmt"
"io"
)
type Message struct {
Type byte
Payload []byte
}
type Encoder struct {
w io.Writer
}
func NewEncoder(w io.Writer) *Encoder {
return &Encoder{w: w}
}
func (e *Encoder) Encode(m Message) error {
if uint64(len(m.Payload)) > uint64(^uint32(0)) {
return fmt.Errorf("payload too large: %d", len(m.Payload))
}
// 帧头布局固定为 magic(2) + type(1) + payloadLength(4)。
header := make([]byte, 7)
copy(header[:2], []byte("GO"))
header[2] = m.Type
binary.BigEndian.PutUint32(header[3:], uint32(len(m.Payload)))
if err := writeAll(e.w, header); err != nil {
return fmt.Errorf("write header: %w", err)
}
if err := writeAll(e.w, m.Payload); err != nil {
return fmt.Errorf("write payload: %w", err)
}
return nil
}
func writeAll(w io.Writer, p []byte) error {
for len(p) > 0 {
n, err := w.Write(p)
if n < 0 || n > len(p) {
return fmt.Errorf("invalid write count: %d", n)
}
// 无论本次是否写满,都只从尚未写出的部分继续。
p = p[n:]
if err != nil {
return err
}
if n == 0 {
return io.ErrShortWrite
}
}
return nil
}
type chunkWriter struct {
dst io.Writer
size int
}
func (w chunkWriter) Write(p []byte) (int, error) {
// 测试桩故意制造“短写且无错误”,验证编码器不会丢失尾部数据。
if len(p) > w.size {
p = p[:w.size]
}
return w.dst.Write(p)
}
func main() {
var buf bytes.Buffer
enc := NewEncoder(chunkWriter{dst: &buf, size: 3})
if err := enc.Encode(Message{Type: 1, Payload: []byte("hello")}); err != nil {
panic(err)
}
fmt.Printf("%x\n", buf.Bytes())
}预期输出
474f010000000568656c6c6f输出可拆成 47 4f、01、00000005 和 68656c6c6f,分别对应魔数、类型、长度 5 与字符串 hello。这个十六进制结果可以作为协议回归测试的黄金样本,后续重构编码器时只要字节序列发生变化,就应先确认是不是协议兼容性被破坏。
部分写入的边界
按照 io.Writer 约定,若 n < len(p),实现通常应同时返回非空错误;示例中的 chunkWriter 是为了验证防御逻辑而故意构造的测试桩,不应作为生产 Writer 的实现范式。编码器对 n > 0 的部分成果先推进切片,再处理错误,避免重复写已经成功发送的字节。
如果底层返回 n == 0 且 err == nil,继续循环会造成死循环,因此直接返回 io.ErrShortWrite。如果写入过程中出现真实错误,则立即返回并附带“写帧头”或“写负载”的上下文;调用方据此决定关闭连接或重建会话,而不是让编码器擅自重试整个消息。
什么时候可以复用这个编码器
只要协议仍是“固定帧头 + 定长字段 + 原始负载”,这个 Encoder 就可以直接复用于 TCP、TLS、文件录制或测试缓冲区。若协议需要校验和、压缩或可选字段,应先明确这些内容在字节流中的顺序,再扩展帧格式;不要把 io.Writer 抽象和协议布局混在一起修改,否则很难判断问题出在传输层还是编码规则。