論一個好介面的自我修養

知識 10-30

最近公司在項目上用了幾個Django外援編寫後台，總體來說效果不太理想。或者是出於能力問題，或者是由於動力不足，外援們編寫的介面問題百出。當我們試圖讓外援根據我們的要求修改介面的時候，有的配合，有的不配合，不配合的理由大致是說我們事前沒有做這麼高的要求。好吧，他覺得這個要求很高，但是我覺得這是介面的基本要求，是一個好介面基本的自我修養。為了避免再有人抱怨說我的要求不清晰，我這裡就詳細闡述下在我心裡「一個好介面的自我修養」應該是什麼樣的？

首先，一個好介面要長得好看。

在這個看臉的社會，顏值總是放在第一位的。介面代碼也是如此，髒亂差的代碼，其他人一眼都不想看，更別說維護和修改了。我們對人的要求一般是「乾淨整潔講衛生」，對代碼類似，至少要做到「空格縮進有標準」吧。如果你不知道什麼是好的標準，那麼遵循PEP8啊。

下面是一個外援的代碼：

圖1：外援代碼整容前

這個代碼我看起來是有點難受的：為什麼這個函數跟上一個函數之間空4行，下一個函數跟這個函數之間空一行？為什麼函數參數之間有的間隔兩個空格，有的卻沒有空格。另外兩個換了行的超長代碼行，我看了之後生怕屏幕被捅破了。於是我用

autopep8

工具格式化了一下這個文件，於是它變成了下面這個樣子：

圖2：外援代碼整容後

突然感覺這段代碼從一個邋遢大漢變成了精緻打扮的小鮮肉。

其次，一個好介面要功能完整、正確。

一個好男人除了帥，還要會掙錢。介面也是如此，如果只有好看，功能不完整、不正確，也是沒有什麼卵用的。

介面功能完整，意味著這個介面內部至少要包含四個部分：參數驗證、許可權驗證、數據操作和返回結果。其中每個部分可以少至只有一兩行代碼，在一些特殊情況下還可能沒有代碼，但是編寫者需要在心裡清晰地知道這個介面中的四個部分分別是哪幾行。

下面是鄙人寫的一個介面，從上至下清晰地標出了四個部分的範圍：

圖3：介面的四個基本部分

鄙人所寫介面，基本都可以清晰地畫出這四個框，其中：

參數驗證是驗證傳入的參數是否有效，如果不寫，往往會在參數錯誤時導致代碼某處報錯，伺服器返回500。
一個好介面是不允許返回500的
。

許可權驗證是保證介面的調用時機和調用者與設計意圖相同。調用時機不對，會導致臟數據的產生。調用者不對，會帶來數據泄露的問題。無論哪一種，都可能最終導致業務的失敗，造成不可挽回的損失。

數據操作是實際的數據更改，這部分是功能實現的部分。

返回結果部分，關鍵在於返回的數據結構的合理性。有關數據結構的合理及可用，我們後面還會說到，這裡就不細說了。

根據我的觀察，這四個部分，大多數初學者都是只關注數據操作的部分，其他三個部分實現的質量就非常呵呵了。可以說，另外三個部分的質量，最體現出高手和初學者的差別。

再次，一個好介面要讓使用者願意用。

雖然你長得又帥，又會賺錢，但是就是逢人不給好臉色，這樣依舊追不到心儀的妹子的。沒有妹子欣賞，你的帥、你的會賺錢，又有什麼用？同樣的，一個介面如果輸入參數和返回結構讓調用者噁心，沒人願意用這個介面，那你為這個介面付出的努力就算是付之東流了。

舉個現實的例子，我們一個外援要為下面這個頁面編寫介面：

這個頁面分為6個部分。為了拉取這個頁面的數據，該外援就寫了6個介面。客戶端對接時就不幹了，頁面一打開就要發6個請求，代碼冗餘不說，性能也不好。如果用微信小程序開發該功能，就直接無法完成功能了（微信小程序限制同時最多只能發5個請求）。

還有一些常見的糟糕的介面設計：比如為了代碼少寫一兩行，返回「user__id」這樣的欄位（其中用了雙下滑線，對接人員完全無法理解為什麼要這樣）；不同介面相同參數卻使用不同名字的；返回錯誤時，錯誤信息直接返回Traceback的，等等。

畢竟介面不是寫來觀賞的，是要給人調用的。適當地遷就調用者的需求和習慣，還是有必要的。我們這些寫後台的，也算是半個服務業從業人員呢！（嗯，正當服務業，別想歪了~）

最後，一個好介面要基本安全。

做到了上面三點，你就又帥又多金，關鍵還會撩，什麼妹子追不到？追到了之後你就金屋藏嬌，過上了幸福的生活。作為家裡唯一的男人，家裡的安全都是你的職責。雖說天下沒有絕對的安全，但是晚上你家裡也不能開門睡覺，不是么？基本的安全措施還是要有的，不能給盜賊開大門。一個好介面，能夠避免一些初級的安全問題，也是非常必要的。

在我們邀請的外援中，有一半的人用了eval解析介面參數。想想這個比例也是蠻嚇人的。因為我們的外援都是其他公司的在職員工，他們是兼職幫我們做事，可想而知有多少公司的後台開發會不自覺地留下eval這個黑客大門。（留過這個後門的請自覺留言承認錯誤）