去年冬天我帮朋友调一个物流查询接口，文档上写着“支持批量查询”，但实际请求超过20个单号就直接返回403。打电话问客服，对方说“建议单次不超过15条”。文档里没写。这种事在API圈子里太常见了——接口说明和实际行为之间永远隔着一层毛玻璃。

《api msh》这个标题看起来像某种缩写，其实是我给“API 迷思”起的代号。msh 就是 myth 去掉元音。干了六年后端对接，我攒了一堆关于 API 的误解，有些是新手常踩的坑，有些连老手也会栽。

迷思一：状态码 200 就代表成功

去年双十一前夜，支付网关的监控突然报警。调用量正常，延迟正常，错误率 0%。但业务方说订单状态没更新。查了半天才发现，对方返回的 HTTP 状态码是 200，响应体里 { "code": 500, "msg": "系统繁忙"}。他们的网关把业务错误包装成了 HTTP 成功。

这种设计不罕见。很多国内厂商喜欢在 body 里再套一层状态码，HTTP 层永远返回 200。你写重试逻辑的时候如果只看 HTTP 状态码，就等着半夜被叫起来吧。我的习惯是：拿到任何新接口，先构造一个必然失败的请求，看它怎么报错。这比读十页文档都管用。

迷思二：文档写了限流，但没写具体数值

“本接口有频率限制，请合理调用。”——这话等于没说。什么叫合理？每秒 10 次还是每分钟 10 次？

有个做爬虫的朋友接过一个天气 API，文档说“免费版限流较严”。他按每秒 1 次跑，第二天账号被封。发邮件问，回复说免费版限制是每分钟 5 次。他算了一下，按这个速度跑完十万条数据要 13 天。

我的做法是：对没写具体数值的接口，从每秒 1 次开始试探，逐步翻倍，观察响应头里的 X-RateLimit-* 字段。如果连这个头都没有，那就只能靠 429 状态码来反推。麻烦，但比封号强。

迷思三：版本号在 URL 里就万事大吉

/api/v2/users 这种设计看起来很清晰。但 v2 和 v1 的区别可能只是加了一个字段，也可能整个响应结构都变了。更坑的是，有些团队会在不升版本号的情况下改字段类型。

上个月遇到一个：用户 ID 从字符串变成了数字。前端 JS 里 parseInt 一下的事，但后端 Java 用 Jackson 反序列化直接抛异常。对方说“这是 bug 修复，不算 breaking change”。

我现在对接任何接口，第一件事是写一个契约测试。把响应 JSON 的结构、字段类型、必填项都断言一遍。对方偷偷改了什么，测试跑不过，至少能提前发现。

迷思四：OAuth 2.0 就是安全的

OAuth 2.0 本身是个授权框架，不是安全银弹。见过太多把 client_secret 写在前端代码里的，也见过 access_token 有效期设成永不过期的。

最离谱的一次：某开放平台要求把 client_secret 放在 URL 查询参数里传递。我截图问他们技术支持，对方说“我们内网环境，没关系”。可那是公网接口。

安全这事，协议只给了一半，另一半靠实现。我现在的检查清单很简单：token 有没有过期时间、刷新机制是否独立、敏感操作是否二次验证。少一个，我就发邮件要求对方确认。

迷思五：SDK 能省事

官方 SDK 确实能省去手写签名、拼装请求的麻烦。但 SDK 也是人写的，也会有 bug。而且很多 SDK 为了“易用”，把底层细节藏得太深，出问题的时候你连原始请求长什么样都看不到。

我一般先用 curl 把接口调通，确认签名、参数、响应都符合预期，再引入 SDK。如果 SDK 报错，至少我知道是 SDK 的问题还是接口的问题。这个顺序不能反。

写了这么多，其实就一句话：API 文档是对方想让你看到的样子，实际行为才是它真正的样子。多写测试，多抓包，少信文档。msh 这个代号我还会继续用下去，毕竟迷思永远比文档多一条。