Go 限流入门：用令牌桶保护一个 HTTP 接口

限流不是大公司才需要的功能。一个公开表单、一个登录接口、一个 AI 调用入口，如果没有任何限制，很容易被误用、刷爆或拖垮下游依赖。对 Go 初学者来说，限流最值得先理解的是“保护边界”：限制请求进入系统的速度，而不是等数据库或外部服务扛不住后再处理错误。

PlumePHP 2024-03-07 9 分钟阅读 4023 字

本文用令牌桶思路写一个 HTTP 中间件。示例不依赖第三方库，便于理解原理。真实项目可以使用成熟库或网关限流，但理解基本模型后，你会更知道配置该怎么设。

令牌桶的直觉

令牌桶可以想象成一个小桶：系统按固定速度往桶里放令牌，桶满了就不再增加。每个请求进来要拿一个令牌，拿到就通过，拿不到就返回 429。桶容量决定允许的突发量，补充速度决定长期平均速率。

比如每秒补 5 个令牌，桶容量 10。平时没请求时桶会积到 10 个，突然来 10 个请求可以马上通过；之后如果继续高频请求，就只能按每秒 5 个的速度通过。

一个简单 Limiter

先写结构：

type TokenBucket struct {
	mu       sync.Mutex
	tokens   float64
	capacity float64
	rate     float64
	last     time.Time
}

func NewTokenBucket(rate float64, capacity int) *TokenBucket {
	return &TokenBucket{
		tokens:   float64(capacity),
		capacity: float64(capacity),
		rate:     rate,
		last:     time.Now(),
	}
}

允许请求：

func (b *TokenBucket) Allow() bool {
	b.mu.Lock()
	defer b.mu.Unlock()

	now := time.Now()
	elapsed := now.Sub(b.last).Seconds()
	b.last = now

	b.tokens += elapsed * b.rate
	if b.tokens > b.capacity {
		b.tokens = b.capacity
	}
	if b.tokens < 1 {
		return false
	}
	b.tokens--
	return true
}

这里用 float64 是为了表达“半个令牌”这类时间累计。初学者不用纠结细节，先理解它每次请求都会按经过时间补充令牌，然后尝试消耗一个。

做成 HTTP 中间件

全局限流：

func RateLimit(bucket *TokenBucket, next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if !bucket.Allow() {
			w.Header().Set("Retry-After", "1")
			http.Error(w, "too many requests", http.StatusTooManyRequests)
			return
		}
		next.ServeHTTP(w, r)
	})
}

使用：

bucket := NewTokenBucket(5, 10)
mux.Handle("/api/search", RateLimit(bucket, searchHandler))

这会限制整个接口总流量。对于内部小服务，全局限流已经有价值。但如果多个用户共享一个桶，一个用户刷接口会影响其他用户。公开接口更常见的是按 IP 或按用户限流。

按 IP 限流

维护一个 map：

type IPLimiter struct {
	mu      sync.Mutex
	rate    float64
	burst   int
	buckets map[string]*TokenBucket
}

func NewIPLimiter(rate float64, burst int) *IPLimiter {
	return &IPLimiter{
		rate:    rate,
		burst:   burst,
		buckets: make(map[string]*TokenBucket),
	}
}

获取 bucket：

func (l *IPLimiter) bucket(ip string) *TokenBucket {
	l.mu.Lock()
	defer l.mu.Unlock()

	b, ok := l.buckets[ip]
	if !ok {
		b = NewTokenBucket(l.rate, l.burst)
		l.buckets[ip] = b
	}
	return b
}

中间件：

func (l *IPLimiter) Middleware(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		ip, _, err := net.SplitHostPort(r.RemoteAddr)
		if err != nil {
			http.Error(w, "bad remote address", http.StatusBadRequest)
			return
		}
		if !l.bucket(ip).Allow() {
			http.Error(w, "too many requests", http.StatusTooManyRequests)
			return
		}
		next.ServeHTTP(w, r)
	})
}

如果服务在反向代理后面，RemoteAddr 可能是代理地址。这时要由可信代理设置 X-Forwarded-For 或 X-Real-IP，应用只在确认来源可信时读取这些头。不要无条件相信客户端传来的 IP 头。

清理长期不用的 bucket

按 IP 限流会让 map 增长。可以记录最后访问时间：

type visitor struct {
	bucket   *TokenBucket
	lastSeen time.Time
}

定期清理：

func (l *IPLimiter) Cleanup(maxIdle time.Duration) {
	l.mu.Lock()
	defer l.mu.Unlock()

	now := time.Now()
	for ip, v := range l.visitors {
		if now.Sub(v.lastSeen) > maxIdle {
			delete(l.visitors, ip)
		}
	}
}

示例为了简短前面用了 map[string]*TokenBucket，实际项目可以改成 map[string]visitor。限流状态本身也需要管理，否则防护代码会变成内存增长来源。

测试限流

测试全局桶比较容易：

func TestTokenBucketAllowsBurst(t *testing.T) {
	b := NewTokenBucket(1, 2)
	if !b.Allow() || !b.Allow() {
		t.Fatal("expected first two requests to pass")
	}
	if b.Allow() {
		t.Fatal("expected third request to be limited")
	}
}

涉及时间的测试容易不稳定。更严谨的设计是把时钟注入 limiter，但入门阶段先测不依赖等待的 burst 行为。不要在测试里随便 time.Sleep(2 * time.Second)，测试会变慢，还可能在 CI 上抖动。

常见问题 FAQ

Q: 令牌桶和漏桶有什么区别？
A: 令牌桶允许突发（桶里有令牌就能立刻通过），漏桶更严格平滑（固定速率输出）。令牌桶更适合 web 接口，漏桶更适合消息队列整形。

Q: 按 IP 限流会不会误伤 NAT 用户？
A: 会。公司内网、校园网、移动运营商多个用户共享出口 IP。可以结合用户 ID 限流，或把 IP 限流阈值设高一些。

Q: 第三方限流库推荐？
A: golang.org/x/time/rate 是最常用的标准扩展库实现，生产环境推荐直接使用它而不是自己实现。

常见陷阱

Proxy 后 RemoteAddr 不正确：要读可信代理传来的 X-Forwarded-For 或 X-Real-IP，不要无条件信任客户端请求头。
限流 map 无限增长：长期运行的服务必须清理不活跃的 IP bucket，否则内存泄露。
测试里用 sleep 验证限流：时间相关测试容易在 CI 上抖动。用 clock 注入或只测 burst 行为更稳。

对比表

限流维度	实现难度	精度	适用场景
全局	低	高	保护整个服务
按 IP	中	中	公开 API
按用户	中	高	需要登录的接口
按 API Key	中	高	第三方接入

小结

限流的基本目标是保护系统边界。令牌桶通过”固定速度补充令牌、请求消耗令牌”来同时支持平均速率和短暂突发。Go 里可以把它封装成 HTTP 中间件，再根据需要做全局限流、按 IP 限流或按用户限流。

实际落地时要注意代理 IP、状态清理、429 响应和测试稳定性。限流不是越严格越好，而是要匹配业务容量和用户体验。关键接口先保护，再逐步扩展覆盖范围。生产环境推荐使用 golang.org/x/time/rate 而不是自己的实现。 debug 模式下保留限流日志，帮助排查误限流和不合理流量。

真实项目用例

在实际团队协作中，下面是几个推荐的工作流：

代码审查清单

函数是否处理了所有 error 返回值
并发代码是否有明确的退出路径和 WaitGroup
用户输入是否经过校验和清洗
敏感配置是否通过环境变量或加密存储注入
测试是否覆盖了正常路径和至少一个错误路径
日志是否包含足够的上下文信息但不泄露敏感数据
接口设计是否符合最小接口原则

CI/CD 集成建议

每次提交前运行 go fmt ./...
CI 中运行 go vet ./... 和 golangci-lint run
单元测试使用 go test -race ./... 检测数据竞争
关键路径的 benchmark 加入回归测试
使用 go mod verify 确保依赖完整性

性能调优检查点

使用 pprof 分析 CPU 和内存使用
关注 benchmark 的 allocs/op，减少高频路径的堆分配
检查数据库查询是否使用索引
确认外部 HTTP 调用有合理的超时设置
缓存热点数据，但注意缓存一致性和过期策略

面试高频考点

如果你正在准备 Go 相关面试，以下概念是高频考点：

goroutine 和线程的区别
channel 的缓冲和非缓冲用法
defer 的执行顺序和与返回值的关系
map 的并发不安全性和解决方案
interface 的隐式实现和类型断言
slice 的底层数组和 append 机制
GC 的基本原理和调优参数
context 的使用场景和超时控制
error 的包装和 errors.Is/errors.As
sync.Mutex vs sync.RWMutex vs atomic

掌握这些概念意味着你具备了独立开发 Go 服务的基础能力。继续在实际项目中磨练，你会越来越熟悉 Go 的工程风格和最佳实践。

常见问题（FAQ）

Q: 这个特性在实际项目中真的有用吗？
A: 是的。本文介绍的技术来源于真实后端开发场景。无论是标准库工具还是工程实践，在日常服务开发中都会反复用到。

Q: Go 版本会影响示例代码吗？
A: 本文代码主要针对 Go 1.20+ 编写。较新版本（如 1.22、1.23）的语法可能有微调，但核心概念保持不变。如有版本差异，文中会特别说明。

Q: 学习 Go 应该先学标准库还是直接上框架？
A: 强烈建议先学标准库。框架是对标准库的封装和扩展。只有理解了标准库的能力边界，才能正确选择和使用框架，也才能在框架出问题时快速定位。

Q: 代码里的错误处理为什么都是显式的 if err != nil？
A: 这是 Go 的设计哲学。显式错误处理让失败路径清晰可见，不会隐藏在任何 try-catch 之后。习惯了之后，你会发现这种写法实际上降低了排查错误的难度。

Q: 并发相关代码怎么测试？
A: 使用 Go 内置的 -race 标志检测数据竞争：go test -race ./...。结合 sync.WaitGroup 和 context.WithTimeout 编写有退出路径的并发测试，避免 goroutine 泄漏。

常见坑与避坑指南

不要信任用户输入：无论表单、JSON、Cookie 还是 HTTP Header，都当作不可信数据处理，做校验和转义。
资源要释放：文件、数据库连接、HTTP 响应体都要及时关闭。defer 是一个好习惯。
不要忽略错误：即使 defer file.Close() 可能返回错误，至少记录日志。完全忽略错误是 bug 的温床。
不要滥用 goroutine：每个 goroutine 都要有明确的退出路径。使用 sync.WaitGroup 和 context 管理生命周期。
不要硬编码配置：端口、路径、超时时间、密钥都应该从配置读取，让程序适应不同环境。
不要过早优化：先让代码正确和可读，再用 benchmark 和 profile 找到真正的热点。

延伸阅读与实践建议

读完本文后，建议完成以下实践：

把文中所有示例代码在自己的机器上跑一遍
给示例代码补充错误分支的测试用例
尝试基于本文内容构建一个小型完整项目
在 review 他人的 Go 代码时，检查本文提到的边界是否被覆盖
订阅 Go 官方博客，关注语言演进和最佳实践更新

参考资源

Go 官方网站：https://go.dev/
Go 标准库文档：https://pkg.go.dev/std
Go by Example：https://gobyexample.com/
Effective Go：https://go.dev/doc/effective_go
Go 常见问题：https://go.dev/doc/faq
Go 项目实战社区案例和开源项目源码

本文力求在讲解技术细节的同时兼顾工程实用性。Go 语言的设计简洁但不简单，掌握它需要持续的实践和反思。希望这篇文章能成为你学习道路上的一个可靠参考。

生产级限流中间件

真实项目的限流中间件通常需要更多能力：

type RateLimiter struct {
    mu      sync.Mutex
    rate    float64
    burst   int
    buckets map[string]*TokenBucket
    
    // 监控
    limitedTotal int64
    allowedTotal int64
}

func (l *RateLimiter) Allow(key string) bool {
    l.mu.Lock()
    b, ok := l.buckets[key]
    if !ok {
        b = NewTokenBucket(l.rate, l.burst)
        l.buckets[key] = b
    }
    l.mu.Unlock()
    
    if !b.Allow() {
        atomic.AddInt64(&l.limitedTotal, 1)
        return false
    }
    atomic.AddInt64(&l.allowedTotal, 1)
    return true
}

func (l *RateLimiter) Stats() (allowed, limited int64) {
    return atomic.LoadInt64(&l.allowedTotal), atomic.LoadInt64(&l.limitedTotal)
}

这个设计增加了基本指标，可以判断限流是否在正常生效。

Go 官方扩展库 rate

推荐使用 golang.org/x/time/rate：

import "golang.org/x/time/rate"

limiter := rate.NewLimiter(rate.Every(time.Second/5), 10)

func handler(w http.ResponseWriter, r *http.Request) {
    if !limiter.Allow() {
        http.Error(w, "too many requests", http.StatusTooManyRequests)
        return
    }
    // 处理请求
}

它的优点是经过了更充分的测试，API 更成熟，处理了边界时序问题。

限流与熔断的配合

限流控制的是入口流量，熔断控制的是下游依赖。两者可以配合使用：

// 限流 -> 业务处理 -> 熔断保护 -> 外部调用

限流防止系统被外部流量超载，熔断防止下游故障拖垮当前系统。两者解决的问题不同，不要混用。

分布式限流

单机限流无法处理多实例协作。分布式限流可以将计数放到 Redis 中：

// 用 Redis 的 INCR + EXPIRE 实现滑动窗口
func DistributedRateLimit(ctx context.Context, key string, limit int, window time.Duration) bool {
    pipe := redis.Client.Pipeline()
    incr := pipe.Incr(ctx, key)
    pipe.Expire(ctx, key, window)
    _, _ = pipe.Exec(ctx)
    return incr.Val() <= int64(limit)
}

分布式限流有网络开销，精度低于单机限流。通常只对需要全局限流的场景（如全局 API Key）使用分布式限流，单机限流仍然保留作为本地保护。

综合建议

任何公开接口都应该有限流保护。
限流阈值 start 后可以宽松，逐步收紧到合理值。
429 响应中带上 Retry-After 头，让客户端知道何时重试。
监控限流率和通过率，发现异常流量模式时调整策略。

限流是系统自我保护的第一扇门，打开它后才能从容处理后续的挑战。

限流在 API 网关中的角色

在企业架构中，限流通常由 API 网关（如 Kong、Nginx、Envoy）统一管理，应用层不需要自己实现。但理解令牌桶原理仍然很重要，因为：应用层可能需要做更细粒度的限流（如按用户 ID 或业务类型），而这些信息网关不一定能获取；网关限流和应用限流可以分层防护，网关限流阻止大流量冲击，应用限流保护内部资源；当没有 API 网关时（如内部服务直连），应用层就需要自己实现限流。无论哪一层做限流，都要遵循一致的策略和阈值管理，避免互相冲突。应用层限流应该尽量简单，把复杂流控交给专门的基础设施。

继续阅读

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章返回首页