Go 服务怎么按租户限流？x/time/rate、429 和多实例边界这样拆

报表接口上线后，某个租户把批量查询接进了定时任务。单看 CPU 还没满，其他租户却开始拿到 429。问题不在“服务够不够大”，而在请求预算没有分层：一个人把共享入口挤满了，后面的正常流量没有自己的通道。

做租户限流不用一开始就上分布式组件，先把三层预算边界拆清楚，单实例用 x/time/rate 就能先搞定大部分公平性问题，多副本场景再根据业务精度要求选择网关层、共享存储等方案，就能拿到可解释、可落地的 429 保护机制。

先拆预算，再决定 limiter 放在哪里

最容易写出的限流只有一层：所有请求共用一个 rate.Limiter。它能保护进程，却会把“单个租户的异常峰值”变成“所有租户一起被拒绝”。更实用的做法是先明确每一层要保护谁。

这套拆法不是为了多建几张表，而是为了让告警能回答一个具体问题：是整台服务忙、某个租户突发，还是某条导出路由本身太贵。原因不同，后面的处理也不同。

单实例先用租户桶把公平性落到中间件

rate.Limiter 是令牌桶。Limit 表示平均补充速度，burst 是一次可消耗的最大令牌数。对于超过预算就直接拒绝的 HTTP 入口，Allow 比等待更合适：它不会把大量 goroutine 堆在等待队列里。

package main

import (
    "net/http"
    "sync"
    "time"

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

type tenantEntry struct {
    limiter *rate.Limiter
    seenAt  time.Time
}

type tenantLimiterPool struct {
    mu    sync.Mutex
    items map[string]*tenantEntry
    rps   rate.Limit
    burst int
}

func (p *tenantLimiterPool) allow(tenantID string) bool {
    p.mu.Lock()
    defer p.mu.Unlock()

    entry := p.items[tenantID]
    if entry == nil {
        entry = &tenantEntry{
            limiter: rate.NewLimiter(p.rps, p.burst),
        }
        p.items[tenantID] = entry
    }
    entry.seenAt = time.Now()
    return entry.limiter.Allow()
}

func tenantFrom(r *http.Request) string {
    if id := r.Header.Get("X-Tenant-ID"); id != "" {
        return id
    }
    return "anonymous"
}

func tenantRateGuard(next http.Handler, pool *tenantLimiterPool) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if !pool.allow(tenantFrom(r)) {
            w.Header().Set("Retry-After", "1")
            http.Error(w, "too many requests", http.StatusTooManyRequests)
            return
        }
        next.ServeHTTP(w, r)
    })
}

例如把 rps 设为 10、burst 设为 20，含义不是“每秒只能来 10 个请求”。刚创建的桶允许一小段突发，之后才回到每秒平均 10 个的节奏。这个突发值要看路由：读缓存的详情页可以稍高，触发大查询或文件生成的路由通常应单独设低一点。

别让租户 ID 变成无限增长的 map

上面的代码只展示判断路径，生产中还需要清理长时间未访问的 tenantEntry。如果请求里能出现任意值，map 会慢慢积累。常见做法是定期按 seenAt 删除过期条目，并对 tenant ID 的来源做认证和格式约束；匿名流量则共享一个更小的桶。

副本一多，内存桶就只剩“本机公平”

一开始两个 Pod 的流量大致均分时，本机桶看起来没问题。负载均衡一旦把同一租户更多请求送到某个 Pod，或者实例数量扩缩容，本机桶就不能代表租户的总预算。此时要先决定目标是“尽量平滑”还是“严格统一”。

这里别急着把所有接口都改成共享限流。高频、低成本的读接口，实例内桶加全局保护往往已经够用；真正需要严格统一的，通常是付费配额、导出任务、短信发送、第三方 API 调用这类有明确成本或额度的动作。

路由成本不一样，预算也别一样

把 GET /orders、POST /exports 和文件上传共用一个租户桶，常常会让便宜请求替昂贵请求买单。一个实用的起点是：普通查询消耗 1 个令牌，导出前置检查消耗更多令牌，真正的大任务转到异步队列，并在创建任务时扣一次预算。

如果业务确实需要等待，而不是立刻拒绝，可以使用 Wait 并给请求设置很短的超时。官方文档说明，等待时间超过 context deadline、请求的令牌数超过 burst，或 context 被取消时，WaitN 会返回错误。HTTP 入口不要无上限等待，否则限流很容易变成排队放大器。

上线前用四个信号校准数字

1. 按租户记录允许数、429 数和高成本路由占比，先找到真正抢资源的对象。
2. 把下游连接池、数据库慢查询和队列积压放在同一张观测图里，别只看 429。
3. 对新规则先灰度一个租户或一条路由，观察正常高峰会不会被误伤。
4. 为共享限流的存储故障预先写好降级策略：保护下游优先，还是尽量放行优先，必须由业务成本决定。

多租户限流真正难的不是调用一次 Allow，而是把“谁的预算”“哪条路由更贵”“多副本时谁说了算”说清楚。边界拆清后，429 才是可解释的保护动作，而不是用户眼里随机出现的故障。

相关问题

burst 设得比每秒限额大，会不会绕过限流？

不会绕过平均速率，但会允许短时间突发。它适合吸收正常抖动；如果下游不能承受瞬时峰值，就应把 burst 设小，或给高成本路由单独建桶。

为什么不直接用 Wait 等到有令牌？

HTTP 请求等待会占用连接和 goroutine。对用户入口，短而明确的 429 通常更可控；等待更适合内部任务，并且必须受 context deadline 约束。

多实例共享限流一定要用 Redis 吗？

不一定。入口集中时可以由网关处理；只有确实需要跨实例统一额度时，才考虑共享存储或专门的配额服务。

按 IP 限流能代替按租户限流吗？

不能完全代替。企业网络可能多人共用出口 IP，同一租户也可能从多个 IP 访问。IP 更适合防护匿名流量或异常来源，租户身份仍应是业务公平性的主键。