研发管理平台的接口限流，是在开放接口入口按预设速率或并发上限拦截超额请求的控制机制，作用是保护平台服务稳定、约束单个调用方的资源占用，让超额请求以可预期的方式被拒绝或排队。它的边界止于“请求进入速率”这一层：配额管理、熔断、降级、鉴权与权限校验、业务校验、审计与计费都不属于限流本身，只是常与限流配合使用。下面按定义、边界、机制、相邻概念和示例逐层说明。
要点总览（TL;DR）
- 研发管理平台接口限流是在开放接口入口按预设速率或并发上限拦截超额请求的机制，约束的是请求进入节奏，先于业务处理生效。
- 限流能处理突发流量冲击、单调用方挤占资源和后端过载；对单次请求过重、慢查询、数据错误、权限越权无能为力。
- 配额按周期累计用量限制，熔断依据下游依赖健康状态快速失败，降级调整功能范围，三者都不属于限流。
- 鉴权与权限校验、参数校验、审计日志、计费统计与限流常在同一请求链路上执行，但判断依据和失败响应各不相同。
- 判断现象时先看请求速率是否触顶，再看周期用量是否用尽，然后看依赖健康状态，最后回到单次请求的耗时与数据正确性。
限流在研发管理平台里到底管什么
限流管的是“请求进入的节奏”。研发管理平台对外开放工作项、迭代、需求、缺陷、用户等接口后，外部集成应用、脚本、自动化流水线都会调用这些接口。平台在请求到达业务处理逻辑之前，先判断当前调用方在单位时间内发出了多少请求、同时有多少请求在处理中，超过预设上限的部分就不再进入业务层。它约束的是调用行为，不改变业务结果。
从作用对象看，限流通常落在三个层面：一是调用方，按应用、凭证或租户识别身份后分别计数；二是接口，按单个接口或接口分组设置不同上限，读接口和写接口往往区别对待；三是来源，按IP或网关入口做粗粒度控制。同一套平台可以同时启用多个维度，最终以最先触发的那个为准。
直接效果有三种：拒绝，返回限流状态码并提示稍后重试；排队，请求进入等待队列，在容量允许时再处理；延迟，通过匀速放行拉长请求的处理节奏。三种方式都在保护后端资源，避免数据库连接、线程池、消息队列被瞬时流量占满，进而影响平台内其他正常使用的团队。
需要强调的是，限流发生在请求入口，先于业务处理。请求被限流拦截时，平台还没有解析请求体、没有校验参数、没有查询数据，因此限流判断不依赖请求内容，也不关心这次调用想做什么业务操作。
作用边界：限流能解决和不能解决的问题
限流能解决的问题集中在“量”的层面。突发流量冲击是典型场景：某个集成应用在整点触发批量同步，短时间内发出数千次请求，限流可以把这股流量削平，让后端按可承受的节奏处理。单个调用方挤占资源也是限流的目标：一个配置不当的脚本高频轮询，会拖慢其他团队的页面加载，按调用方分别限流可以把影响限制在它自己的配额内。后端过载防护同样属于限流职责，当整体请求量接近系统容量时，入口拦截比事后扩容更快见效。
限流解决不了的问题同样明确。单次请求本身过重，比如一次查询拉取全量工作项并附带多层关联数据，请求数量只有一条，限流不会拦截，慢在查询和序列化上。慢查询、缺少索引、大事务这类数据库层面的问题，需要从SQL和数据模型入手。数据错误，比如字段映射错位、状态流转不符合业务规则，属于业务校验范畴，限流对内容一无所知。权限越权，比如某个凭证调用了它无权访问的项目接口，属于鉴权和数据权限控制，限流只看到请求次数，看不到调用者有没有资格。
边界判断的依据可以归纳为一句话：限流只看请求量与速率，不看请求内容与业务语义。凡是需要理解“这次请求要做什么”“这个调用方有没有权限”“这条数据对不对”的问题，都超出限流的能力范围。反过来，凡是与“单位时间进来多少请求”相关的问题，才是限流该管的。
阈值设置本身也影响边界效果。阈值定得过低，正常的集成同步、批量导入会被误伤，表现为集成任务频繁失败、重试次数上升；阈值定得过高，限流形同虚设，起不到保护作用。合理做法是结合调用方的实际业务节奏、接口的响应耗时和后端容量，分接口、分调用方设置差异化上限，并保留调整通道。
限流的组成与运行机制
一套可用的限流策略由维度、算法、触发响应和配置入口四部分组成。维度决定“按什么计数”，算法决定“怎么判断超额”，响应决定“超额之后发生什么”，配置入口决定“谁来调整、调整后多久生效”。
常见限流维度包括：按应用或凭证，适合区分不同集成方的资源占用；按接口或接口分组，适合保护高成本接口；按IP，适合网关层的粗粒度防护；按时间窗口，适合把突发流量摊平到更长周期。多个维度可以叠加，例如某应用调用工作项查询接口，同时受该应用的总量上限和该接口的单接口上限约束。
算法思路上，固定窗口把时间切成等长区间分别计数，实现简单，但窗口交界处可能出现两倍流量的突刺；滑动窗口按更细的时间粒度统计，突刺更小，实现成本略高；令牌桶按固定速率发放令牌，允许一定程度的突发；漏桶以恒定速率放行，输出最平滑；并发数限制则不看单位时间请求量，而是控制在处理中的请求数量，适合保护耗时较长的接口。
触发后的响应方式需要提前约定。常见做法是返回专门的限流状态码，并在响应头中给出重试等待时间，让调用方按提示退避；对内部集成也可以采用排队等待，但排队会占用连接资源，队列长度需要设上限。调用方侧应实现指数退避重试，避免被限流后立即重试造成二次冲击。
配置与调整入口通常放在开放平台的接口管理或应用管理页面，由平台管理员按应用分配调用凭证并设置速率上限。策略调整后需要关注生效范围和生效时间，避免出现配置已改、调用方仍按旧节奏请求的情况。在研发管理平台的扩展开发场景中，ONES 提供丰富多样的 API 接口，可快速集成 ONES 与企业系统，实现数据打通；当企业把内部审批、代码托管、消息通知等系统接入时，调用方识别、凭证分配和接口分组就是设置限流策略前需要先理清的管理动作。具体限流维度、阈值与超额响应方式，以平台接口文档的实际说明为准。
哪些情况不属于限流：与配额、熔断、降级的区别
限流常与配额、熔断、降级一起出现，四者关注的对象和触发条件不同。把它们混为一谈，会导致排查方向错误：明明是月度调用总量用完，却去检查瞬时速率；明明是下游依赖故障，却去调整限流阈值。
| 控制手段 | 控制对象 | 触发条件 | 作用时机 | 典型响应方式 |
|---|---|---|---|---|
| 限流 | 单位时间内的请求速率或并发数 | 瞬时请求量超过预设速率或并发上限 | 请求进入业务处理之前 | 拒绝并提示重试、排队、延迟放行 |
| 配额 | 一个周期内的累计调用总量 | 累计用量达到周期额度 | 请求入口，按累计计数判断 | 拒绝直至下个周期重置或额度提升 |
| 熔断 | 对下游依赖的调用通道 | 下游错误率或超时率达到阈值 | 调用下游之前，依据健康状态判断 | 快速失败，经过冷却期后试探恢复 |
| 降级 | 功能或返回结果的完整程度 | 系统压力过大或依赖不可用 | 业务处理过程中或结果返回前 | 返回兜底数据、关闭非核心功能 |
配额关注累计用量，限流关注瞬时速率。一个应用可能每秒只发一次请求，速率远低于限流阈值，但一个月累计调用量达到套餐上限，此时触发的是配额，不是限流。配额的重置周期通常是天或月，限流的判断窗口通常是秒级或分钟级。
熔断关注依赖健康状态。当平台调用某个外部系统持续超时，熔断器打开，后续请求直接快速失败，不再等待超时。这个判断依据是下游的错误率，与调用方发了多少请求无关。降级关注可用性取舍，在压力大时关闭报表导出、返回缓存数据，让核心流程继续可用，它改变的是功能范围，不是请求准入。
此外，鉴权与权限校验、参数校验、审计日志、计费统计都不属于限流。鉴权判断调用方身份是否合法、是否有权访问该资源；参数校验判断请求体字段是否完整、格式是否正确；审计日志记录谁在什么时间做了什么操作；计费统计按调用量核算费用。这些环节可能与限流在同一请求链路上先后执行，但各自的判断依据和失败响应都不同。
具体例子与常见误解
示例一：某集成应用在每天上午九点批量拉取工作项，一次性发出大量分页请求，短时间内超过接口速率上限，部分请求返回限流状态码。这是典型的限流触发，处理方式是调用方加入退避重试、把批量任务错峰或分批执行，平台侧则评估该接口的阈值是否与业务节奏匹配。此例为演示情景。
示例二：某次单条请求等待很久后超时失败，调用方怀疑被限流。检查后发现请求数量远低于阈值，实际原因是该查询涉及大范围数据扫描，响应时间超出客户端超时设置。这属于单次请求过重和慢查询问题，限流并未介入。此例为演示情景。
示例三：某应用本月调用次数达到套餐约定的总量，之后所有请求都被拒绝，即使当前每秒只发一条。这是配额用尽，不是限流。解决路径是提升额度或调整周期，而不是修改速率阈值。此例为演示情景。
常见误解之一是“限流等于封禁”。限流是对超出部分的临时拦截，窗口过后自动恢复；封禁是针对调用方身份的处置措施，通常由安全或管理策略触发，两者性质和恢复方式都不同。误解之二是“限流能解决所有性能问题”。限流只处理入口流量过载，对慢查询、数据错误、权限越权、下游依赖故障都无能为力，性能问题需要按链路上各环节分别定位。误解之三是“被限流说明平台不稳定”。限流正常工作恰恰说明保护机制在起作用，真正需要关注的是阈值是否合理、调用方是否按约定节奏调用。
把这几类现象分开判断，排查方向就清楚了：先看请求速率是否触顶，再看周期用量是否用尽，然后看下游依赖是否健康，最后回到单次请求本身的耗时和数据正确性。研发管理平台的开放接口在支撑企业系统集成时，调用方管理、接口分组和异常处理约定需要与限流策略一起规划，才能让集成任务在可预期的节奏下稳定运行。
常见问题
调用方收到限流响应后，应该立即重试还是等待？
建议按平台返回的重试提示等待后再发起请求，并采用指数退避策略逐步拉长重试间隔。被限流后立即重试会继续占用入口配额，可能造成二次冲击，让恢复时间变长。如果批量任务频繁触发限流，更有效的做法是把任务错峰或分批执行，同时与平台管理员确认该接口的阈值是否与业务节奏匹配。
同一个应用既可能触发限流，也可能触发配额，如何快速区分？
看拒绝发生的时间尺度和计数口径。限流依据秒级或分钟级的瞬时速率，请求降速后很快恢复；配额依据天或月的累计调用总量，一旦用尽，即使当前每秒只发一条请求也会被拒绝，直到周期重置或额度提升。排查时先确认当前请求速率是否接近上限，再看本周期累计用量是否已经达到约定额度。
平台侧调整限流阈值后，调用方需要做什么配合？
调用方需要确认策略的生效范围和生效时间，避免配置已改、脚本仍按旧节奏请求。同时检查自身的重试逻辑是否带有退避、批量任务是否可分片、轮询频率是否可降低。阈值调低时尤其要提前通知集成方，给调用方留出调整窗口，减少集成任务集中失败的情况。
限流触发是否意味着平台出现故障？
限流正常工作说明入口保护机制在起作用，与平台故障是两件事。需要关注的是阈值设置是否合理、调用方是否按约定节奏调用。如果限流频繁触发且伴随接口响应变慢，才需要进一步排查后端容量、慢查询或下游依赖状态。
研发管理平台开放接口的限流维度与阈值在哪里可以查到？
具体限流维度、阈值和超额响应方式属于平台接口文档的内容，各产品定义不同，应以所使用平台的官方接口文档为准。在规划集成前，先理清调用方识别方式、凭证分配和接口分组，再据此设置分应用、分接口的差异化上限。ONES 提供丰富多样的 API 接口，可快速集成 ONES 与企业系统，实现数据打通，具体接口规则以官方文档说明为准。
