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:] 继续。

go
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())
}

预期输出

text
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 抽象和协议布局混在一起修改,否则很难判断问题出在传输层还是编码规则。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 io.Writer 实现编码器

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通