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

什么是技術視野

網(wǎng)上看到不少關于如何提升技術視野的討論谆构,但卻沒有人給出定義署惯,到底什么是技術視野行施?

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

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

API管理工具

零視角

曾經(jīng)在一個小型創(chuàng)業(yè)公司用到過最簡單的管理工具又固,就是一個開源的文檔管理工具仲器,界面功能類似wiki(維基百科)。

這樣的工具確實能滿足核心需求——API在線文檔化仰冠,并支持用戶管理乏冀。

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

使用這類管理工具很多時候都會出現(xiàn)文檔與代碼不一致的情況识虚,也就是說工程師都不愿意去維護這個文檔肢扯。

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

所以有時候接口的變更通過口頭協(xié)商而非文檔協(xié)商。

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

單一視角

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

現(xiàn)在看來其實當初的寫的項目還是比較粗糙的被盈,除了展示界面相較于wiki更加美觀之外,主要加入了 Mock 功能搭伤。

更好的開源項目也有不少害捕,比如阿里的RAP和國外的APIDOC

之所以把它們歸為一類討論闷畸,那是因為它們都體現(xiàn)了開發(fā)者的單一視角。

RAP就是典型地站在前端工程師的角度開發(fā)的吞滞。

比如第一版是以頁面來對接口進行分組佑菩,這種分組方式顯然不合理盾沫,后端之間的服務調用不涉及頁面怎么辦呢?所以第二版對此進行了修改殿漠。

又比如和 MockJS 深度綁定赴精,為前端工程師提供 Mock 功能。

MockJS 確實很不錯绞幌,不但支持數(shù)據(jù)模擬蕾哟,還支持數(shù)據(jù)校驗,后端也是使用前端工程師所熟悉的 Node.js 編寫莲蜘。

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

APIDOC則是站在后端工程師角度來編寫,增加了通過代碼注釋生成文檔的功能票渠。

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

多視角

偶然間讀到 Martin Fowler大神的一篇關于契約測試的文章很受啟發(fā)昂秃,文中提出了一種構想,通過管理工具來對前后端進行校驗杜窄,從而保障文檔與代碼的一致性肠骆。

于是開發(fā)了第2版的管理工具。這一版同時從前后端兩個角度設計塞耕。

對于前端不僅支持 Mock服務蚀腿,同時還能對請求參數(shù)進行校驗,甚至模擬服務端響應異常荷科。
對于后端增加了類似 postman 調試接口功能唯咬,同時由于采用 JSON-Schema規(guī)范,可以直接將schema移植到后端代碼中作為校驗規(guī)則來校驗參數(shù)畏浆。(RAP的局限性也在于此胆胰,MockJS的校驗只能用于 Node.js和瀏覽器端,其它語言編寫的服務端則無法使用刻获。同時對于后端來說也沒有如 Mock 服務器般好用的調試功能蜀涨。)

當然它和一些知名的管理工具 SwaggerRAML還是有些差距蝎毡,比如工具鏈不夠豐富厚柳,不能通過注釋生成代碼。

小結:多視角的建立是從1到N的量變沐兵,而這個過程需要積累更多的經(jīng)驗别垮,最終形成全局視野。

總結

經(jīng)吃眩看到一些公司在招聘高級前端工程師的時候會要求掌握一門以上后的端語言或者說把掌握后端語言作為加分項碳想,真正的用意不一定會要求前端工程師寫后端代碼烧董,但掌握后端語言的前端工程師會多一個思考維度,也就是技術視野更豐富胧奔。

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

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

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

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

  • 考慮事情的前因后果以及所在系統(tǒng)中的各種聯(lián)動關系红且,已然是架構師的視野了。

?著作權歸作者所有,轉載或內容合作請聯(lián)系作者
  • 序言:七十年代末涤姊,一起剝皮案震驚了整個濱河市暇番,隨后出現(xiàn)的幾起案子,更是在濱河造成了極大的恐慌思喊,老刑警劉巖壁酬,帶你破解...
    沈念sama閱讀 217,185評論 6 503
  • 序言:濱河連續(xù)發(fā)生了三起死亡事件,死亡現(xiàn)場離奇詭異恨课,居然都是意外死亡舆乔,警方通過查閱死者的電腦和手機,發(fā)現(xiàn)死者居然都...
    沈念sama閱讀 92,652評論 3 393
  • 文/潘曉璐 我一進店門剂公,熙熙樓的掌柜王于貴愁眉苦臉地迎上來希俩,“玉大人,你說我怎么就攤上這事纲辽⊙瘴洌” “怎么了?”我有些...
    開封第一講書人閱讀 163,524評論 0 353
  • 文/不壞的土叔 我叫張陵拖吼,是天一觀的道長鳞上。 經(jīng)常有香客問我,道長吊档,這世上最難降的妖魔是什么篙议? 我笑而不...
    開封第一講書人閱讀 58,339評論 1 293
  • 正文 為了忘掉前任,我火速辦了婚禮怠硼,結果婚禮上涡上,老公的妹妹穿的比我還像新娘趾断。我一直安慰自己,他們只是感情好吩愧,可當我...
    茶點故事閱讀 67,387評論 6 391
  • 文/花漫 我一把揭開白布。 她就那樣靜靜地躺著增显,像睡著了一般雁佳。 火紅的嫁衣襯著肌膚如雪。 梳的紋絲不亂的頭發(fā)上同云,一...
    開封第一講書人閱讀 51,287評論 1 301
  • 那天糖权,我揣著相機與錄音,去河邊找鬼炸站。 笑死星澳,一個胖子當著我的面吹牛,可吹牛的內容都是我干的旱易。 我是一名探鬼主播禁偎,決...
    沈念sama閱讀 40,130評論 3 418
  • 文/蒼蘭香墨 我猛地睜開眼,長吁一口氣:“原來是場噩夢啊……” “哼阀坏!你這毒婦竟也來了如暖?” 一聲冷哼從身側響起,我...
    開封第一講書人閱讀 38,985評論 0 275
  • 序言:老撾萬榮一對情侶失蹤忌堂,失蹤者是張志新(化名)和其女友劉穎盒至,沒想到半個月后,有當?shù)厝嗽跇淞掷锇l(fā)現(xiàn)了一具尸體士修,經(jīng)...
    沈念sama閱讀 45,420評論 1 313
  • 正文 獨居荒郊野嶺守林人離奇死亡枷遂,尸身上長有42處帶血的膿包…… 初始之章·張勛 以下內容為張勛視角 年9月15日...
    茶點故事閱讀 37,617評論 3 334
  • 正文 我和宋清朗相戀三年,在試婚紗的時候發(fā)現(xiàn)自己被綠了棋嘲。 大學時的朋友給我發(fā)了我未婚夫和他白月光在一起吃飯的照片酒唉。...
    茶點故事閱讀 39,779評論 1 348
  • 序言:一個原本活蹦亂跳的男人離奇死亡,死狀恐怖封字,靈堂內的尸體忽然破棺而出黔州,到底是詐尸還是另有隱情,我是刑警寧澤阔籽,帶...
    沈念sama閱讀 35,477評論 5 345
  • 正文 年R本政府宣布流妻,位于F島的核電站,受9級特大地震影響笆制,放射性物質發(fā)生泄漏绅这。R本人自食惡果不足惜,卻給世界環(huán)境...
    茶點故事閱讀 41,088評論 3 328
  • 文/蒙蒙 一在辆、第九天 我趴在偏房一處隱蔽的房頂上張望证薇。 院中可真熱鬧度苔,春花似錦、人聲如沸浑度。這莊子的主人今日做“春日...
    開封第一講書人閱讀 31,716評論 0 22
  • 文/蒼蘭香墨 我抬頭看了看天上的太陽箩张。三九已至甩骏,卻和暖如春,著一層夾襖步出監(jiān)牢的瞬間先慷,已是汗流浹背饮笛。 一陣腳步聲響...
    開封第一講書人閱讀 32,857評論 1 269
  • 我被黑心中介騙來泰國打工, 沒想到剛下飛機就差點兒被人妖公主榨干…… 1. 我叫王不留论熙,地道東北人福青。 一個月前我還...
    沈念sama閱讀 47,876評論 2 370
  • 正文 我出身青樓,卻偏偏與公主長得像脓诡,于是被迫代替她去往敵國和親无午。 傳聞我的和親對象是個殘疾皇子,可洞房花燭夜當晚...
    茶點故事閱讀 44,700評論 2 354

推薦閱讀更多精彩內容

  • 因個人精力有限誉券,暫停簡書的維護指厌,歡迎大家關注我的知乎https://www.zhihu.com/people/we...
    尾尾閱讀 1,181評論 3 13
  • 文/鯉氏 曾宿桃花醉未醒。不知花謝萬般輕踊跟。 若發(fā)青帝應無意踩验,始恨人間常有情。 燭二盞商玫,夢三更箕憾,幾回垂淚到天明。 相...
    真觀閱讀 1,135評論 4 41
  • 大連的春天來了。溫暖的陽光和微涼的海風竟是這樣的和諧炬藤,每天在教室里望著窗外的山和藍天御铃,乏了,我想要去看一看大海沈矿。 ...
    寧夏初開閱讀 286評論 8 7
  • 昨天晚上女兒下班上真,走進家門鞋都沒顧得上換,就上前來把我緊緊地擁抱了一下羹膳,還在我耳朵邊悄悄說睡互,媽媽,我好愛你呀!女兒...
    微荷閱讀 467評論 1 1
  • 燈光將雪地認作親戚就珠, 便與他膩在一起晃著黑夜寇壳, 黑夜黑的竟尋不到一顆星星, 而在此時春姑娘正在 偷偷的用力掀起大地...
    素絢閱讀 213評論 2 6