• 优秀的程序接口该如何设计
  • 发布于 1周前
  • 104 热度
    1 评论
  • 林永贵
  • 2 粉丝 19 篇博客
  •   
最近公司在项目上用了几个Django外援编写后台,总体来说效果不太理想。或者是出于能力问题,或者是由于动力不足,外援们编写的接口问题百出。当我们试图让外援根据我们的要求修改接口的时候,有的配合,有的不配合,不配合的理由大致是说我们事前没有做这么高的要求。好吧,他觉得这个要求很高,但是我觉得这是接口的基本要求,是一个好接口基本的自我修养。为了避免再有人抱怨说我的要求不清晰,我这里就详细阐述下在我心里“一个好接口的自我修养”应该是什么样的?

第一.一个好接口要长得好看

在这个看脸的社会,颜值总是放在第一位的。接口代码也是如此,脏乱差的代码,其他人一眼都不想看,更别说维护和修改了。我们对人的要求一般是“干净整洁讲卫生”,对代码类似,至少要做到“空格缩进有标准”吧。如果你不知道什么是好的标准,那么遵循PEP8啊。

下面是一个外援的代码:

图1:外援代码整容前

这个代码我看起来是有点难受的:为什么这个函数跟上一个函数之间空4行,下一个函数跟这个函数之间空一行?为什么函数参数之间有的间隔两个空格,有的却没有空格。另外两个换了行的超长代码行,我看了之后生怕屏幕被捅破了。于是我用autopep8工具格式化了一下这个文件,于是它变成了下面这个样子:

图2:外援代码整容后

突然感觉这段代码从一个邋遢大汉变成了精致打扮的小鲜肉。

第二.一个好接口要功能完整、正确

一个好男人除了帅,还要会挣钱。接口也是如此,如果只有好看,功能不完整、不正确,也是没有什么卵用的。

接口功能完整,意味着这个接口内部至少要包含四个部分:参数验证、权限验证、数据操作和返回结果。其中每个部分可以少至只有一两行代码,在一些特殊情况下还可能没有代码,但是编写者需要在心里清晰地知道这个接口中的四个部分分别是哪几行。

下面是鄙人写的一个接口,从上至下清晰地标出了四个部分的范围:

图3:接口的四个基本部分

鄙人所写接口,基本都可以清晰地画出这四个框,其中:
参数验证是验证传入的参数是否有效,如果不写,往往会在参数错误时导致代码某处报错,服务器返回500。一个好接口是不允许返回500的。
权限验证是保证接口的调用时机和调用者与设计意图相同。调用时机不对,会导致脏数据的产生。调用者不对,会带来数据泄露的问题。无论哪一种,都可能最终导致业务的失败,造成不可挽回的损失。
数据操作是实际的数据更改,这部分是功能实现的部分。
返回结果部分,关键在于返回的数据结构的合理性。有关数据结构的合理及可用,我们后面还会说到,这里就不细说了。

根据我的观察,这四个部分,大多数初学者都是只关注数据操作的部分,其他三个部分实现的质量就非常呵呵了。可以说,另外三个部分的质量,最体现出高手和初学者的差别。

第三.一个好接口要让使用者愿意用

虽然你长得又帅,又会赚钱,但是就是逢人不给好脸色,这样依旧追不到心仪的妹子的。没有妹子欣赏,你的帅、你的会赚钱,又有什么用?同样的,一个接口如果输入参数和返回结构让调用者恶心,没人愿意用这个接口,那你为这个接口付出的努力就算是付之东流了。

举个现实的例子,我们一个外援要为下面这个页面编写接口:

这个页面分为6个部分。为了拉取这个页面的数据,该外援就写了6个接口。客户端对接时就不干了,页面一打开就要发6个请求,代码冗余不说,性能也不好。如果用微信小程序开发该功能,就直接无法完成功能了(微信小程序限制同时最多只能发5个请求)。

还有一些常见的糟糕的接口设计:比如为了代码少写一两行,返回“user__id”这样的字段(其中用了双下滑线,对接人员完全无法理解为什么要这样);不同接口相同参数却使用不同名字的;返回错误时,错误信息直接返回Traceback的,等等。

毕竟接口不是写来观赏的,是要给人调用的。适当地迁就调用者的需求和习惯,还是有必要的。我们这些写后台的,也算是半个服务业从业人员呢!(嗯,正当服务业,别想歪了~)

第四.一个好接口要基本安全

做到了上面三点,你就又帅又多金,关键还会撩,什么妹子追不到?追到了之后你就金屋藏娇,过上了幸福的生活。作为家里唯一的男人,家里的安全都是你的职责。虽说天下没有绝对的安全,但是晚上你家里也不能开门睡觉,不是么?基本的安全措施还是要有的,不能给盗贼开大门。一个好接口,能够避免一些初级的安全问题,也是非常必要的。

在我们邀请的外援中,有一半的人用了eval解析接口参数。想想这个比例也是蛮吓人的。因为我们的外援都是其他公司的在职员工,他们是兼职帮我们做事,可想而知有多少公司的后台开发会不自觉地留下eval这个黑客大门。(留过这个后门的请自觉留言承认错误)

另外,绝对不要使用上传参数的内容拼接SQL字符串,然后给数据库执行。Django ORM都这么优秀了,你还自己拼接SQL,你让Django怎么想?这日子还过不过了?

总结

做到上面四点,是一个好接口基本的自我修养。这些都是无关能力,只要你尽心,就一定能够也应该做到的事情。如果下次再使用外援,我就把这篇文章先给他看。做不到这四点,验收注定是无法通过的哦~

用户评论