io.Writer 实现必须返回真实写入字节数而非 len(p)，因接口契约要求准确反映处理进度；网络写可能部分成功，过滤型 Writer 完整消费才返回 len(p)，Discard 永远返回 len(p)；禁止 Write 中阻塞、Flush 或非原子统计；装饰器需显式实现 WriteString/Close 等接口；二进制数据禁用 io.WriteString。
io.Writer 实现必须返回真实写入字节数，不是 len(p)
很多人以为 Write 方法只要把输入切片“收下来”就算完成，于是写成 return len(p), nil。这是错的——它违反了接口契约，会导致 io.Copy、fmt.Fprint 等上游逻辑误判传输状态。
- 真实场景中，网络写可能只发出前 128 字节就因对端关闭而失败，此时必须返回
n=128, err=io.ErrClosedPipe - 过滤型 Writer（如跳过 BOM、移除控制字符）若已完整消费
p，仍应返回len(p), nil；只有处理中断才返回n -
io.Discard就是典型：什么也不存，但永远返回len(p), nil，因为它“成功处理了全部输入”
别在 Write 里做耗时操作或调用 Flush
自定义 Write 是数据流的关键节点，任何阻塞都会拖慢整个链路。比如在 Write 里直接 fmt.Printf 打印进度，1GB 文件会触发数万次系统调用，终端卡死。
- 进度回调要轻量，建议采样（如每 64KB 触发一次），避免高频更新
- 缓冲类 Writer（如包装
bufio.Writer）必须自己管理缓冲区，不能在Write内部调用Flush()—— 那会破坏调用方对刷新时机的控制 - 日志统计类装饰器要加
atomic.AddUint64，否则 32 位系统上uint64读写非原子，会丢计数
Writer 装饰器必须显式实现所有被探测的接口
日志库（如 zap、slog）不会只看 io.Writer，还会检查是否实现了 io.Closer、io.StringWriter 或 WriteString 方法。只嵌入一个 w io.Writer 字段，不手动透传这些方法，运行时一调就 panic。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 必须显式写出
WriteString和Close方法，哪怕只是转发给底层 -
Close要做类型断言：if c, ok := w.(io.Closer); ok { return c.Close() }，否则对不可关对象返回nil更安全 - 别依赖匿名字段自动提升方法——Go 不支持这种“隐式继承”
二进制数据禁止用 io.WriteString
io.WriteString 本质是 w.Write([]byte(s))，而 Go 的 string 类型是只读 UTF-8 序列，无法安全表示含 \x00、\xFF 或非法 UTF-8 字节的原始二进制数据。
立即学习“go语言免费学习笔记（深入）”；
- 写二进制一律用
w.Write([]byte{0x00, 0xFF})或binary.Write(w, binary.BigEndian, value) - 模板渲染、HTTP 响应等文本场景可用
io.WriteString，但前提是确认内容纯 UTF-8 且无嵌入零字节 - 反例：
io.WriteString(w, string([]byte{0x00, 0xFF}))—— 可能在 CGO 边界截断或引发未定义行为
实际写法中最容易被忽略的是：Write 方法的语义不是“物理落盘”，而是“逻辑处理完成”。 这个理解偏差会让自定义 Writer 在流式转发、加密包装、日志注入等场景下静默出错，而且很难复现。
