Go 基础体系 · 第 27/113 篇。示例统一基于 Go 1.26.4；核心片段可能省略 package 与 import，完整程序可直接按文中结构运行。

Go I/O 抽象：io.Reader、Writer、Copy 与流式处理

本文所有代码与运行行为均以 Go 1.26.4 为基准。Go 的 I/O 体系并不按“文件、网络、压缩、内存”分别设计一套搬运 API，而是把共同动作压缩为两个小接口：io.Reader 产生字节，io.Writer 消费字节。算法一旦只依赖这两个能力，就能在文件、HTTP body、标准输入、内存缓冲、压缩流和哈希器之间复用。

这篇文章聚焦字节流的契约、组合、缓冲、限流、错误和资源所有权。真实文件的权限、原子替换与路径安全属于《Go 文件与文件系统》；HTTP 超时和连接复用属于 HTTP 主题；JSON 字段语义属于 JSON 主题。底层载体不同，但本篇建立的读写规则完全相同。

1. 两个小接口建立能力边界

io.Reader 和 io.Writer 都只有一个方法：

type Reader interface {
	Read(p []byte) (n int, err error)
}

type Writer interface {
	Write(p []byte) (n int, err error)
}

Read 最多写入 len(p) 个字节并返回实际数量；Write 尝试消费 p。接口表达的是能力，不表达数据来自哪里，也不承诺缓冲、并发安全、可重试、可定位或可关闭。函数若只需要读取，就接收 io.Reader，不要接收功能更大的 *os.File；若同时需要关闭，可明确接收 io.ReadCloser，但这也意味着所有权必须写清楚。

常见组合接口只是方法集合：io.ReadWriter、io.ReadCloser、io.WriteCloser、io.ReadWriteCloser。io.ReaderAt 和 io.Seeker 则是不同能力：前者从指定偏移读取且不改变共享游标，后者改变后续顺序读写的位置。不要因为一个类型碰巧实现了更多接口，就让算法依赖不需要的能力。

2. Read 的精确语义：先处理 n，再处理 err

一次 Read 不保证填满缓冲区。网络分片、管道调度和内部缓冲都可能让它只返回少量数据。合法结果包括 (n>0, nil)、(n>0, io.EOF) 和 (0, io.EOF)；调用方必须先处理 p[:n]，再判断 err，否则会丢掉与 EOF 同时返回的最后一批字节。

func drain(dst io.Writer, src io.Reader) error {
	buf := make([]byte, 32*1024)
	for {
		n, readErr := src.Read(buf)
		if n > 0 {
			if _, err := dst.Write(buf[:n]); err != nil {
				return fmt.Errorf("write: %w", err)
			}
		}
		if readErr != nil {
			if errors.Is(readErr, io.EOF) {
				return nil
			}
			return fmt.Errorf("read: %w", readErr)
		}
	}
}

实现 Reader 时也要避免无进展：除非 len(p)==0，反复返回 (0, nil) 会让调用方空转。标准辅助函数检测到持续无进展时可能返回 io.ErrNoProgress。p 只在 Read 调用期间属于实现方；实现不能保留它并在返回后异步写入。

3. Write、短写与数据所有权

按接口约定，Write 在 n < len(p) 时必须返回非 nil 错误。调用方仍不能假设任意第三方实现都完美；io.Copy 等标准函数会把“短写但无错误”转换为 io.ErrShortWrite。一个健壮的手写循环既要累计已写字节，也要避免在零进展时无限循环。

func writeAll(w io.Writer, p []byte) error {
	for len(p) > 0 {
		n, err := w.Write(p)
		if n > 0 {
			p = p[n:]
		}
		if err != nil {
			return err
		}
		if n == 0 {
			return io.ErrShortWrite
		}
	}
	return nil
}

Write 返回后，实现不得继续访问传入切片，除非文档明确另有约定；相应地，实现若要异步消费必须复制数据。bytes.Buffer 之类内存 writer 会保留内容，但不是保留调用方的切片本身。并发安全同样不由接口保证：多个 goroutine 同时写一个 bytes.Buffer 会产生数据竞争，需由上层串行化或选择明确支持并发的实现。

4. io.Copy 的分派、计数与缓冲区

io.Copy(dst, src) 持续搬运直到 EOF，成功时把 EOF 当作正常结束，并返回已经写入的字节数。出错时计数仍有诊断价值，应和包装后的错误一起记录。它并非永远使用一个固定循环：若 src 实现 io.WriterTo，优先调用 src.WriteTo(dst)；否则若 dst 实现 io.ReaderFrom，调用 dst.ReadFrom(src)；最后才使用内部缓冲区。这使文件或网络类型可以采用更高效的路径。

io.CopyBuffer 允许复用调用方缓冲区，适合高频流水线减少临时分配。缓冲区长度不能为零；并发 copy 不能共享同一切片。不要盲目把缓冲区调得很大：吞吐受系统调用、网络窗口、存储和上下游速度共同约束，应通过 benchmark、执行追踪和实际负载验证。

io.CopyN 精确复制 n 字节；源提前结束会返回错误。它适合有长度前缀的协议片段，但不能单独证明后面没有额外数据。需要把一段输入限制在最多 n 字节时使用 io.LimitReader，需要确认恰好读满则使用 io.ReadFull。

5. ReadAll、ReadFull 与输入大小边界

io.ReadAll 简洁，却意味着把直到 EOF 的全部输入留在内存中。对几 KiB 的可信配置很合适，对上传、代理响应或未知长度输入则可能造成内存峰值甚至拒绝服务。流式处理优先使用 io.Copy 或增量解析；确实需要完整内容时，要先建立硬上限。

func readAtMost(r io.Reader, max int64) ([]byte, error) {
	limited := io.LimitReader(r, max+1)
	b, err := io.ReadAll(limited)
	if err != nil {
		return nil, err
	}
	if int64(len(b)) > max {
		return nil, fmt.Errorf("input exceeds %d bytes", max)
	}
	return b, nil
}

只用 LimitReader(r, max) 再 ReadAll 无法区分“恰好 max 字节”和“被截断”，所以常读 max+1 字节再判断。io.ReadFull(r, buf) 要么填满 buf，要么返回 io.ErrUnexpectedEOF 或其他错误；若一个字节也没读到且遇到 EOF，则返回 io.EOF。协议解析应保留这种区别，因为“干净结束”和“半个帧”含义不同。

6. bufio.Reader、Writer 与 Flush

缓冲的价值是合并许多小 I/O，减少底层调用。bufio.Reader 的 ReadString、ReadBytes、ReadSlice 和 Peek 适合带分隔符协议；其中 ReadSlice 返回的切片引用内部缓冲区，会在后续读取时失效。遇到分隔符前缓冲区已满时，它返回 bufio.ErrBufferFull，调用方若允许长记录就要累积片段。

bufio.Writer 把数据暂存在内存，Write 成功不代表底层已经收到。结束前必须检查 Flush：

bw := bufio.NewWriter(dst)
if _, err := fmt.Fprintln(bw, "header"); err != nil {
	return err
}
if err := bw.Flush(); err != nil {
	return fmt.Errorf("flush: %w", err)
}

不要无条件套多层缓冲。若下层库已经缓冲，额外一层会增加延迟和复杂性；若每写一小段就 Flush，则失去批处理收益。关闭底层资源通常也不会替你刷新独立创建的 bufio.Writer，正确顺序是完成写入、Flush、再 Close，并分别处理错误。

7. Scanner 的 token 模型和长度陷阱

bufio.Scanner 按 token 工作，默认按行切分，也可使用 ScanWords、ScanRunes 或自定义 SplitFunc。循环结束后必须检查 scanner.Err()，否则 I/O 错误和 token 过长会被误认为正常 EOF。

scanner := bufio.NewScanner(src)
scanner.Buffer(make([]byte, 64*1024), 2*1024*1024)
for scanner.Scan() {
	line := scanner.Text() // Text 返回稳定字符串；Bytes 会被下一次 Scan 覆盖
	_ = line
}
if err := scanner.Err(); err != nil {
	return fmt.Errorf("scan: %w", err)
}

默认最大 token 约为 64 KiB，日志、CSV 或生成数据很容易超过。已知合理上限时调用 Buffer；记录可能任意长或需要精细区分分隔符与 EOF 时，用 bufio.Reader。自定义 SplitFunc 必须保证推进输入，错误的 (0, nil, nil) 策略会让扫描器不断请求更多数据，错误的空 token 又可能触发 panic。

8. 组合器：复制、观察、串联与切片

io.MultiWriter(a, b) 把同一批字节依次写给多个 writer；其中一个失败便返回，不提供事务性回滚，之前的目标可能已写入。它适合“写文件同时算哈希”，不适合要求多个副本原子一致的场景。io.TeeReader(r, w) 在读取 r 时同步写入 w，只有被实际读取的字节才会被观察；若消费者提前停止，余下内容不会进入旁路 writer。

io.MultiReader 按顺序拼接多个输入，可用于添加前缀或组合分片。io.SectionReader 在 ReaderAt 上暴露固定区间，既不改变原始游标，也避免读取越界，适合并行读取文件区段。io.NopCloser 给普通 reader 加无操作 Close，常用于满足统一接口，但它没有创造真实资源释放行为。

io.Pipe 提供同步的内存管道：writer 的写入会阻塞，直到 reader 消费；它不是无界队列。这种背压适合把生成器接给编码器或上传器。生产者必须用 CloseWithError 传播失败，消费者提前退出也要关闭 reader，否则另一端可能永久阻塞。

9. EOF、错误包装与部分成功

io.EOF 表示输入正常结束，通常不应包装成业务失败；io.ErrUnexpectedEOF 表示结构尚未完成便结束。判断哨兵错误用 errors.Is，不要比较错误字符串。包装错误时补充操作和进度，例如 copy response after 524288 bytes: connection reset，并用 %w 保留错误链。

I/O 往往不是全有或全无。复制返回 n>0 和非 nil 错误，意味着目标已产生可见的部分结果。调用者必须决定删除临时结果、保留断点、标记为损坏还是重试。直接对最终文件或响应写入时，重试可能重复前缀；工程上常写临时目标，验证完整性后再发布。

对可能短暂失败的设备或网络，重试策略不能仅凭 Reader 接口决定：输入是否可重放、错误是否临时、目标是否幂等都属于更高层协议。通用 copy 函数不应偷偷无限重试。

10. Close 的所有权与错误优先级

Reader/Writer 本身没有 Close，因为内存缓冲不需要释放，而文件、socket、压缩流可能需要。惯用所有权规则是：函数内部创建的资源由函数关闭；调用方传入的资源仍由调用方管理。若函数接管所有权，应在 API 文档和名字中明确。

读场景常用 defer body.Close()，但写场景的 Close 可能完成尾部编码并返回关键错误，例如压缩器写 trailer。因此不能总是忽略关闭错误：

func produce(w io.WriteCloser) (err error) {
	defer func() {
		if closeErr := w.Close(); err == nil && closeErr != nil {
			err = closeErr
		}
	}()
	_, err = io.WriteString(w, "payload")
	return err
}

若主体写入和关闭都失败，至少保留主体错误并记录关闭错误，或使用 errors.Join 表达多个失败。关闭顺序通常与创建顺序相反：先关闭最外层编码器以输出尾部，再刷新缓冲，最后关闭底层资源。

11. 背压、取消和并发流水线

流式处理降低内存占用，但不会自动解决慢消费者。io.Pipe 的同步阻塞会把背压传回生产者；有界缓冲只能吸收短暂波动，不能消除长期速率差。监控时应区分读取等待、写入等待、处理 CPU 和队列时间。

io.Reader 没有 context 参数，阻塞中的 Read 不保证能被任意取消。取消方式取决于具体实现：网络连接可设 deadline 或关闭连接，管道可 CloseWithError，自定义 reader 可在每轮前检查 context。不要启动一个 goroutine 执行永远阻塞的 Read 后只丢弃结果，那会泄漏 goroutine 和资源。

多个 goroutine 不应随意共享顺序 reader，因为游标和记录边界会被交错。并行化通常放在明确分帧之后：一个 goroutine 顺序读取并界定记录，再把独立任务送入有界 worker；输出若必须保持顺序，则还要携带序号并重排。

12. 诊断 I/O 问题的方法

先记录可行动的事实：操作名、逻辑来源与目标、已处理字节、耗时、错误链以及是否由取消导致。不要记录敏感正文。吞吐低时可用 benchmark 比较缓冲尺寸，用 runtime/trace 和阻塞 profile 判断是在系统调用、锁、channel 还是下游等待；文件和网络还需结合操作系统指标。

单元测试不要只用 bytes.Buffer 的理想路径。可编写每次只返回几个字节的 reader、在指定偏移报错的 reader、短写 writer 和零进展实现，验证代码是否正确处理 (n>0, err)、部分输出和异常终止。testing/iotest 提供 OneByteReader、HalfReader、DataErrReader、ErrReader 等工具，适合打破“一次就读满”的错误假设。

内存突然上涨时先查是否误用 ReadAll、Scanner.Text 结果是否被长期保存、缓冲池是否保留超大切片，以及流水线是否积压。高分配并不一定来自系统 I/O，本质可能是每个 token 都转字符串或重复复制。

13. 工程实践清单

  • API 接收最小能力接口，资源所有权另行明确。
  • 对不可信或未知尺寸输入先设硬上限，再决定全量读取还是流式处理。
  • 永远先处理 n，再处理 err；扫描循环结束后检查 Err。
  • 需要精确长度用 ReadFull/CopyN，不要依赖单次 Read。
  • 检查 Flush、Close 和复制的字节计数，设计部分成功后的清理策略。
  • 不默认 reader、writer 可并发使用，也不把通用 I/O 错误擅自无限重试。
  • 使用有界缓冲与背压，确保取消能真正解除底层阻塞。
  • 用异常 reader/writer 测试协议边界，而不只测内存中的顺利路径。

14. 可运行综合示例：限长流式复制并计算摘要

下面程序把输入流复制到目标，同时计算 SHA-256。它最多接受 max 字节，并额外探测一个字节来区分“恰好达到上限”和“超限”；写入与哈希通过 MultiWriter 同步推进。实际文件发布还应在文件主题所述的临时文件和原子替换层完成。

package main

import (
	"bytes"
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"fmt"
	"io"
)

var ErrTooLarge = errors.New("input too large")

func copyDigest(dst io.Writer, src io.Reader, max int64) (int64, string, error) {
	if max < 0 {
		return 0, "", fmt.Errorf("max must be non-negative")
	}
	hash := sha256.New()
	limited := io.LimitReader(src, max+1)
	n, err := io.Copy(io.MultiWriter(dst, hash), limited)
	if err != nil {
		return n, "", fmt.Errorf("copy after %d bytes: %w", n, err)
	}
	if n > max {
		return n, "", ErrTooLarge
	}
	return n, hex.EncodeToString(hash.Sum(nil)), nil
}

func main() {
	var dst bytes.Buffer
	n, digest, err := copyDigest(&dst, bytes.NewBufferString("streaming io\n"), 64)
	if err != nil {
		panic(err)
	}
	fmt.Printf("bytes=%d sha256=%s data=%q\n", n, digest, dst.String())
}

保存为 main.go 后执行：

gofmt -w main.go
go run main.go

预期输出中的 bytes=13，data="streaming io\n"，摘要稳定不变。测试还应覆盖空输入、恰好 64 字节、65 字节、源中途报错与目标短写；这样才能证明限制、计数和部分失败语义都符合预期。

系列导航与关联阅读

官方资料

本文依据 Go 官方规范、标准库文档和 Go 官方博客重新梳理；正文与示例由 WR BLOG 编写。