论一个好接口的自我修养

最近公司在项目上用了几个Django外援编写后台，总体来说效果不太理想。或者是出于能力问题，或者是由于动力不足，外援们编写的接口问题百出。当我们试图让外援根据我们的要求修改接口的时候，有的配合，有的不配合，不配合的理由大致是说我们事前没有做这么高的要求。好吧，他觉得这个要求很高，但是我觉得这是接口的基本要求，是一个好接口基本的自我修养。为了避免再有人抱怨说我的要求不清晰，我这里就详细阐述下在我心里“一个好接口的自我修养”应该是什么样的？

首先，一个好接口要长得好看。

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

下面是一个外援的代码：

图1：外援代码整容前

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

图2：外援代码整容后

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

其次，一个好接口要功能完整、正确。

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

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

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

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

鄙人所写接口，基本都可以清晰地画出这四个框，其中：

参数验证是验证传入的参数是否有效，如果不写，往往会在参数错误时导致代码某处报错，服务器返回500。一个好接口是不允许返回500的。

权限验证是保证接口的调用时机和调用者与设计意图相同。调用时机不对，会导致脏数据的产生。调用者不对，会带来数据泄露的问题。无论哪一种，都可能最终导致业务的失败，造成不可挽回的损失。

数据操作是实际的数据更改，这部分是功能实现的部分。

返回结果部分，关键在于返回的数据结构的合理性。有关数据结构的合理及可用，我们后面还会说到，这里就不细说了。

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

再次，一个好接口要让使用者愿意用。

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

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

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

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

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

最后，一个好接口要基本安全。

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

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

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

总结

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

幕

后

花

絮

主持人：请问有没有什么接口代码一看就是有情绪的？

作者：有的。比如接口中用try...except，然后不指定异常类型，并且把接口代码整体包起来的，基本上就说明代码作者不耐烦了，内心世界是“管它什么错误，随便返回个提示就行了。别再找我改bug了，阿弥陀佛，阿弥陀佛......”

主持人：有没有什么代码细节，让你一看就觉得代码作者不专业的？

作者：这个就比较多了。对空白、对齐不敏感的；变量命名看不出单复数的，明明是个列表，却写成一个单数单词的；基本上不处理边界条件的，等等。

主持人：做到了您说的四条要求之后，如何能让好接口变得更好？

作者：变得更好，最重要的就是让代码语义话。让不懂代码的人，阅读你的代码时也基本能猜出代码每句话是做什么的。这个涉及到如何更好地设计数据结构、如何更好地封装代码等，对编码者经验的要求就相对高了。这个话题展开很大，这里无法细说了。

主持人：感谢您今天的分享，我们感到受益良多。

作者：希望能为后台代码整体质量的提升，献出一点微薄之力。

-END-