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 服務器般好用的調試功能。）

固然它和一些知名的管理工具 Swagger 、 RAML仍是有些差距，好比工具鏈不夠豐富，不能經過註釋生成代碼。

小結：多視角的創建是從1到N的量變，而這個過程須要積累更多的經驗，最終造成全局視野。

總結

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

不少工程師覺得本身和大神的差距是技術，但這種差距只是表象，而實質的差距是思惟方式和技術視野。

技術視野不同工程師，即便是作一樣的事情，取得的成就也會不同，這也是爲何我會在寫書的時候注重幫助讀者提高技術視野~

• 一個工程師作事情若是老是隻考慮把事情完成，零視角解決問題，最多隻能成爲中級工程師。
• 能跳出事情自己，站在一個合理的角度進行思考，長久積累下來就能達到高級工程師的水準。
• 考慮事情的來龍去脈以及所在系統中的各類聯動關係，已然是架構師的視野了。