潮州海绵专用胶厂 谈谈API接口开发, 怎么编写个比较理严谨的接口

接口写得烂潮州海绵专用胶厂，公司赔钱快，程序员背锅急。

我近帮公司改个支付回调接口，光是签名验签就调了三天。不是不会写，是没人告诉我为什么须加nonce_str，为什么timestamp差5秒就不让过。

以前觉得接口能跑通就行，传个参数，返回个json，完事。直到上个月支付系统崩了半小时，财务发现有37笔订单被重复扣款。老板开会不骂运维，门点名API组：“你们写的不是接口，是定时炸弹。”

其实问题很简单：GET里写了扣款逻辑，网络抖，浏览器重试，钱就没了。银联的文档里白纸黑字写着“GET须幂等”，我们却当废话。后来查日志，发现重试请求的timestamp样，但没带nonce，服务器根本分不清是不是同个请求。

签名这事也挺尴尬。开发说加了HMAC，测试也过了。上线后作老是签名失败。后发现对用的是GBK编码传参，我们按UTF-8签名，哈希值当然对不上。没人规定须统字符集，可不统，就等于没签。

Token和Sign搞混的人多。有人把JWT放Header里，再附个appKey+sign在URL里，以为越复杂越安全。其实JWT管的是“谁在操作”，sign管的是“这次数据有没有被改过”。个越权，个篡改，混着用，两边都不住。

敏感字段处理是糊弄。身份证直接传明文潮州海绵专用胶厂，说是“前端自己加密”。结果抓包看，js里base64下就完事，连密钥都没有。规检查时被叫停，临时加AES，密钥却写死在代码里——运维说，这跟贴在门上的钥匙没区别。

限流也常被当成摆设。测的时候QPS压到200没问题，上线就500。不是机器不够，是没做分。个恶意IP狂刷订单查询，pvc管道管件胶把整个支付查询接口拖垮。后来加了三层限流：接口、appKey、IP，才稳住。

日志以前只记http状态和时间，出问题只能靠猜。现在强制每条日志带request_id，前后端、数据库、消息队列全串得起来。有次退款失败，3分钟就定位到是Redis锁时没释放，而不是瞎翻代码。

奥力斯    pvc管道管件胶批发    联系人：王经理    手机：15226765735（微信同号）    地址：河北省任丘市北辛庄乡南代河工业区

错误返回以前五花八门：{"err":"参数错"}、{"code":1,"msg":"失败"}、甚至直接500加堆栈。现在统格式，带code、message、request_id、timestamp。客服接到投诉，直接甩ID给技术，不用再问“你点的哪个按钮”。

文档是笑话。Swagger页面写着/v1/orders，实际接口是/v1/order。前端照着调，直404。后来发现文档是两年前写的，没人新。现在强制PR不带OpenAPI变就不让并，文档改了，Mock服务自动新，连测试都不用手点。

接口废弃也没人管。旧版还在跑，新版又上线，两个版本逻辑还不样。有次客户用老接口查订单，返回的字段少个create_time，财务对账直接对不上。现在下线前须邮件通知，Headerdeprecated标记，到期自动返410，不偷偷删。

我删过三次自己的代码。次删的是没加幂等的支付回调，二次删的是用MD5存密码的登录接口，三次删的是把timestamp写成毫秒但服务端按秒解析的签名逻辑。删完才发现，难的不是写新代码，是改旧习惯。

OpenAPI文件现在跟src放起，改接口就得改YAML，CI自动校验兼容。有人嫌烦，说“我又不是写论文”。可代码没人读，文档没人看，出事时翻Git Blame，行就写着你的名字。

自查清单贴在工位电脑边：URI用复数没？X-Request-ID加了没？手机号AES了没？错误返回带ID没？文档同步没？写完项个勾，不勾不准提测。

有个实习生问我：“是不是得背很多规范？”我说不用，就记住三件事：别人会重试你的接口，别人会抄你的接口，五年后你自己还得修它。

这活干得糙，真会出事。