---

title: API安全与速率限制（Rate Limiting）实现指南与最佳实践

keywords:

• API安全
• 限流
• 令牌桶
• 漏桶
• 节流
• DoS防护
• IP黑白名单
• JWT作用域

description: 从鉴权到限流的全链路API安全实践，结合令牌桶/漏桶算法、作用域控制与黑白名单策略，给出高可用与低误杀的实现方案。

categories:

• 文章资讯
• 技术教程

---

API安全与速率限制（Rate Limiting）实现指南与最佳实践

概述

API安全需要同时关注身份鉴别、权限控制与流量治理。合理的限流与资源配额可在高并发与攻击场景下保持服务稳定与公平使用。

身份与作用域

• 使用JWT携带 sub、scope 与过期时间
• 细粒度作用域限制到资源与动作
• 后端按 scope 决定速率配额与并发阈值

令牌桶限流

class TokenBucket {
  capacity: number
  tokens: number
  refillRate: number
  lastRefill: number

  constructor(capacity: number, refillPerSec: number) {
    this.capacity = capacity
    this.tokens = capacity
    this.refillRate = refillPerSec
    this.lastRefill = Date.now()
  }

  allow(cost = 1): boolean {
    const now = Date.now()
    const delta = (now - this.lastRefill) / 1000
    this.tokens = Math.min(this.capacity, this.tokens + delta * this.refillRate)
    this.lastRefill = now
    if (this.tokens >= cost) {
      this.tokens -= cost
      return true
    }
    return false
  }
}

漏桶整形

class LeakyBucket {
  capacity: number
  queue: number
  leakRate: number
  lastLeak: number

  constructor(capacity: number, leakPerSec: number) {
    this.capacity = capacity
    this.queue = 0
    this.leakRate = leakPerSec
    this.lastLeak = Date.now()
  }

  enqueue(size = 1): boolean {
    this.leak()
    if (this.queue + size > this.capacity) return false
    this.queue += size
    return true
  }

  leak(): void {
    const now = Date.now()
    const delta = (now - this.lastLeak) / 1000
    const leaked = Math.floor(delta * this.leakRate)
    this.queue = Math.max(0, this.queue - leaked)
    this.lastLeak = now
  }
}

组合策略

• 对匿名/IP维度使用令牌桶作为基线
• 对认证用户按 scope 叠加配额与优先级
• 高危接口使用漏桶整形避免瞬时峰值压垮后端
• 黑白名单与地理/ASN画像提升阻断效率

返回格式

{
  "error": "rate_limited",
  "retry_after": 2.5,
  "limit": 120,
  "remaining": 0,
  "scope": "orders:write"
}

运维与监控

• 指标：拒绝率、平均等待时长、配额使用率、误杀率
• 预案：当攻击态势上升时下调匿名配额、上调灰度挑战
• 审计：记录被限流的主体、接口、来源与时间窗口

通过分层限流与作用域治理，可在复杂流量环境下实现稳定与公平的API服务。