Go io.Pipe CloseWithError 为什么不会覆盖更早的错误

在 io.Pipe 里，CloseWithError 不是“更新当前错误”，而是“确定这一端的终止原因”。同一端第一次保存下来的关闭错误会成为最终结果，后续再传入别的错误也不会覆盖它。因此，业务错误先关闭、清理错误后关闭时，接收方仍然看到前面的业务错误。

官方文档：https://pkg.go.dev/io#PipeWriter.CloseWithError

背景：Pipe 用关闭动作传播终止原因

io.Pipe 把一个 PipeReader 和一个 PipeWriter 连接起来，常用于边生成边上传、压缩流转发、编码器与消费者串联。它没有内部缓冲：写入会等待读取方消费相应数据。正常结束时，写端关闭后读端得到 EOF；异常结束时，写端调用 CloseWithError(err)，读端随后的读取会得到这个错误。

这个机制解决的是“流为什么终止”，而不是“收集整个生命周期里的所有错误”。理解这一点，就容易解释为什么后一次 CloseWithError 不覆盖前一次。

旧写法问题：多个地方都在 CloseWithError

常见代码会在业务分支、defer 清理和超时处理里分别关闭同一个写端。例如编码失败时先传入 encode failed，退出函数时清理逻辑又传入 cleanup failed。如果把关闭错误当作普通变量，开发者可能以为最后一次调用会“刷新”错误，结果读端仍然收到编码错误。

package main

import (
    "errors"
    "fmt"
    "io"
)

func main() {
    first := errors.New("encode failed")
    later := errors.New("cleanup failed")

    r, w := io.Pipe()
    _ = w.CloseWithError(first) // 首次关闭决定读端看到的终止原因
    _ = w.CloseWithError(later) // 后续错误不会覆盖已经保存的原因

    _, err := r.Read(make([]byte, 1))
    fmt.Println(errors.Is(err, first)) // 按接口语义应为 true
}

还要注意，CloseWithError 总是返回 nil。这个返回值不表示“本次传入的错误赢了”，也不能用来判断是否覆盖成功；它只说明关闭调用本身没有可报告的操作错误。

新规则：关闭错误沿相反方向传播

PipeWriter.CloseWithError(err) 保存写端的结束原因，后续读操作看到该错误；若传入 nil，读端看到 EOF。反过来，PipeReader.CloseWithError(err) 会让后续写操作得到该错误；若传入 nil，写端看到 io.ErrClosedPipe。

因此可以把它记成一句话：谁关闭，原因由对端观察。生产者通常拥有写端，并负责用一次关闭向消费者报告生产结果；消费者若主动放弃读取，则关闭读端，把取消或校验失败传给仍在写入的生产者。

为什么不会覆盖：first-error-wins 是终止语义

Go 标准库内部为读端和写端分别维护一个只保存一次的错误槽。保存逻辑只在槽位为空时写入，所以同一端最早的非空终止原因被保留。与此同时，管道完成信号也只会关闭一次。两层一次性语义共同保证：并发路径即使重复收尾，对端观察到的原因仍然稳定。

这种设计很重要。假设消费者已经因为“编码失败”停止处理，随后一个清理错误把原因改成“临时文件关闭失败”，日志、重试策略和监控标签就可能前后矛盾。保留第一个终止原因，可以让所有观察者围绕同一个根因作出判断。

代码对比：第一次关闭决定可观察结果

下面的测试把规则固定下来。它不依赖字符串比较，而是用 errors.Is 验证错误身份，避免包装错误后断言失效。

func TestFirstCloseErrorWins(t *testing.T) {
    first := errors.New("encode failed")
    later := errors.New("cleanup failed")

    r, w := io.Pipe()
    if err := w.CloseWithError(first); err != nil {
        t.Fatalf("首次关闭失败: %v", err)
    }
    if err := w.CloseWithError(later); err != nil {
        t.Fatalf("重复关闭失败: %v", err)
    }

    _, err := r.Read(make([]byte, 1))
    if !errors.Is(err, first) {
        t.Fatalf("读端错误 = %v，期望保留首次错误", err)
    }
}

反例是先调用普通的 Close()，再调用 CloseWithError(bizErr)。写端的 Close() 等价于 CloseWithError(nil)，而写端的 nil 会被转换为正常结束的 EOF。由于终态已经确定，后来传入的业务错误无法替换它，读端只会看到 EOF。这类顺序错误很容易把真正故障伪装成正常结束。

nil 的语义并不对称

所以不要把两个方向的 nil 都理解成 EOF。EOF 描述的是写端没有更多数据；读端关闭意味着写入目标已经不存在，写端自然更接近“管道已关闭”的失败。

兼容注意：读端和写端各有一个错误槽

“第一个错误胜出”是针对同一端重复关闭而言。读端和写端各自保存关闭原因，并不是全局只有一个共享错误。若两端都由不同 goroutine 主动关闭，最终某次读写看到哪个错误，还会受到操作方向和关闭时序影响。工程上应避免把两端都设计成争夺最终错误的所有者。

另外，io.Pipe 的同步传输特性没有因为关闭规则而改变。若写 goroutine 在消费者启动前大量写入，它仍然会阻塞；关闭错误只能解除和解释终止，不能替代正确的并发组织。

采用建议：只让一个所有者负责关闭

最稳妥的方式是把写端交给生产者 goroutine，并让它在唯一出口调用一次 CloseWithError。成功时传 nil，失败时传真正的生产错误。调用方只消费读端，不再补一次写端关闭。

func startProducer(w *io.PipeWriter) {
    go func() {
        err := produce(w)
        _ = w.CloseWithError(err) // 唯一所有者在唯一出口发布结果
    }()
}

func consume(r *io.PipeReader) error {
    _, err := io.Copy(io.Discard, r)
    return err // 直接得到生产者发布的终止原因
}

如果必须同时保留业务错误和清理错误，应先完成清理，再用 errors.Join(primaryErr, cleanupErr) 合并，然后只调用一次 CloseWithError。前提是两个错误在首次关闭前都已知；一旦终止原因已经发布，就不应再试图修改。另一种做法是用独立结果通道上报附加错误，让管道错误只承担主要终止原因。

func finish(w *io.PipeWriter, primaryErr error, cleanup func() error) {
    cleanupErr := cleanup()
    finalErr := errors.Join(primaryErr, cleanupErr) // 关闭前统一整理错误
    _ = w.CloseWithError(finalErr)                 // 只发布一次终态
}

排查清单

• 搜索同一个 PipeReader 或 PipeWriter 的全部 Close、CloseWithError 调用点。
• 确认普通 Close() 是否早于业务错误关闭，导致错误被 EOF 或 ErrClosedPipe 固化。
• 为每一端指定唯一关闭所有者，并把关闭放到单一出口。
• 测试中使用 errors.Is 验证首次错误，额外覆盖成功关闭、消费者提前退出和并发取消。
• 需要多个错误时，在首次关闭前合并，或通过单独通道传递附加诊断信息。

常见问题

后一次 CloseWithError 返回 nil，是否代表覆盖成功？

不是。该方法按契约总是返回 nil，重复调用不会覆盖同一端已经保存的错误。

先 Close 再 CloseWithError 会怎样？

第一次普通关闭已经确定终态。写端先 Close() 时，读端通常得到 EOF；后面的业务错误不会替换它。

第一个错误是否一定是整个系统最重要的错误？

不一定，它只是最先被该端发布的终止原因。因此应通过所有权和单一出口控制发布顺序，而不是让多个 goroutine 竞争关闭。

结论：io.Pipe 把关闭错误当作不可变的终态信号。同一端第一次关闭决定对端看到的原因，后续调用只做幂等收尾。把关闭权交给一个明确所有者，并在首次关闭前完成错误整理，就能避免根因被 EOF 掩盖或被误以为会被后续错误替换。