本文介绍使用 `juju/ratelimit` 库结合令牌桶算法，在 go http 服务中对大文件（如 1gb）的上传和下载流量进行精确、可配置的速率限制（例如 1mb/s），兼顾性能与资源可控性。
在构建高可用文件服务时，不限速的上传/下载可能耗尽带宽、拖慢其他请求，甚至引发 OOM 或连接超时。Go 原生 io.Copy 不提供流控能力，但通过封装 io.Reader/io.Writer 并注入速率限制逻辑，即可优雅解决。
核心方案是采用令牌桶（Token Bucket）算法：以恒定速率向桶中添加令牌，每次读/写操作需消耗令牌；桶满则阻塞，从而实现平滑限速。推荐使用成熟稳定的 github.com/juju/ratelimit 库，它线程安全、低开销，且支持动态调整速率。
✅ 下载限速（服务端响应流控）
对 http.ResponseWriter 的写入进行限速，需包装 http.ResponseWriter 的 Write 方法为受控 io.Writer：
import "github.com/juju/ratelimit"
func downloadFile(w http.ResponseWriter, r *http.Request) {
// 示例：从磁盘读取大文件
file, err := os.Open(`e:\test\test.mpg`)
if err != nil {
http.Error(w, "file not found", http.StatusNotFound)
return
}
defer file.Close()
// 设置限速：1MB/s = 1_048_576 bytes/sec，桶容量设为 2x（防突发）
bucket := ratelimit.NewBucketWithRate(1_048_576, 2_097_152)
// 包装 ResponseWriter 为限速 Writer
limitedWriter := ratelimit.Writer(w, bucket)
// 设置必要 Header
w.Header().Set("Content-Type", "application/octet-stream")
w.Header().Set("Content-Disposition", `attachment; filename="test.mpg"`)
// 使用限速 Writer 复制文件
_, err = io.Copy(limitedWriter, file)
if err != nil && err != io.ErrUnexpectedEOF {
log.Printf("download error: %v", err)
}
}✅ 上传限速（客户端请求流控）
对 r.FormFile 返回的 io.ReadCloser 进行限速，只需用 ratelimit.Reader 封装：
func uploadFile(w http.ResponseWriter, r *http.Request) {
file, _, err := r.FormFile("file")
if err != nil {
http.Error(w, "invalid file form field", http.StatusBadRequest)
return
}
defer file.Close()
// 限速：1MB/s，桶容量 1MB（可根据并发调整）
bucket := ratelimit.NewBucketWithRate(1_048_576, 1_048_576)
limitedReader := ratelimit.Reader(file, bucket)
os.MkdirAll(`e:\test`, 0755)
out, err := os.Create(`e:\test\test.mpg`)
if err != nil {
http.Error(w, "failed to create file", http.StatusInternalServerError)
return
}
defer out.Close()
_, err = io.Copy(out, limitedReader) // ← 关键：使用限速 Reader
if err != nil {
http.Error(w, "upload failed", http.StatusInternalServerError)
return
}
w.WriteHeader(http.StatusOK)
w.Write([]byte("upload success"))
}⚠️ 注意事项与最佳实践
- 桶容量（capacity）建议设为速率的 1–3 倍：过小易因瞬时抖动频繁阻塞；过大则削弱限速效果。
- 避免在高频 Handler 中重复创建 bucket：应预创建并复用（如作为包变量或依赖注入），减少 GC 压力。
- 配合超时控制：为大文件操作显式设置 r.Context().Done() 或 http.TimeoutHandler，防止无限等待。
- 监控与调优：可通过 bucket.Available() 定期采样剩余令牌，结合 Prometheus 暴露实时速率指标。
- 替代方案参考：若需更轻量级实现，可基于 time.Ticker + channel 自建简单漏桶；但生产环境强烈推荐 juju/ratelimit。
通过以上方式，你能在不修改业务逻辑的前提下，以极小侵入性为任意 io.Reader/io.Writer 添加精准、稳定、可配置的带宽控制，让大文件传输既可靠又可控。
