实现 io.Writer 时，若逻辑上主动忽略部分输入字节（如过滤、截断、采样），仍应返回 len(p) 表示“成功处理全部输入”，仅在发生真正错误（如底层写失败、资源不可用）时才返回 n < len(p) 并附带非 nil 错误。
实现 `io.writer` 时，若逻辑上主动忽略部分输入字节（如过滤、截断、采样），仍应返回 `len(p)` 表示“成功处理全部输入”，仅在发生真正错误（如底层写失败、资源不可用）时才返回 `n
在 Go 中，io.Writer 是一个基础而严格的接口，其契约（contract）远不止方法签名那么简单。核心在于 Write(p []byte) (n int, err error) 的语义约定：n 表示“成功处理”的字节数，而非“物理落盘/传输”的字节数；只要处理过程无异常，就必须返回 len(p)。
这看似反直觉——尤其当你设计一个“过滤型写入器”（例如跳过前 10 字节、只保留偶数索引字节）时，实际写入下游的数据量必然少于 len(p)。但关键在于区分两个概念：
- ✅ 处理（handling）：接收、解析、按业务规则决定是否保留或丢弃每个字节——这一过程本身是完整的、无错误的；
- ❌ 写入失败（failure）：因 I/O 错误、缓冲区满、连接中断等导致无法完成预定处理流程。
根据 Go 官方文档 明确要求：
“Write must return a non-nil error if it returns n < len(p)”
这意味着：n < len(p) 和 err != nil 必须同时成立，二者互为充要条件。它不是可选建议，而是接口实现的强制契约。违反此约定将导致与标准库（如 io.Copy、bufio.Writer）及其他兼容组件产生未定义行为——例如 io.Copy 可能提前终止、重试逻辑错乱，甚至静默丢数据。
下面是一个符合规范的“跳过前 N 字节”写入器示例：
type SkipNWriter struct {
w io.Writer
skip int
}
func (s *SkipNWriter) Write(p []byte) (n int, err error) {
// 逻辑上“处理”全部 p：计算应写入范围
if len(p) <= s.skip {
// 全部跳过 → 仍视为成功处理 len(p) 字节
s.skip -= len(p)
return len(p), nil
}
// 写入剩余部分
writeBuf := p[s.skip:]
s.skip = 0
n, err = s.w.Write(writeBuf)
// ⚠️ 关键：即使 s.w.Write 返回 n' < len(writeBuf)，我们也必须传播该错误，
// 且此时本层 Write 的返回值 n 应为 len(p)，但需修正为实际写入量 + 已跳过量？
// 不！正确做法是：仅当 s.w.Write 出错时，本层才返回错误；否则始终返回 len(p)
if err != nil {
return len(p), err // ✅ 错误时仍返回 len(p)？不！见下方说明
}
return len(p), nil // ✅ 正确：处理完成，无错误 → 返回 len(p)
}⚠️ 注意：上述示例中最后一行 return len(p), nil 是正确的，但中间注释提到的场景需要澄清——实际上，如果底层 s.w.Write(writeBuf) 返回 n' < len(writeBuf) 且 err == nil，则它已违反 io.Writer 契约，属于 bug。因此你的包装器无需为此兜底；你只需确保：
- 自身逻辑无错误 → 总是返回 len(p), nil；
- 底层调用出错 → 返回 len(p), err（注意：此处 n 仍为 len(p)，因为“处理请求”已完成，只是底层执行失败）。
然而，更严谨的实践是：若底层 Write 返回 n' < len(writeBuf) 且 err == nil，应将其视为违反契约的非法状态，并主动 panic 或记录警告（生产环境建议封装为明确错误）。
最后，也是最重要的一点：文档即契约。你的类型必须在 Godoc 中清晰声明行为，例如：
// SkipNWriter writes all bytes to the underlying writer except the first n bytes. // It always reports len(p) as written on success, per io.Writer contract. // The caller must not assume written bytes are persisted verbatim.
总结：
- ✅ 成功过滤/变换 → return len(p), nil；
- ❌ 底层 I/O 失败 → return len(p), err（保持 n == len(p)，错误反映真实问题）；
- ? 绝不返回 n < len(p) 且 err == nil；
- ? 用文档明确告知使用者“哪些字节被处理了”，而非“哪些字节被存储了”。
遵循此原则，你的 io.Writer 才是可组合、可预测、符合 Go 生态共识的合格实现。
