必须初始化io.Writer并检查Write返回的n值；未初始化调用会panic，n<len(p)是常态需处理， bufio.Writer可优化性能但需显式Flush，二进制数据禁用io.WriteString。
没初始化就调用 Write 必 panic；不检查返回的 n 值，数据大概率丢一半。
io.Writer 变量声明后直接用会崩溃
写 var w io.Writer 不等于“准备好能用了”，它就是 nil。只要一调 w.Write 或 io.WriteString(w, ...)，立刻触发 panic: invalid memory address or nil pointer dereference。
这不是编译错误，测试容易漏掉——尤其在配置未加载、依赖注入失败时。
- 正确做法：必须显式赋值，比如
w = os.Stdout、w = &bytes.Buffer{}、w = file - 别在函数参数里默认给
nil然后靠 if 判断跳过写入：接口方法调用发生在判断前，已经 panic 了 - 单元测试中要覆盖
w为nil的路径，否则上线后第一个空配置就挂
Write 返回的 n 不等于 len(p) 是常态，不是 bug
Write([]byte) 的语义从来不是“全写完或全失败”，而是“尽力写，写多少算多少”。网络抖动、缓冲区满、磁盘空间不足……都会导致 n < len(p) 且 err == nil，或者 n > 0 && err != nil（如 io.ErrShortWrite）。
立即学习“go语言免费学习笔记（深入）”；
- 必须检查
n和err两个返回值，不能只看err - 典型误写：
_, err := w.Write(buf); if err != nil { ... }—— 这完全忽略部分写入，后续逻辑可能基于“已全写”做假设，导致数据截断 - 安全模式：用
io.Copy替代手写循环；它内部自动切片重试剩余字节，你不用管 offset - 自定义
Write实现时，若底层写入只完成一部分，必须如实返回该n值，不能硬补成len(p)，否则上游工具（如io.Copy）会死循环
网络和文件写入别裸调 Write，记得套 bufio.Writer 并 Flush
对 net.Conn 或 *os.File 直接调 Write，每次都是系统调用，小数据高频写性能极差，还可能被 TCP Nagle 算法卡住。
- 推荐包装：
wr := bufio.NewWriter(conn)，之后所有Write都进内存缓冲，默认 4KB - 关键点：缓冲只是暂存，
Flush()才真正发出去；连接关闭前必须显式调用，不能只靠defer wr.Flush()（panic 或提前 return 会让它跳过） - 反例：
conn.Write([]byte("OK"))发一条短消息 → 一次 syscall；换成bufio后，100 条合并成几次发，延迟和吞吐都改善 - 如果协议要求严格消息边界（如 header + body），
bufio可能引入歧义，此时应手动拼完整包再调Write，并校验n == len(fullPacket)
二进制数据别碰 io.WriteString
io.WriteString 内部会把字符串转成 []byte，而 Go 的 string 是只读 UTF-8 序列，无法安全表示含 \x00、\xFF 或非法 UTF-8 字节的原始二进制数据。
- 危险写法：
io.WriteString(w, string([]byte{0x00, 0xFF}))—— 转换过程可能被截断或污染 - 正确写法：
w.Write([]byte{0x00, 0xFF})或用binary.Write(w, binary.BigEndian, value) - 结构体序列化优先走
encoding/binary，它按字段顺序生成确定性二进制布局，不加 padding，也不依赖字符串编码
最易被忽略的其实是 n 值的语义：它不是“应该写多少”，而是“这次真写进去几个”。所有基于 io.Writer 的封装、转发、重试逻辑，都绕不开这个数字——它既是事实，也是契约。
