网站API

我上周调一个天气接口，网站文档写了三页，网站参数却只有两个。网站最离谱的网站是，那个“返回示例”居然是网站手打的JSON——缩进都对不齐，字段还少了一个。网站那一刻我忽然明白，网站API这东西，网站文档写得越漂亮，网站坑往往越深。网站

API的网站本质很简单：你给服务器递一张纸条，它给你回一张纸条。网站但现实里，网站这张纸条的网站传递过程裹了太多层戏。OAuth要跳转，网站CORS要预检，限流要排队，重试要退避。有时候我觉得，整个互联网就像一座巨大的官僚大楼，每个API窗口后面都坐着一个面无表情的办事员，你填错一个字段，它就把材料原样扔回来，附一句“400 Bad Request”——连个“请”字都没有。

我见过最诚实的API是GitHub的。它的错误信息会直接告诉你“你引用的这个commit不存在”，而不是给你一串五位的错误码让你去查手册。也见过最敷衍的——某支付平台，接口挂了一次，报错信息是“系统繁忙，请稍后再试”。稍后是多久？没人知道。后来我抓包才发现，它内部其实抛了空指针异常，只是不敢把Java堆栈打印给客户端看。

做API设计的人常犯一个毛病：把接口当成自己代码的镜像。你内部有UserService，就暴露一个/api/user；你内部有OrderDao，就暴露一个/api/order。但调用方根本不在乎你的类怎么划分，他们只关心“我要下单，顺便查一下库存和优惠券”。于是你被迫写一堆聚合接口，或者让前端发三个请求再自己拼数据。这事我干过，前端同事也干过，两边都觉得自己在给别人擦屁股。

真正好的API设计，是把调用方当傻子照顾，但又不侮辱他们的智商。比如Stripe，它的支付接口就一个POST /v1/charges，参数就amount、currency、source三件套。但背后它帮你处理了3DS验证、网络重试、汇率换算。你用起来觉得简单，是因为它把复杂都藏在了那个“source”字段里——你传一个token，它自己去找银行结算。这种设计哲学叫“表面朴素，内里精密”，跟好的UI一样，你看不到设计，才是最好的设计。

当然，API也有让人血压飙升的时刻。我印象最深的一次，是某云服务商的对象存储接口，签名算法改了三次，每次都在文档角落加一行“为了安全考虑”。第三次改版时，我凌晨两点被报警吵醒，线上所有上传失败。查了半天，发现是时间戳的格式从秒变成了毫秒，而旧文档里还写着“Unix时间戳（秒）”。后来我在代码里写了个自适应解析：先按毫秒解析，失败就除以1000再试。丑是丑了点，但它能活。

说到底，API是人与人之间的契约，只是用机器语言书写。写接口的人要揣测调用方会怎么犯错，调用方要祈祷写接口的人别太有创意。最理想的状态是双方都懒——懒得多写一个不必要的参数，懒得多做一次没意义的校验。但现实往往是，一方为了“完整性”加了十几个可选字段，另一方为了“健壮性”给每个字段都写了十行兼容代码。最后接口文档长得像国考职位表，实际用起来却像猜谜。

我电脑里存着一个文档，叫《API设计检查清单》。第一条写着：“如果你需要解释这个参数为什么存在，那它可能就不该存在。”第二条是：“错误信息要写人话，别写代码。”第三条是：“永远别改字段的语义，哪怕你觉得旧语义是坨屎。”这几条都是我拿血泪教训换的，现在分享出来，希望能少几个人踩坑。