API设计：为什么你写的接口，半年后连自己都看不懂？

你有没有遇到过这种情况：调一个第三方API，光看文档就得花半天，调通之后还要骂娘？或者更惨——你自己写的API，半年后再回来接手，发现连自己都看不懂？

好的API设计就像好的UI——用户不需要说明书就能上手。区别是，API的用户是开发者，他们的耐心比普通用户更少。

一个真实的故事

去年我对接过一个支付API，文档里写着：amount: 金额。结果调了半天报错，最后发现——他们要的是分，不是元。文档里一个字都没提。

从此之后，我对API设计有了敬畏之心。

好API的三个标准

1. 直觉：看方法名就知道干嘛，看参数名就知道传啥。

2. 一致：整个API风格统一，不要让用户猜。

3. 容错：错误信息要告诉用户该怎么办。

命名这件事，值得花时间

我见过最离谱的命名是：getData()、getData2()、getRealData()。这三个方法返回的东西完全不一样，命名却像在比赛谁更敷衍。

好的命名应该是自解释的：

• getUserProfile() 而不是 getData()
• calculateOrderTotal() 而不是 process()
• validateEmailFormat() 而不是 check()

多花30秒想个好名字，能省下后来者30分钟的困惑。

版本控制：越早越好

很多人觉得第一版API不用加版本号，反正后面可以加。错！等你有100个调用方的时候，改任何一个接口都是灾难。

从第一天就把版本号加上：

我总结的API设计检查清单

• ✅ 方法名/参数名是否自解释？
• ✅ 命名风格是否整个API统一？
• ✅ 是否遵循了RESTful规范？
• ✅ 错误信息是否足够帮助调试？
• ✅ 是否有版本号？
• ✅ 文档是否完整？
• ✅ 单位是否明确？

写在最后

好的API设计不是技术问题，是同理心问题。当你站在调用者的角度思考，很多答案就自然浮现了。

毕竟，那个半年后看API文档骂娘的人，可能就是你自己。