API開發/運維經驗1

對於維護API的經驗，推薦《軟件框架設計的藝術》這本書，不管是webService仍是Rest仍是其餘什麼，都頗有幫助。

不過這書在概念上仍是離平時工做太遠，知識很精華，但和個人實際工做並不接軌，因此逐漸萌生「把我本身開發/運維API的一些經驗整理出來，寫一篇大的博文」這樣的想法

不過最近又忙且病，因此一條條慢慢往外擠……

1. 參數命名規範

我曾經接手一個已經運行一段時間的API系統，它對外暴露的接口的參數，沒有采用通用的第一個後單詞首字母的規範
我在新開發接口時，決定採用新的規範；
但問題來了，接口的之前使用者，在調用新接口時，總也調不通，緣由就是，之前用來標記訪問來源的參數visitsystem，被我不經意間改爲了visit**S**ystem，一字之差，接口在驗證時找不到訪問來源，因而不容許訪問；

由此得出經驗：參數規範化很重要，但對於以被使用的通用參數名，仍是聽從之前的規則。
由於開發最不喜歡細看接口文檔……啊啊啊！！！！（雖然我也有這毛病，但我仍是要鄙視）

2. 接口返回值 對於錯誤信息的返回，很是重要。調用接口的系統，會根據錯誤信息，提示用戶進行對應操做。 我負責這個系統，最開始是用數字（errcode），表明錯誤信息；但用數字用來標示每一個錯誤，則粒度太細，用來標示一類錯誤，則對信息的提示又不足； 好比對於系統異常，和參數錯誤，是同級別的錯誤類型，和某個具體參數的具體錯誤，如email不符合規範，就不是同級別； 於是增長errMsg，填寫具體錯誤信息（中文） 固然，系統架構上， 最好有對應的字典表，標記每一個errcode對應哪類錯誤；

這種方式的優缺點以下： 優勢：錯誤信息規範化，接口調用者可方便查詢； 缺點：增長開發者工做量和運維量。