能跑通的接口，全是假象，上线三天就出事。
我们天天写API，却很少想它到底靠不靠谱。
面试时被问倒的、线上查不出问题的、合作方骂你文档乱的，其实都因为一开始没想清楚。
现在好多接口，只要前端能拿到数据就完事。参数没校验，错误码全用500，连超时时间都随便写个30秒。银联那边一个支付接口，光签名就得检查时间戳、随机串、密钥，差一秒都不让过。微信退款必须带idempotency-key，支付宝删订单接口重复调十次，结果还是只删一次。这些不是炫技，是踩过太多坑才定下来的规矩。
安全这事，真不能图省事。我之前见一个项目，用MD5拼接token，后端连盐都不加，扫一下就全暴露了。现在KMS托管密钥是标配，手机号传过来必须AES-256加密，每次还换IV，不然黑客截个包就能解。Token也得分场景——B2B系统直接用client_id+secret拿token，B2C后台得带scope权限字段，付钱这种操作，必须再弹个短信验证码，不能和登录共用一个token。
接口地址看着是小事，其实特别影响协作。比如把“改状态”写成`/updateOrderStatus`，前端以为是个新接口，后端其实只是套了个壳。正确的写法是`PATCH /orders/{id}/status`，谁看都明白在动哪个资源的哪个字段。GET必须能重刷不扣钱，DELETE重复删要返回204，不是404。响应体也得统一，code、message、data、trace_id一个不能少，400错误得告诉具体哪个字段错了，不能只回一句“参数错误”。
线上最怕的不是崩，而是崩了找不到原因。有一次订单超时，查日志翻了半小时，最后发现是下游接口卡在DNS解析，因为没设connect timeout。现在我们所有客户端设3秒连通、8秒读完，服务端内部调用卡超300毫秒就报警。慢SQL、缓存没命中、第三方超时，全得打点。trace_id从入口带到DB再到消息队列，日志一搜就串起来。
版本管理也常被忽视。有团队用header传v2，结果CDN把v1和v2混缓存，用户刷半天还是旧版。现在一律走URL路径，`/v2/users`清晰又方便灰度。老接口要下线，不偷偷关，而是返回410 Gone，还带个Link头指到新地址。OpenAPI文档也不再是写完就扔，CI里自动跑spectral检查，少写一个example都过不了。
我参与过一次三方对接，对方把我们的接口文档打印出来，盖章后当合同附件。当时真有点懵，后来才懂：文档写得清，签名验得严，错误码说得明，监控看得准，别人自然敢签。没人喜欢写一堆防御代码，但等故障来了，重写比补漏还累。
检查清单我贴在工位旁边：幂等性测了没？trace_id打了没？敏感字段真加密了？OpenAPI文档扫过spectral没？400错误有没有字段级提示？监控面板上p99延迟是不是绿的？这些事儿做全了，接口才算立住了。
其实没那么玄乎，就是别偷懒。签名多算一个参数，日志多打一个trace_id，错误码多写一行说明，监控多配两个告警。这些动作拆开看都不难，合起来就是别人敢调、敢联、敢长期用的底气。
文档签字那天，没人鼓掌，也没人说啥。
接口跑稳了，大家就去忙别的了。
