go服务端限速必须用github.com/juju/ratelimit按字节限速，而非rate.limiter；需先writeheader、避免gzip绕过、透传flush，并处理content-length与上下文超时。
Go 框架本身不提供开箱即用的带宽限速能力，必须手动在 I/O 路径上插入 rate.Limiter 或 juju/ratelimit 实现字节级节流；直接改 HTTP 客户端超时、用 io.LimitReader 截断流、或在 goroutine 里 sleep 都不是真限速。
rate.Limiter 为什么不能直接用于下载/上传限速
标准 golang.org/x/time/rate.Limiter 默认按「事件次数」计数，不是字节。比如 rate.NewLimiter(rate.Limit(1024*1024), 1024*1024) 表示「每秒最多 1024×1024 次调用」，不是「每秒最多 1MB 字节」——这会导致限速单位错位，实际速率远超预期。
常见错误现象：
- 设了 512KB/s 却跑出 50MB/s：因为 burst 被当成了字节数，实际是允许 512000 次小读（如每次 1 字节）
- 首包卡顿严重：burst 小于 limit 导致初始化 panic 或令牌桶为空
- 限速失效但无报错：只调
AllowN或ReserveN不调Wait/Delay，令牌申请后不阻塞
正确做法是显式用 rate.Limit(512*1024)（别写 rate.Every(time.Second/512000)，编译器可能优化掉除法），并确保每次 Read 后用真实字节数调 WaitN(ctx, n)。
下载限速必须包装 io.Reader，不是改 http.Client
限速点必须落在 http.Response.Body 和目标 io.Writer（如文件）之间，而不是动 http.Client.Timeout 或 context.WithTimeout ——它们只管连接建立和响应头超时，跟吞吐率无关。
实操要点：
- 不要直接在
resp.Body上time.Sleep：会阻塞整个连接，破坏 TCP 流控与复用 - 必须实现
io.ReadCloser：自定义 reader 的Close()方法要透传resp.Body.Close()，否则连接泄漏 - 每次
Read(p []byte)返回n后，立刻调limiter.WaitN(ctx, n)；若用ReserveN，必须检查res.OK()并显式time.Sleep(res.Delay()) - 避免预估字节数：不能固定传
WaitN(ctx, 4096)，网络底层可能返回更少，要用实际n
服务端响应限速得用 juju/ratelimit，不是 rate.Limiter
给 http.ResponseWriter 限速时，golang.org/x/time/rate 语义不匹配，必须换 github.com/juju/ratelimit。它的 ratelimit.NewBucketWithRate(1024*1024, 1024*1024) 第一个参数就是「字节/秒」，无歧义。
关键细节：
- 必须先调
w.WriteHeader(statusCode)再包装，否则 header 自动写入可能覆盖状态码 - gzip 中间件会绕过限速：要在压缩之后再包装，即包装
gzipResponseWriter，而非原始ResponseWriter - 务必设置
Content-Length：限速后单次Write耗时变长，不设长度易触发 client 断连 + goroutine 泄漏 - 禁用
io.Copy：它会一次性读完 body，跳过限速逻辑；需手动分块Read/Write+ratelimit.Writer.Write
上传限速必须加 io.Pipe + goroutine 隔离读写
把限速 io.Reader 直接当 http.Request.Body 传入是危险的：HTTP client 可能多次 Read（尤其 multipart 场景），导致令牌被重复扣减、速率翻倍甚至死锁。
安全路径：
- 启动一个 goroutine，从限速 reader 读 → 往
io.PipeWriter写 - 用
io.PipeReader作为新req.Body -
io.PipeWriter.Close()必须由写端触发，否则读端永久阻塞 - 限速 reader 的
Close()要透传原始req.Body.Close()，尤其 multipart 场景下 boundary 字节不能丢 - 测试时用
curl -F "file=@big.zip"观察接收速率是否稳定，同时检查文件完整性
真正难的不是写限速逻辑，而是让限速器和 HTTP client 的内部缓冲、重试、multipart 解析完全解耦——漏掉 io.Pipe 或 Close 透传，线上就容易出现 goroutine 堆积和连接泄漏。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
