研发接口限流要解决的是开放接口被过量调用时如何保护后端资源，同时让正常调用方不受影响。设计时先明确保护对象和配额口径，再选择算法与执行位置，约定超限响应和重试规则，落实角色分工，最后通过监控告警和灰度上线验证效果。本文按“清单—算法—响应—分工—验证”的顺序给出可执行步骤和交付物。
要点总览（TL;DR）
- 限流设计先产出“接口—调用方—配额”清单：按读写、同步异步、内外部划分保护等级，按 QPS、并发数、日调用量或加权配额确定口径。
- 执行位置推荐网关统一限流加服务内单机限流双层控制；读接口多用令牌桶保留突发弹性，写接口和资源紧张的下游用漏桶或滑动窗口控制更严。
- 超限统一返回 429 并携带 Retry-After，调用方按指数退避加随机抖动重试，非幂等写接口需在接口文档中标注不可重试。
- 上线前先跑观察模式核对配额，再小比例拦截、最后全量；核心接口拒绝率异常升高或主要调用方业务中断时，值班人员可直接关闭规则回滚。
- 配额清单、规则变更和上线检查项可作为工作项统一跟踪，让限流调整与接口版本发布保持同一节奏。
先定限流对象：接口清单、调用方与配额口径
限流设计的第一步是回答“保护什么、限制谁”。没有接口清单和调用方清单，配额只能凭感觉设定，上线后容易出现该拦的没拦住、正常调用被误伤。这一步的产出是一张“接口—调用方—配额”三列清单，作为后续算法选型和规则配置的输入。
按接口分组划分保护等级
把对外接口按业务特征分组，为每组设定不同的保护等级。常用分组维度包括：
- 读接口与写接口：写接口通常涉及数据变更和事务，资源成本更高，配额应更保守。
- 同步接口与异步接口：同步接口占用连接和线程，超时影响面大；异步接口可排队缓冲，限流阈值可以放宽。
- 内部接口与外部接口：外部合作方调用不可控因素多，需要独立配额和更严格的默认上限。
分组完成后，为每组标注保护等级（如核心、重要、一般），保护等级决定后续配额的松紧和告警的敏感度。
识别调用方身份
配额要落到具体调用方才有约束力。常见身份维度包括应用（AppKey）、团队、个人令牌和第三方合作方。需要确认每种身份在网关或鉴权层是否可识别，识别不到的调用方只能按 IP 或接口维度做兜底限制。调用方清单应记录身份标识、所属团队、联系人和调用用途，便于配额审批和超限时沟通。
确定配额口径
配额口径决定限流规则怎么写，常见口径及适用场景如下：
| 配额口径 | 含义 | 适用场景 |
|---|---|---|
| QPS | 每秒请求数上限 | 大多数同步接口的默认口径，直观易沟通 |
| 并发数 | 同时处理的请求数上限 | 长耗时接口、占用连接池资源的接口 |
| 日调用量 | 按天累计的调用总量 | 合作方合同约定、批量数据同步类接口 |
| 加权配额 | 按单次调用资源成本折算的配额单位 | 同一接口存在轻量查询与重量查询混合的情况 |
同一接口可以组合多个口径，例如同时限制 QPS 和日调用量。加权配额需要接口提供方为每个接口标注成本系数，成本系数可依据数据库查询量、下游调用次数或历史响应耗时估算。
产出：接口与调用方配额清单
清单模板建议包含以下列，每行对应一个“接口—调用方”组合：
| 接口路径 | 接口分组 | 保护等级 | 调用方 | 身份标识 | 配额口径 | 配额值 | 备注 |
|---|---|---|---|---|---|---|---|
| /api/v1/orders | 写/同步/外部 | 核心 | 合作方A | AppKey-A | QPS + 日调用量 | 50 QPS / 20万次 | 演示数据 |
| /api/v1/reports | 读/同步/内部 | 重要 | 数据团队 | Token-D | 并发数 | 20 | 演示数据 |
清单完成后组织接口提供方和主要调用方评审一次，确认配额值有流量基线支撑，避免拍脑袋定数。
选择限流算法与执行位置
算法决定“怎么计数和判断超限”，执行位置决定“在哪里拦截”。两者要一起考虑：网关层适合做统一入口控制，服务内单机限流适合保护具体资源，分布式场景还需要共享计数存储。
常见算法的适用差异
| 算法 | 特点 | 适用场景 | 注意事项 |
|---|---|---|---|
| 固定窗口 | 按时间窗口计数，实现简单 | 对突发流量不敏感的粗粒度限制 | 窗口边界可能出现两倍流量突刺 |
| 滑动窗口 | 按更细粒度滚动统计，平滑边界 | 需要较精确控制平均速率的接口 | 存储和计算开销高于固定窗口 |
| 令牌桶 | 按固定速率发放令牌，允许一定突发 | 大多数开放接口的默认选择 | 桶容量决定可容忍的突发量，需与调用方沟通 |
| 漏桶 | 请求按固定速率流出，削峰填谷 | 下游处理能力稳定、需要严格匀速的场景 | 突发请求会被排队或丢弃，延迟增加 |
选择时先看接口是否需要容忍突发：读接口和查询类接口通常用令牌桶保留一定弹性；写接口和下游资源紧张的接口可用漏桶或滑动窗口控制得更严格。
网关统一限流与服务内单机限流的组合
推荐双层控制：网关层按调用方和接口分组做统一限流，负责对外承诺的配额；服务内做单机限流，保护本实例的线程池、连接池和下游依赖。两层阈值要协调，网关阈值应小于等于服务集群总承载能力，单机阈值按实例数分摊并留出余量。只做网关限流时，绕过网关的内部调用不受约束；只做单机限流时，无法按调用方区分配额。
分布式场景下的计数存储与一致性
多实例部署时，按调用方维度的配额需要共享计数。常见做法是用 Redis 等集中存储配合原子操作或 Lua 脚本实现令牌桶或滑动窗口计数。需要评估：计数存储的延迟是否可接受、存储故障时是放行还是拒绝（通常选择放行并告警，避免限流组件本身成为故障点）、计数精度要求是否允许最终一致。对精度要求不高的场景，也可以采用“本地预分配额度、定期同步”的方式减少集中存储压力。
按接口成本加权时的实现注意点
加权配额要求每次调用先确定成本系数再扣减。实现时注意：成本系数应配置化而非硬编码，便于调整；同一接口不同参数可能导致成本差异较大时，按参数区间分档；扣减失败或成本未知时按默认系数处理并记录日志，避免计数失真。
超限响应与重试约定
限流生效后，调用方需要清楚知道“被限了、什么时候可以再试”。响应格式和重试规则要在上线前与调用方书面约定，否则容易出现调用方疯狂重试、把限流变成雪崩的情况。
HTTP 429 与业务错误码约定
对外 HTTP 接口超限时返回 429 Too Many Requests，响应体包含统一结构：错误码、错误信息、当前配额、建议重试时间。内部 RPC 接口可定义对应的业务错误码，并在错误信息中注明限流维度（调用方级、接口级或全局级）。错误码应纳入接口文档和 SDK 统一处理，避免每个调用方各自解析。
Retry-After 与退避策略
429 响应携带 Retry-After 头，给出建议等待秒数。调用方重试遵循指数退避加随机抖动，例如首次等待 1 秒，之后每次翻倍并加入随机偏移，设置最大重试次数。批量任务类调用方在收到 429 后应暂停当前批次，按 Retry-After 等待后再继续，避免并发重试放大压力。
区分可重试与不可重试的接口
幂等查询接口超限后可安全重试；写接口重试前需确认幂等性，非幂等写接口超限后应返回明确失败，由调用方决定是否人工补偿。接口清单中为每个接口标注“超限可重试/不可重试”，并写入接口文档。
调用方侧的熔断与降级配合
调用方连续收到 429 或超时后，应触发熔断，暂停对该接口的调用一段时间，期间走降级逻辑（返回缓存数据、跳过非关键调用或提示稍后重试）。熔断阈值和恢复策略由调用方团队设定，平台方在接入文档中给出推荐值。
角色分工与交付物
限流机制涉及平台、接口提供方、调用方和运维多方，职责不清会出现规则没人配、配额没人审、告警没人处理的情况。下表明确各角色的职责和交付物。
| 角色 | 职责 | 交付物 |
|---|---|---|
| 平台/网关负责人 | 提供限流规则配置能力，审核并配置配额规则，维护网关层限流组件 | 限流规则配置记录、网关限流组件说明 |
| 接口提供方 | 完成接口分组与保护等级标注，标注接口成本系数，评审配额合理性 | 接口分级清单、成本系数表 |
| 调用方团队 | 提交配额申请，实现重试、退避和熔断逻辑，反馈误伤情况 | 配额申请单、调用方重试实现说明 |
| 运维/SRE | 配置监控指标与告警规则，评估容量基线，执行灰度与回滚操作 | 监控看板、告警规则、灰度与回滚预案 |
配额申请和规则变更建议走工单流程，保留审批记录，便于事后追溯某次限流调整的原因。限流规则、配额申请单和上线检查项可以作为工作项纳入研发管理平台统一跟踪，让规则变更与接口版本发布保持同一节奏。ONES 可用于承载这类工作项的流转与状态跟踪，具体配置方式以团队现有流程为准。
监控、告警与灰度上线
限流规则配置完成不等于生效正确。上线前后要通过指标观察限流是否按预期拦截、是否误伤正常调用，并用灰度方式逐步放开拦截范围。
关键指标
- 超限次数：按接口、调用方、限流维度分别统计，判断拦截是否集中在少数调用方。
- 拒绝率：超限次数占该接口总调用量的比例，拒绝率突然升高通常意味着配额偏紧或调用方行为变化。
- P99 延迟：观察限流组件本身是否引入额外延迟，以及限流后后端延迟是否改善。
- 配额使用率：各调用方实际用量与配额之比，用于后续配额调整。
告警阈值与通知对象
告警分两类：一类是限流组件异常（计数存储不可用、规则加载失败），通知平台和运维；另一类是业务侧异常（某调用方拒绝率持续超过设定比例、核心接口整体拒绝率突增），通知接口提供方和对应调用方。阈值结合流量基线设定，例如核心接口拒绝率连续 5 分钟超过 5% 触发告警，具体数值以实际基线为准。
灰度顺序
- 观察模式：规则只记录不拦截，对比“如果拦截会拒绝多少请求”，核对配额是否合理。
- 小比例拦截：对部分调用方或部分实例开启拦截，观察拒绝率和调用方反馈。
- 全量拦截：确认无异常后全量生效，持续观察一周再进入常规运维。
回滚条件与操作
出现核心接口拒绝率异常升高、主要调用方业务中断或限流组件故障时触发回滚。回滚操作应预先演练：关闭对应规则或切换为观察模式，确认流量恢复，记录回滚原因和时间。回滚开关要由值班人员可直接操作，不依赖发布流程。
示例：一个开放接口的限流配置过程
以下示例为演示场景，数值仅用于说明流程，不代表任何产品的默认配置。
示例接口与调用方设定
某研发平台开放“查询构建记录”接口 /open/api/v1/builds，属于读、同步、外部接口，保护等级为核心。调用方为合作方 A（AppKey-A）和内部报表系统（Token-R）。历史峰值显示合作方 A 单实例峰值约 80 QPS，报表系统批量拉取时约 30 QPS。
配额与算法选择理由
合作方 A 配额设为 100 QPS，报表系统设为 50 QPS，均采用令牌桶，桶容量取配额的 20%，允许短时突发。选择令牌桶是因为查询接口可容忍小幅突发，且实现成熟。执行位置为网关层按 AppKey 限流，服务内按实例设置 40 QPS 单机限流兜底。计数存储使用集中缓存，故障时放行并告警。
超限响应示例
超限时返回 429，响应体包含错误码 RATE_LIMITED、当前配额和建议重试时间，Retry-After 设为 1 秒。接口文档标注该接口超限可重试，调用方按指数退避重试，最多 3 次。
上线后指标观察与调整
观察模式运行三天，合作方 A 的模拟拒绝率约 0.3%，集中在每日上午批量任务时段。与合作方沟通后确认其批量任务可错峰，配额维持 100 QPS 不变，同时建议其批量任务改为串行拉取。灰度拦截一周后拒绝率降至 0.1% 以下，P99 延迟未因限流组件上升，规则转入常规运维，配额使用率纳入月度容量评估。
完成检查：限流机制是否可交付
上线前逐项核对以下清单，全部满足才进入灰度拦截阶段。
| 检查项 | 通过标准 | 确认人 |
|---|---|---|
| 配额清单覆盖范围 | 全部对外接口均有分组、保护等级和配额记录，主要调用方均已登记 | 接口提供方 |
| 算法与执行位置记录 | 每个接口组注明所用算法、执行层（网关/服务内）和阈值依据 | 平台负责人 |
| 超限响应与重试规范 | 错误码、Retry-After、可重试标注已写入接口文档并通知调用方 | 接口提供方、调用方 |
| 监控告警配置与演练 | 关键指标看板可用，告警规则已配置并做过一次模拟触发验证 | 运维/SRE |
| 灰度与回滚方案 | 观察模式已运行并核对数据，回滚开关可操作且已演练 | 运维/SRE、平台负责人 |
清单通过后按灰度顺序推进，上线后一周内复盘拒绝率、配额使用率和调用方反馈，形成配额调整记录，作为下一轮容量评估的输入。
常见问题
配额值应该按历史峰值定，还是留出增长余量？
建议以历史流量基线为起点，再按业务增长预期留出余量，两者都要有记录。具体做法是取近 30 天同一时段的 P95 调用量作为基线，结合调用方已报备的扩容计划上浮一定比例，并在清单备注中写明依据。配额定得过紧会在业务高峰误伤正常调用，定得过松则起不到保护作用。上线后通过配额使用率指标持续校准，把调整记录纳入月度容量评估。
计数存储故障时，限流组件应该放行还是拒绝请求？
多数场景选择放行并立即告警。限流组件本身是保护手段，如果它故障时改为拒绝全部请求，会把局部故障放大成整体不可用。放行期间后端可能承受超出配额的流量，因此需要配套告警通知平台和运维尽快恢复计数存储，并评估后端是否具备短时超额承载能力。对资源极其紧张、宁可拒绝也不能过载的接口，可以单独配置为拒绝策略，但要在接口文档中说明这一行为。
内部服务之间的调用也需要按调用方限流吗？
需要，但口径可以简化。内部调用通常能识别服务身份，可以按服务名配置配额，重点保护被多个上游依赖的公共接口。只做网关限流时，绕过网关的服务间直连不受约束，因此服务内单机限流要作为兜底保留。内部调用的超限响应可以走 RPC 错误码而非 HTTP 429，但同样要约定重试规则，避免上游服务无节制重试。
灰度观察模式要运行多久才能进入拦截阶段？
没有统一时长，判断标准是观察数据是否覆盖了主要流量形态。至少覆盖一个完整业务周期，包括日常高峰和批量任务时段；如果业务有明显周期性（如月末结算），应覆盖到对应节点。观察期内要核对“如果拦截会拒绝多少请求”，确认拒绝集中在可沟通的调用方，且没有核心调用方被大面积拦截，再进入小比例拦截。
限流规则变更后，怎么通知调用方并避免接口文档与实现不一致？
把规则变更纳入工单流程，变更单中记录接口、调用方、原配额、新配额和生效时间，审批通过后同步更新接口文档和 SDK 中的错误码说明。对受影响的调用方提前发出通知，给出调整窗口。上线检查清单中增加一项“文档与规则一致性核对”，由接口提供方确认后再放开拦截。规则变更与接口版本发布保持同一节奏，可以减少调用方在不知情的情况下触发超限。
