大廠對外提供的API接口入參命名規範

最近查閱百度API接口時,發現接口文檔中,參數明文居然是下劃線格式,很疑惑。進一步查閱了 阿里開發平臺、騰訊微信開發者平臺, 對外api接口都是下劃線命名,  爲什麼? java實體類的屬性一般是遵從駝峯式命名規範。我們的程序裏的數據訪問層一般均採用ORM框架。如果表字段是小寫字母+下劃線,那麼,相應的POJO/POCO實體類的屬性也會是小寫字母+下劃線,這樣,違背了駝峯式命名規範,有違代碼的整潔度。

在網上查閱到原因:

對外提供的接口,

  • 如果用駝峯式。 首先,我們用word編寫接口說明文檔時,在參數表格列裏輸入參數名後,如果按tab鍵,則word默認首字母是大寫的。而如果恰好我們的首字母是小寫時,如果我們在編寫時忽略了這個細節,這就會給對接者帶來疑惑(產品設計上有一條重要的原則:Don't Make Me Think,同樣適用於軟件設計); 更甚之,如果簽名規則要求的簽名原串包括參數名時,那麼,因字母大小寫所致的驗籤失敗往往不那麼容易排查出來,進而造成雙方的“不必要”溝通。
  • 如果用小寫+下劃線。 首先,這種方式規避了上面駝峯式命名的不足。 其次,考慮到商戶對接存在不同的編程語言如php/java/.net,跨語言程序員之間也都會認可。

綜上:個人建議對於內部系統之間的接口,儘量採用java命名規範。 對外提供API可以和大廠們保持一致。各有優缺點,看開發者如何取捨。 實踐出真知。


 

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章