用开放接口调用记录评估接口稳定性，关键是把每条记录整理成可复算的指标：在固定时间窗内统计调用总量、成功量、失败量与超时量，计算成功率、失败率和超时率，再按端点、调用方、错误类型和时段拆分，区分偶发失败与持续劣化。评估结论需要写明分母、时间窗、缺失记录处理和阈值来源，单看成功率不足以代表整体稳定性。
要点总览（TL;DR）
- 评估前先固定口径：端点清单、调用方范围、时间窗与聚合粒度，所有比率共用同一分母（去重后的调用总量），报告保留分子分母便于复算。
- 核心指标是调用总量、成功量、失败量、超时量与成功率、失败率、超时率，延迟用P50、P95、P99分位数描述，并注明样本量。
- 按端点、调用方、错误类型和时段拆分，用连续失败区间和相邻周期延迟变化区分偶发波动与持续劣化。
- 阈值来自服务约定、历史基线或业务容忍度并注明来源；没有可靠阈值时先给观察值和周期对比，不设通用达标线。
- 成功率受调用方行为和重试归类影响，样本过少时不下结论，指标达标仍需与日志、告警交叉验证。
评估目标：先明确要回答的稳定性问题
调用记录本身只是流水，直接统计容易得到一堆没有结论的数字。评估开始前先写一份目标说明，把“评估谁、看哪段时间、回答什么问题、结论给谁用”固定下来，后续的指标和拆分维度都围绕这份说明展开。
评估对象要落到具体清单：哪些开放接口端点纳入范围，哪些调用方参与统计，时间窗从哪天几点到哪天几点。端点清单建议按接口分组列出，调用方清单用调用方标识而非名称，避免同一调用方因名称变更被拆成多条。时间窗要注明时区和聚合粒度，例如“2025年3月1日至3月31日，按小时聚合，UTC+8”。
待回答的问题通常有三类：整体稳定性是否达到预期；哪个端点或哪个调用方拉低了整体表现；稳定性是在改善还是在劣化。三类问题对应不同的拆分方式，整体判断看汇总指标，定位问题看端点和调用方拆分，趋势判断看按时段排列的序列。
结论用途决定判断标准。用于验收时，阈值来自服务约定或验收标准；用于日常巡检时，阈值来自历史基线；用于扩容决策时，还需要结合流量增长和延迟分位数；用于问题定位时，重点是异常区间和错误类型分布。用途不同，同一组数据可能得出不同的行动建议，目标说明里应写明本次评估服务于哪一种用途。
指标与范围：成功率、失败率、超时率与延迟
稳定性评估的核心指标是四个计数和三个比率，外加延迟分位数。所有比率的分母都是同一时间窗内去重后的调用总量，分子分别是成功量、失败量和超时量，单位用百分比，报告中同时保留分子分母，方便他人复算。
| 指标 | 定义与公式 | 分子 | 分母 | 单位 |
|---|---|---|---|---|
| 调用总量 | 时间窗内去重后的调用记录条数 | — | — | 条 |
| 成功量 | 按成功判定规则归类的记录条数 | — | — | 条 |
| 失败量 | 按失败判定规则归类的记录条数 | — | — | 条 |
| 超时量 | 耗时超过约定超时阈值的记录条数 | — | — | 条 |
| 成功率 | 成功量÷调用总量×100% | 成功量 | 调用总量 | % |
| 失败率 | 失败量÷调用总量×100% | 失败量 | 调用总量 | % |
| 超时率 | 超时量÷调用总量×100% | 超时量 | 调用总量 | % |
| 延迟分位数 | P50、P95、P99耗时，注明时间窗与样本量 | — | — | 毫秒 |
延迟用分位数描述，平均值会把少量极慢请求摊薄，掩盖长尾问题。P95表示95%的调用耗时不超过该值，P99对应最慢的1%。分位数必须和样本量一起报告，样本只有几十条时P99几乎没有参考意义。
统计范围要写清端点清单、调用方清单、时间窗和采样粒度。如果调用记录经过采样，需要在报告中注明采样比例，并把指标标注为估算值。三个比率的分子之和应等于调用总量，若出现不相等，说明存在未归类的记录，需要回到口径规则中补齐。
数据口径：调用记录里取哪些字段
口径决定结果能否复算。从调用记录中至少提取六类字段：时间戳、端点标识、调用方标识、响应状态或错误码、耗时、请求标识。时间戳用于切分时间窗，端点和调用方用于拆分，状态码用于判定成功失败，耗时用于超时归类和分位数计算，请求标识用于去重和识别重试。
成功与失败的判定要写成明确规则。常见做法是2xx状态码计为成功，4xx和5xx计为失败，其中因调用方参数错误导致的4xx可以单独标记，避免和接口自身故障混在一起。超时单独归类：耗时超过约定阈值且未返回正常响应的记录计为超时，不再重复计入失败，保证三类计数互斥。规则写进报告，读者才能判断数字的含义。
缺失、重复和重试是三类需要预先处理的情况。缺失关键字段的记录无法归类，应单独计数并在报告中说明占比；同一请求标识出现多条记录时，按请求标识去重，保留最终状态；重试请求可以按请求标识合并为一次调用，也可以单独标记后保留，两种方式得出的成功率不同，选择哪一种要在报告中写明。重试合并后的成功率反映调用方最终拿到结果的比例，保留重试则更能暴露首次调用的失败情况。
时间窗对齐要求所有记录使用同一时区，跨天统计时明确以哪个时区切分日期。聚合粒度按小时或按天均可，粒度越细越容易发现短时抖动，但记录量小时会产生大量空窗，需要结合样本量选择。
计算与评估步骤：从记录到结论
第一步按时间窗聚合。以去重后的记录为底表，按选定粒度统计调用总量、成功量、失败量和超时量，计算三个比率和延迟分位数，得到整体基线。这一步的产物是一张按时间排列的汇总表，每一行对应一个时间片。
第二步做拆分。按端点拆分，找出成功率明显低于整体的端点；按调用方拆分，观察是否存在个别调用方贡献了大部分失败；按错误类型拆分，区分参数错误、鉴权失败、服务端错误和超时；按时段拆分，看失败是否集中在特定时间。拆分维度可以组合，例如“端点×错误类型”，用于定位某端点的主要失败原因。
第三步识别劣化。把各时间片的成功率排成序列，观察是否出现连续多个时间片低于基线，连续失败区间比单点低值更能说明问题。同时对比相邻周期的P95延迟，延迟抬升往往先于失败率上升出现。趋势判断建议至少覆盖三个周期，单周期波动不足以定性。
第四步对照阈值给出判断。阈值来源可以是服务约定、历史基线或业务容忍度，报告中注明来源和取值。判断结果分为三档：达到阈值且无劣化趋势，判为通过；指标接近阈值或出现短时异常但未持续，判为观察，安排下一周期复评；持续低于阈值或连续失败区间扩大，判为整改，列出具体端点和调用方。没有可靠阈值时，先给出观察值和与上一周期的对比，不虚构通用达标线。
评估结论和整改项需要有人跟进时，可以把每个问题端点或调用方登记为工作项，附上指标数据、时间窗和判断依据，整改完成后回填复评结果。ONES 的工作项与文档可以承载这类记录和跟踪，具体字段和流程按团队现有方式设置。
例子：一次调用记录评估的完整演算
以下为演示数据，用于说明计算过程，不代表任何真实系统。假设评估某开放接口在2025年3月1日至3月7日（UTC+8，按天聚合）的表现，去重后调用总量为120,000条，其中成功114,000条，失败4,800条，超时1,200条。
整体指标计算：成功率=114,000÷120,000×100%=95.0%；失败率=4,800÷120,000×100%=4.0%；超时率=1,200÷120,000×100%=1.0%。三类计数之和为120,000，与调用总量一致，说明没有未归类记录。延迟方面，P50为180毫秒，P95为920毫秒，P99为2,400毫秒，样本量120,000条。
按端点拆分后发现，端点A承担了80,000次调用，成功率97.5%；端点B承担40,000次调用，成功率90.0%，失败2,800条、超时1,200条，超时全部集中在端点B。端点B的P99为3,800毫秒，明显高于整体。按调用方拆分，调用方X贡献了端点B失败的60%，其请求集中在每日10时至11时。
对照阈值：假设服务约定成功率为99.0%，则整体95.0%未达标，端点B的90.0%是主要拖累项。结合连续失败区间看，端点B在3月3日至3月5日连续三天成功率低于92%，属于持续劣化而非偶发波动。结论为整改：优先排查端点B在高峰时段的超时原因，并与调用方X确认其请求模式；端点A维持观察。整改项登记为工作项，下一周期复评端点B的成功率和P99。
解读与限制：避免把指标当因果保证
成功率受调用方行为影响明显。调用方传入错误参数、在高峰集中请求或未按约定重试，都会拉低成功率，这类失败反映的是使用方式而非接口质量。解读时应把调用方原因导致的失败单独列出，再判断接口自身的稳定性。
分母为零或样本过少时不下结论。某端点一周只有几十次调用，一次失败就会让成功率大幅波动，此时只记录数据不足，等样本积累后再评估。同理，按小时拆分后大量时间片为空时，趋势判断应回到按天粒度。
重试和超时的归类方式会改变结果。合并重试后的成功率偏高，保留重试则偏低；超时若同时计入失败，失败率会被放大。报告必须写明采用的规则，跨周期对比时保持规则一致，否则数字不可比。
指标达标不等于业务无风险。成功率反映的是调用结果，接口返回正确但数据错误、延迟在阈值内但持续抬升，都不会体现在成功率上。评估结论应与调用日志、告警记录和业务侧反馈交叉验证，发现指标未覆盖的问题时，回头补充指标或调整口径。
常见问题
调用记录里同时有重试请求，成功率应该按合并还是按保留重试来算？
两种算法都成立，取决于要回答的问题。按请求标识合并重试，得到的是调用方最终拿到结果的比例，适合评估对外可用性；保留每次重试单独计数，首次调用的失败会暴露出来，适合定位接口自身问题。无论选哪种，都要在报告中写明规则，跨周期对比时保持一致，否则两期数字不可比。
某个端点一周只有几十次调用，成功率波动很大，还能给出稳定性结论吗？
样本过少时不宜下稳定性结论。几十次调用中一次失败就会让成功率变动几个百分点，这种波动更多来自样本量而非接口质量。建议只记录数据不足，把聚合粒度从按小时回到按天或按周，等样本积累后再评估；如果该端点业务重要，可以单独延长观察周期，而不是用短窗口的数字直接判定整改。
整体成功率达标，但个别调用方的失败率明显偏高，评估结论该怎么写？
这种情况应把结论拆成两层：整体判为通过，同时把高失败调用方列为观察项。先按错误类型看该调用方的失败构成，参数错误和鉴权失败通常指向调用方接入方式，服务端错误和超时则要回到接口侧排查。结论中写明该调用方的调用量占比，占比很小时对整体的影响有限，但仍需与其确认请求模式，避免后续流量增长放大问题。
超时记录既超过耗时阈值又返回了错误码，应该计入超时还是失败？
关键是保证三类计数互斥，让成功量、失败量、超时量之和等于调用总量。常见做法是优先按超时归类：耗时超过约定阈值且未返回正常响应的记录计为超时，不再重复计入失败。如果团队更关注错误码分布，也可以先按状态码归类、再把其中的超时单独标记，但要在报告中说明顺序，并保证各期规则一致。
评估发现的劣化端点，后续怎么跟踪到复评闭环？
把每个问题端点或调用方登记为一条工作项，附上时间窗、指标数值、判断依据和阈值来源，指定负责人和复评时间。复评时用相同口径重算同一组指标，把结果回填到原记录，形成前后对比。ONES 的工作项与文档可以承载这类登记和跟踪，字段与流转按团队现有流程设置即可。
