沒有API文檔管理的開發就是耍流氓

導讀

• 背景
• 痛點
• 協同開發文檔
• API規範
• 工具,工具
• 後記

背景

隨著業務的發展,研發團隊的項目也是越來越多。同時,項目架構體系的擴展,我們對系統業務水平拆分,垂直分層,讓業務系統更加清晰,產生了一系列平台和子系統,並使用介面進行數據交互。

在公司業務快速增加和迭代的過程中,只有順應形勢,採取"中台戰略",構建符合DT時代的更具創新性、靈活性的「大中台，小前台」組織機制和業務機制，即作為前台的一線業務會更敏捷、更快速適應瞬息萬變的市場，而中台將整合公司的運營數據能力、產品技術能力,對各前台業務形成強有力的支撐。 而筆者認為，"中台戰略"的落地就在於將業務進行拆分,然後通過開放介面,為更多的業務系統"賦能"，從而真正建立起共享服務體系。

痛點

我們運營和維護著諸多的對外介面,很多現有的介面服務寄宿在各個不同的項目,哪些應用在使用api也沒有管理起來。並且以前的調用模式，加密方式都有各自風格,從長期來看,維護和排錯困難。

每次和其他同事合作，對方都會要求給出api文檔,特別是開發完成的api介面,往往解釋半天,大家也很痛苦。新介面還好,可以製作一個文檔,可以解決一時的問題。

或許有的開發部門有很好的習慣,每次開發都會有要求寫開發文檔,介面文檔等。但是我們知道,很多介面是不同人在不同時間添加和維護的,信息不同步,也會造成越來越多的問題。

以下是總結的幾個痛點:

• 沒有介面文檔
• 介面在代碼里,只能看代碼

• 沒有集中的的api項目
• 相同業務的api分散在不同的項目
• 查找困難

• 代碼和文檔不匹配
• 代碼介面更新,文檔不更新

• 文檔不規範
• 有的是word,有的是excel,有的是txt等等

• api不規範
• 命名,參數不規範

擼碼一分鐘,對接三小時

協同開發文檔

真正優秀的團隊,是通過協同充分發揮出每個成員的能力。這就需要倡導和形成團隊文化，讓整個團隊能夠有強大的凝聚力。那麼,這期間必須形成一些標準和規範。而API介面相關的規範和文檔就是很重要的一環。

• 統一的文檔管理平台
• 規範的API規範
• 統一的對接模式

API規範

這裡也是見仁見智,但是我認為一個團隊最好有統一的API規範。特別是同一個項目的編碼風格,不管多少人參與,風格上要保持一致。我相信,很多人開發人員都會有"代碼潔癖",沒有人願意看到那種"辣眼睛"的代碼。

• 介面名稱
• 這裡統一使用小寫 如:api/order/get
• 可參考跟著Github學習Restful HTTP API 設計
• uri
• 提供客戶端使用的全路徑
• 如http://172.16.0.194:8057/api/order/get

請求協議

• Http,Https
• 請求方式
• POST,GET等
• 頭部(系統參數)
• 加密簽名,時間戳等
• 請求參數(業務)
• 業務相關的輸入參數
• 響應參數(業務)
• 輸出參數
• 返回示例
  定義返貨結果數據結構,更直觀

• 1.返回成功
• 2.返回失敗

這裡給一張圖來說明,

工具,工具

工欲善其事,必先利其器。帶著需求,去google了一下,果然有現成的開源工具(當然如果有時間我還是覺得可以自己開發一套)。同類工具對比之後,發現eolinker比較好用。

• 整體全貌

整個系統風格簡潔,還有點小清新的感。頁面功能布局合理,完全不用培訓就知道么使用。

• 協作管理

如同現在的很多在線工具一樣,如tower,processon, eolinker也提供了團隊協作功能。

• 新建項目

• 查看明細

後記

項目中使用restfulapi的情況較多,webservice,wcf,webapi均支持，所以這裡該規範重點針對resfulapi。

經過多個項目的API協同開發,實踐證明,有了規範更能減少溝通成本,讓參與的人真正協同起來,提高工作效率。

eolinker是一個開源的介面管理工具(github上源碼),可以自己搭建在自己的伺服器上使用。當然,如果要使用更多功能,可以購買付費版本。

參考

• 《企業IT架構轉型之道：阿里巴巴中台戰略思想與架構實戰》
• 如何基於eolinker 的進行介面管理
• github上源碼
• 跟著Github學習Restful HTTP API 設計

附

如果您對eolinker開源的項目感興趣,可以進一步查閱我編寫的安裝文檔。http://www.doc88.com/p-4753808839165.html

如果你想及時得到個人撰寫文章的消息推送，或者想看看個人推薦的技術資料，可以關注個人公眾號:碼農商業參謀）。

推薦閱讀：