创业老炮私藏7个技术网站，省3年API试错成本

　　去年十二月，被个创业老炮拽去他新公司聊技术选型。那会议室空调滴水，他简历在桌上转了半圈，我盯着水渍在A4纸上晕开的圆圈，听他说“这七个网站够你少踩三年坑”。当时我还想，又来一个拿‘最佳实践’当圣经的——结果他甩出来的链接，倒真让我记了半年。

文章配图，仅供参考

　　第二个是Swagger Hub的社区案例库。他说“别光看官方教程，社区里那些被骂得最惨的API设计才值得学”。我点开一个标注‘反面教材’的案例，是个电商系统的订单接口，返回字段里‘status’用了‘1/2/3’代替‘pending/paid/shipped’，评论区有人骂“这设计得让前端多写多少if-else”。巧的是，上周我们组评审接口时，有个新人也这么干，我直接把那个案例链接甩群里，他当场改了。

　　第三个是AWS API Gateway的最佳实践文档。老炮说“别觉得云厂商的文档都是广告，他们踩过的坑比你吃的饭多”。我翻到里面讲‘版本控制’的部分，说“别用URL路径做版本号（/v1/users），要用请求头（Accept: application/vnd.api+json;version=1）”。我们之前用路径版本，结果前端说“缓存键总变，页面加载慢”，现在改用请求头，问题少了八成。走廊那股消毒水味飘进来时，我正把这段划重点。

　　第四个是Google的API Design Guide。老炮说“这帮人连‘HTTP方法该不该用PATCH’都能吵三百页”。我翻到‘资源命名’那章，说“别用复数名词（/users），要用单数（/user/{id}）”，因为“复数在URL里没语义，单数更符合RESTful的‘资源’概念”。我们之前用复数，被测试提了二十多个bug，说“分页查询时/users?page=1和/user?page=1，哪个是查单个资源？”现在全改单数，测试开心得在群里发了个烟花表情。

　　第五个是Apigee的API Security Checklist。老炮说“安全不是后端的事，是整个API链的事”。我翻到‘CORS策略’那节，说“别用通配符（），要明确指定允许的域名”。我们之前用，结果被安全团队扫出“跨域请求可能泄露敏感数据”，现在改成了白名单，安全团队没再找过麻烦。对了，那天下雨，老炮的伞放在会议室门口，滴了一地水，他边擦边说“这比你们踩的坑干净多了”。

　　第六个是Stoplight的API Style Guide。老炮说“风格统一比功能强大更重要”。我翻到‘命名规范’那章，说“别用缩写（usrId），要用全称（userId）”，因为“缩写会增加理解成本，尤其是对非英语母语的前端”。我们之前用缩写，被一个法国外包团队投诉“看不懂字段名”，现在全改全称，他们说“终于不用查字典了”。

　　第七个是Microsoft的REST API Guidelines。老炮说“这帮人连‘404该返回什么’都能写十页”。我翻到‘错误处理’那节，说“404要返回‘resource not found’，别返回‘not found’，因为‘resource’能让客户端知道是资源没找到，不是接口没找到”。我们之前返回‘not found’，被监控告警“大量404请求”，查了半天发现是客户端把接口路径拼错了，现在改回‘resource not found’，监控告警少了九成。

　　那天聊完，老炮说“这些网站不是银弹，是筛子——能帮你筛掉那些连基础规范都不遵守的API设计”。我回他“那优胜劣汰的‘优’，得是这些规范里的‘优’？”他转了半圈桌上的水杯，说“不然呢？你以为那些踩三年坑的人，是缺技术还是缺耐心？”

　　对了，上周面试个候选人，简历写“精通API设计”，我问他“RESTful API的幂等性该怎么保证”，他说“用POST方法”。我当场把Postman文档库里‘幂等性与HTTP方法’的案例甩给他，他看了五分钟，说“原来DELETE和PUT也能保证幂等”。我原以为他要反驳，结果他说“这规范比我想的严多了”。

　　现在每次评审接口，我都先问“你看了那七个网站里的案例吗？”有人说“看了”，我就让他讲具体哪篇；有人说“没看”，我就说“那你先回去看，下周再来”。省得像去年那个项目，因为错误码不规范，前端和后端吵了半个月，最后还是按Swagger社区的案例重写的——那半个月的工时，够看十遍这些网站了。

（编辑：站长网）

【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!