web接口

凌晨两点，我盯着浏览器里那个红色的500 Internal Server Error，突然觉得web接口这东西像极了人与人之间的承诺——你说你会给我数据，我信了，结果你反手甩给我一堆乱码。

接口的本质就一句话：约定好格式的请求和响应。前端说“我要用户信息”，后端就回一段JSON，字段名是name，值就是“张三”。这事听起来简单，但全世界的程序员都在为它掉头发。我见过最离谱的接口，文档写着返回success: true，实际代码里却拼成了sucess——整整三个星期，所有调用方都在默默检查自己的参数是不是写错了。

真正的麻烦在于，接口一旦上线，就像泼出去的水。你可以改内部逻辑，但字段名动不得，参数格式变不得。有个老系统用了八年，里面的user_id其实是手机号，remark字段存的是HTML片段。没人敢动，因为十几个业务线都挂在上面。你问为什么不重构？谁愿意为了“整洁”去承担凌晨三点被电话吵醒的风险。

接口设计得好的团队，通常有个共同点：把调用方当傻子。不是贬义，而是说他们会在文档里写清楚每个字段的取值范围，连“性别”都标注0代表未知，1男，2女。反观那些烂接口，status字段可能是字符串“1”，也可能是数字1，甚至有时直接缺省——全靠调用方猜。

我自己的血泪教训是，接口版本号一定要早加。最初觉得“就几个内部系统，没必要”，结果第三个月就有个需求要改返回结构。硬着头皮在原有字段上打补丁，new_name、name_v2这种脏东西全冒出来了。后来学乖了，URL里直接带/v1/，哪怕只有一个调用方也这么干。改起来至少不用看老代码的脸色。

还有件怪事。接口文档写得越漂亮，实际用起来越容易踩坑。有次对接某个第三方支付，文档画了精美的时序图，每个错误码都配了解释。结果联调时发现，他们文档里写的sign参数是MD5加密，实际代码里用的是SHA256。打电话问，对方理直气壮：“我们文档更新滞后了。”我盯着那PDF看了两小时，最后默默写了段兼容两种算法的代码。

做接口久了，人会变得特别务实。不再追求什么“优雅的设计模式”，而是关心超时时间设多少秒合适，重试机制会不会造成重复下单。有个同事说得在理：接口就是合同，白纸黑字写清楚，比什么都强。至于合同条款是否漂亮——能执行就不错了。

现在每当我看到新项目从零开始搭接口，总忍不住多嘴一句：先定好错误码规范，再写业务代码。没人听，等上线三个月后，他们就会回来找我吐槽——那时候，错误码已经乱得连自己人都分不清了。