1. 程式人生 > >API文件管理工具折射出的技術視野

API文件管理工具折射出的技術視野

所謂技術視野,就是看問題時所能切換的不同角(維)度。

下面就以API管理工具(以下簡稱“管理工具”)為例,來探討背後隱藏的技術視野。

API管理工具

零視角

曾經在一個小型創業公司用到過最簡單的管理工具,就是一個開源的文件管理工具,介面功能類似wiki(維基百科)。

這樣的工具確實能滿足核心需求——API線上文件化,並支援使用者管理。

可是深想一層,對於管理工具的使用者——工程師,操作足夠友好,功能足夠完善嗎?

使用這類管理工具很多時候都會出現文件與程式碼不一致的情況,也就是說工程師都不願意去維護這個文件。

因為編寫修改文件是個耗費時間的事情,短期來看,維護了既無利益,不維護也無危害~

所以有時候介面的變更通過口頭協商而非文件協商。

小結:零視角其實談不上視野,是大多數工程師的最容易形成的思維方式,特點就是隻關注功能/問題本身。

單一視角

當時為了解決上面的問題,同時為了練手所學的Node.js,我寫了第一版的管理工具,並參加了線下沙龍分享。

現在看來其實當初的寫的專案還是比較粗糙的,除了展示介面相較於wiki更加美觀之外,主要加入了 Mock 功能。

更好的開源專案也有不少,比如阿里的RAP和國外的APIDOC

之所以把它們歸為一類討論,那是因為它們都體現了開發者的單一視角。

RAP就是典型地站在前端工程師的角度開發的。

比如第一版是以頁面來對介面進行分組,這種分組方式顯然不合理,後端之間的服務呼叫不涉及頁面怎麼辦呢?所以第二版對此進行了修改。

又比如和 MockJS 深度繫結,為前端工程師提供 Mock 功能。

MockJS 確實很不錯,不但支援資料模擬,還支援資料校驗,後端也是使用前端工程師所熟悉的 Node.js 編寫。

缺點呢後面在講其他管理工具的時候再對比分析。

APIDOC則是站在後端工程師角度來編寫,增加了通過程式碼註釋生成文件的功能。

小結:視角的建立意味著從0到1的質變,技術視野開始形成。此視野的工程師不再只關注功能實現或問題解決。

多視角

偶然間讀到 Martin Fowler大神的一篇關於契約測試的文章很受啟發,文中提出了一種構想,通過管理工具來對前後端進行校驗,從而保障文件與程式碼的一致性。

於是開發了第2版的管理工具。這一版同時從前後端兩個角度設計。

對於前端不僅支援 Mock服務,同時還能對請求引數進行校驗,甚至模擬服務端響應異常。 對於後端增加了類似 postman 除錯介面功能,同時由於採用 JSON-Schema規範,可以直接將schema移植到後端程式碼中作為校驗規則來校驗引數。(RAP的侷限性也在於此,MockJS的校驗只能用於 Node.js和瀏覽器端,其它語言編寫的服務端則無法使用。同時對於後端來說也沒有如 Mock 伺服器般好用的除錯功能。)

當然它和一些知名的管理工具 SwaggerRAML還是有些差距,比如工具鏈不夠豐富,不能通過註釋生成程式碼。

小結:多視角的建立是從1到N的量變,而這個過程需要積累更多的經驗,最終形成全域性視野。

總結

經常看到一些公司在招聘高階前端工程師的時候會要求掌握一門以上後的端語言或者說把掌握後端語言作為加分項,真正的用意不一定會要求前端工程師寫後端程式碼,但掌握後端語言的前端工程師會多一個思考維度,也就是技術視野更豐富。

很多工程師以為自己和大神的差距是技術,但這種差距只是表象,而實質的差距是思維方式和技術視野。

技術視野不一樣工程師,即使是做同樣的事情,取得的成就也會不一樣,這也是為什麼我會在寫書的時候注重幫助讀者提升技術視野~

  • 一個工程師做事情如果總是隻考慮把事情完成,零視角解決問題,最多隻能成為中級工程師。

  • 能跳出事情本身,站在一個合理的角度進行思考,長久積累下來就能達到高階工程師的水準。

  • 考慮事情的前因後果以及所在系統中的各種聯動關係,已然是架構師的視