打开电脑，泡上一杯咖啡，准备对接一个新服务的API。点开文档，密密麻麻的参数说明扑面而来，但你最关心的是什么？不是“支持哪些功能”，而是“调用快不快”“会不会卡”“高峰期能不能扛住”。这时候，API文档里的性能指标就成了你的导航灯。
响应时间：别让等待毁掉体验
你在做一款订单查询工具，用户输入单号，系统调用API获取结果。如果文档标明平均响应时间是200毫秒，那用户体验基本流畅。但如果实际调用经常超过2秒，用户可能以为网络出问题，反复刷新，反而加重服务器负担。所以，靠谱的API文档会明确写出P95、P99响应时间，比如“95%的请求在300毫秒内返回”，这比只说“平均150毫秒”更真实。
吞吐量与并发能力：别在高峰时掉链子
某电商平台大促前，技术团队开始压测各个接口。API文档里写着“支持每秒处理5000次请求”，但没提“最大并发连接数”。上线后发现，当并发达到3000时，响应开始大幅延迟。后来才发现，文档漏写了“建议最大并发2000”。这类信息缺失，轻则影响业务，重则导致服务雪崩。真正实用的文档，会标注清楚QPS（每秒查询率）、最大并发连接数，甚至建议的客户端超时设置。
错误率与可用性：稳定比快更重要
你集成的支付API，文档声称“全年可用性99.9%”。听起来不错，但换算下来，每年允许宕机约8.7小时。如果你的产品面向全球用户，这个数字可能无法接受。更细致的文档会分时段统计，比如“工作日99.95%，节假日99.8%”，还会列出常见错误码的出现频率。比如“订单不存在”错误占总请求的0.3%，这能帮你提前优化前端提示逻辑。
数据大小与传输效率：省流量也是生产力
在开发一个移动端应用时，每次API返回的数据包大小直接影响用户流量消耗。文档中标注“典型响应体大小为1.2KB”，你可以据此评估是否需要开启GZIP压缩，或者考虑分页策略。有些API默认返回冗余字段，文档若注明“可通过fields参数精简至400B”，就能帮你在弱网环境下提升加载速度。
代码示例中的隐含性能信息
很多开发者只把示例当模板复制，其实里面藏着性能提示。比如：
requests.get(url, timeout=5) # 超时设为5秒，暗示服务通常在1-3秒内返回
再比如批量接口的示例中，一次最多传50个ID：
api.batch_query(ids[:50]) # 暗示单次请求上限，避免因传太多导致超时或被限流
这些细节不会写在“性能指标”章节里，但却是真实使用中的关键参考。
如何快速识别文档的性能可信度
打开一份API文档，先找有没有“SLA”或“性能基准”页面。没有？接着看是否有压测报告链接或第三方监测数据。如果只有“高性能”“极速响应”这种形容词，就得打个问号。真正的技术文档，会用数字说话，比如“在AWS us-east-1区域，c5.xlarge实例测试下，QPS可达7200”。
对接API就像租房子，功能是户型，性能指标就是水电宽带套餐。光看客厅多大没用，得知道冬天暖气稳不稳定，晚上刷视频卡不卡。下次读API文档，别急着跑demo，先翻到性能那一栏，那里藏着真实世界的运行节奏。