strings.Builder无法应对分块流场景，因其是纯内存累积结构，无流式写入语义，不能在写入中途触发切片、上报或压缩；需用可插拔的ChunkWriter实现分块io.Writer，核心是嵌入目标Writer并在Write中缓存、判断阈值、触发回调。
为什么直接用 strings.Builder 无法应对分块流场景
因为 strings.Builder 是纯内存累积结构，没有流式写入语义；一旦开始写入，就无法在中途触发“切片”“上报”或“压缩”等动作。真实场景中，比如日志聚合、模板渲染后按 4KB 分块上传、或向 WebSocket 连续推送渲染结果，都需要在写入过程中感知边界并干预行为——这要求 Writer 必须能拦截每次 Write 调用，而非仅拼接字节。
如何实现一个可插拔的分块 io.Writer
核心是嵌入一个目标 io.Writer（如 os.Stdout 或自定义缓冲器），并在 Write 方法中做三件事：缓存、判断是否达到分块阈值、触发回调。关键点在于避免重复拷贝和误判多字节字符边界：
- 用
bytes.Buffer作临时缓存，比切片拼接更高效且自带Write接口兼容性 - 分块判断必须基于字节数（
len(p)），不是 rune 数——UTF-8 下一个汉字占 3 字节，按 rune 切会破坏编码 - 回调函数签名建议为
func([]byte) error，接收当前块原始字节，由调用方决定落盘、加密或发送 - 不要在
Write内部做阻塞操作（如 HTTP 请求），否则会卡住整个写入流
type ChunkWriter struct {
buf *bytes.Buffer
limit int
onChunk func([]byte) error
}
func (w *ChunkWriter) Write(p []byte) (n int, err error) {
w.buf.Write(p)
if w.buf.Len() >= w.limit {
chunk := w.buf.Bytes()
if err = w.onChunk(chunk); err != nil {
return 0, err
}
w.buf.Reset()
}
return len(p), nil
}
Write 返回值不等于实际分块长度，这点必须手动对齐
Go 的 io.Writer 合约只要求返回「已接受字节数」，不承诺已处理或已分发。上面示例中 Write 总是返回 len(p)，但若 onChunk 失败，这块数据其实没被消费——此时应考虑是否重试、丢弃或 panic。常见错误是假设「写成功 = 已分发」，导致数据静默丢失：
- 如果
onChunk是网络发送，需检查返回的error是否可重试（如net.ErrClosed不可重试，context.DeadlineExceeded可选重试） - 若要求严格有序分块，不能在
onChunk异步执行；否则后一块可能早于前一块到达下游 -
buf.Reset()必须在onChunk成功后调用，否则失败时重复传递同一块
和 bufio.Writer 混用时的缓冲叠加风险
如果把 ChunkWriter 包裹在 bufio.NewWriter 外层，会出现双重缓冲：一次在 ChunkWriter.buf，一次在 bufio.Writer 内部。结果是分块逻辑看到的是未刷出的 bufio 缓冲内容，完全失效。正确做法是：
立即学习“go语言免费学习笔记（深入）”；
- 让
ChunkWriter直接包装最终目的地（如net.Conn），把bufio.Writer当作它的onChunk回调里的内部优化 - 或者反向组合：用
bufio.Writer包裹ChunkWriter，但只在Flush时触发分块——这就退化成定时批量，失去流式响应能力 - 需要实时分块 + 高吞吐时，干脆去掉
bufio.Writer，改用syscall.Write或conn.SetWriteDeadline控制底层
动态分块的本质不是缓冲策略，而是写入时机的控制权移交。越靠近数据源头做决策，越容易保持低延迟和高确定性。
