Go gzip.Writer写入HTTP响应时的刷新时机设计

流式 HTTP 响应里，gzip.Writer 的刷新分成两层：gzip.Flush() 先把压缩器里的数据写到 http.ResponseWriter，HTTP 层是否立即把缓冲交给客户端，还要看 http.Flusher 或 http.ResponseController。因此，想让客户端在一批消息结束后尽快读到内容，通常要“压缩刷新一次，再刷新 HTTP 响应一次”；请求结束时仍然必须调用 gzip.Close() 写出 gzip 尾部。

先把两层刷新职责拆开

这类问题的现场通常是：服务端循环里一直调用 gz.Write，但浏览器或长连接客户端要等很久才收到数据。原因不一定是 gzip 没有写入，而是压缩缓冲和 HTTP 缓冲叠在了一起。gzip.Writer.Write 的压缩字节不保证立即落到底层；gzip.Writer.Flush 只保证待处理的压缩数据写到下层 writer。HTTP 层还可能由服务器实现、ResponseWriter 包装器或代理继续缓冲。

所以不要把两个动作写成一个含糊的“刷新”：压缩层用 gz.Flush()，HTTP 层用 http.NewResponseController(w).Flush()。ResponseController 能处理支持 Flush 的 ResponseWriter 或可解包的包装器；如果底层不支持，应该把错误当成兼容性信号，而不是假设数据一定已经到达客户端。

先设置响应头，再建立压缩写入器

响应头必须在首个字节写出前确定。下面的处理器把每条消息视为一个刷新边界，使用 ResponseController 统一提交 HTTP 层缓冲：

func stream(w http.ResponseWriter, r *http.Request) {
	// 先写响应头，避免 gzip 的首个字节触发默认的 Content-Type。
	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
	w.Header().Set("Content-Encoding", "gzip")
	w.Header().Set("Cache-Control", "no-cache")

	// ResponseController 负责触达 HTTP 层的 Flush 能力。
	rc := http.NewResponseController(w)
	gz := gzip.NewWriter(w)
	messages := []string{"第一批数据\n", "第二批数据\n", "最后一批数据\n"}

	for _, msg := range messages {
		// 业务层先形成完整消息，再交给 gzip 压缩。
		if _, err := io.WriteString(gz, msg); err != nil {
			http.Error(w, "write compressed response failed", http.StatusInternalServerError)
			return
		}
		// gzip.Flush 只提交压缩层，不代表客户端已经可见。
		if err := gz.Flush(); err != nil {
			return
		}
		// HTTP 层不支持 Flush 时，退出并记录真实错误，不伪造流式能力。
		if err := rc.Flush(); err != nil {
			return
		}
	}

	// Close 会写出 gzip footer；它不负责关闭底层 ResponseWriter。
	if err := gz.Close(); err != nil {
		return
	}
	// 需要尽快提交尾部时，在 Close 之后再刷新一次 HTTP 层。
	_ = rc.Flush()
}

生产代码还应把错误写入请求级日志，并避免在部分响应已经发送后再次调用 http.Error 修改状态码。示例强调的是职责边界：如果只调用 rc.Flush 而没有先调用 gz.Flush，HTTP 层可能只能刷新到一个空的或不完整的压缩片段。

按消息边界刷新，最后用 Close 收尾

刷新频率要和协议或业务消息对齐。事件流可以一条事件一次，日志流可以按若干行合并，生成式文本则可按一段或一个 token 批次合并。每次小写入都刷新会增加压缩同步点和网络写入次数，通常既没有更低延迟，也会损失压缩效率。

结束路径要区分两种情况：正常结束调用 Close，让 gzip 写出 footer；客户端提前断开时，Flush 或 Close 的错误应作为连接终止记录，不要继续写入。不要用 Flush 代替 Close，因为前者不会写出完整 gzip 尾部。

用排查清单验证刷新时机

先确认响应头没有在压缩前被错误发送，再检查每个消息边界是否同时出现 gz.Flush 与 HTTP 刷新。若应用日志显示两次调用都成功而客户端仍然聚合显示，继续检查反向代理的缓冲策略、客户端读取方式和连接协议；http.Flusher 的成功只说明服务器提交了缓冲，不是端到端即时送达承诺。

• 第一块是否在首个完整消息后出现，而不是等 Handler 返回？
• 是否把 gzip.Close 错误和 HTTP 刷新错误分开记录？
• 是否在不支持刷新时仍保证完整响应可以正常结束？

常见问题

只调用 gzip.Writer.Flush 可以吗？

它适合提交压缩层数据，但不能代替 HTTP 层刷新。需要增量可见时，两层都应按边界处理。

Close 后还需要 Flush 吗？

Close 已经写入 gzip footer；如果希望尾部尽快交给客户端，可以再调用一次 HTTP 层 Flush，并处理返回错误。

代理会让 Flush 失效吗？

可能会。代理或客户端仍可聚合缓冲，因此排查时要把应用层、HTTP 层和中间层分开判断。