大廠技術(shù)??高級前端??Node進階

點擊上方?程序員成長指北，關(guān)注公眾號

回復(fù)1，加入高級Node交流群

前言

百度百科對計算機軟件的的定義為：“計算機軟件( Software，也稱軟件)是指計算機系統(tǒng)中的程序及其文檔，程序是計算任務(wù)的處理對象和處理規(guī)則的描述；文檔是為了便于了解程序所需的闡明性資料。程序必須裝入機器內(nèi)部才能工作，文檔一般是給人看的，不一定裝入機器”。

可以看到概念里提到了"文檔"，說明寫文檔是軟件開發(fā)過程必不可少的一個環(huán)節(jié)，如果文檔沒有寫好，那么軟件也不能算是優(yōu)秀的軟件。

可對于一般軟件開發(fā)人員來講，寫代碼要比寫文字容易得多。很多時候我們都能看到類似的事情，項目做完了，設(shè)計文檔還沒有；當別人問起，某個功能當時為什么這么設(shè)計，一時語塞；項目代碼里沒有注釋，時間長了，自己都忘記當時代碼為什么要這么寫；當接手別人的項目的時候，要排查個問題只能一行行讀代碼，唯一的文檔就是隨腳手架自動生成的?README.md。以上這些都是我們平時開發(fā)中可能會遇到的問題，為什么會這樣？其實就是因為平時沒有寫文檔的習(xí)慣，文字沒有得以保留，只靠記憶，時間長了確實記不住。

下文就想和大家一起探討一下，前端為什么寫技術(shù)方案，怎么寫前端技術(shù)方案。

寫技術(shù)方案目的

在講為什么要寫前端方案文檔前，先講一個我的好朋友小明的故事。

小明也是一個前端，在接到需求的時候，他會大致看一下需求文檔，感覺沒有什么太大的問題，然后就看看交互、視覺稿上有哪些頁面，接下來就開始迫不及待地寫代碼了。

新建一個文件、寫模板、寫樣式、寫交互邏輯，一氣呵成。新模塊的需求是小明最喜歡的，因為不用去理解其它功能的邏輯，可工作中還是少不了維護歷史代碼。小明很聰明，他發(fā)現(xiàn)有個功能加個參數(shù)傳過去做個邏輯判斷就能實現(xiàn)，于是他也就這么做了。

開發(fā)完后，小明覺得很滿意，因為很快就實現(xiàn)了需求，代碼在腦中的邏輯比較清晰，里面也許有些地方寫的不太妥當，但是也無妨吧。雖然不是全局最優(yōu)的，但可以說是局部最優(yōu)的。

版本提測之后，QA 開始針對各種邊界問題和極端場景給小明提 bug。譬如輸入框輸入?emoji?表情后提交接口報錯、按鈕連續(xù)點擊觸發(fā)了多次請求、買家角色頁面展示正常但是供應(yīng)商角色展示錯誤……

在改 bug 的過程中小明漸漸帶上了痛苦面具，代碼邏輯被改的支離破碎，不得不為代碼打各種補丁，方法的參數(shù)加了一個又一個，邏輯里的條件判斷加了又加。到這個時候小明的開發(fā)積極性已經(jīng)被消磨的差不多了，開始對 QA 提出的 bug 表示質(zhì)疑，他會用“原來就是這么設(shè)計的呀”、“這個問題不在這次的需求范圍內(nèi)”等等這樣的說辭來避免對代碼的更改。

過了一段時間，小明又接到一個需求，需要對上次開發(fā)的模塊增加一些功能。翻開代碼的時候，小明整個人都崩潰了。以前代碼的邏輯自己早就忘記了，面對自己已經(jīng)看不懂的代碼，開始對自己進行靈魂拷問“這個方法有什么用？這個方法怎么有這么多參數(shù)？為什么邏輯這么復(fù)雜？”，“代碼在不同頁面之間跳來跳去，還有長得幾乎一模一樣的代碼，他們的邏輯到底是什么樣的？”，“為什么會有這么多標識位，這么多魔法數(shù)字，他們都是干嘛的？”。注釋什么的是不存在的，即使存在，也不明白在講些什么。

剛接手項目的時候小明還不斷吐槽之前開發(fā)的人不寫文檔、不寫注釋，沒過多久小明也成了別人口中的那個"他"。

以上故事根據(jù)真實事件改編。

我覺得寫技術(shù)方案文檔是能解決小明的一部分問題的，“謀定而后動，三思而后行”，都是在說這個道理。當然寫文檔也不是萬能。對比一下后端，會發(fā)現(xiàn)他們在寫代碼之前都會做方案設(shè)計，好像難道后端的開發(fā)時間很充裕或者說前端的技術(shù)方案不值一提嗎？肯定不是。方案設(shè)計是軟件工程里的一個最佳實踐，通常做技術(shù)方案的過程中會體現(xiàn)出軟件整體的架構(gòu)，當對核心流程梳理完成之后，最后基本都能落實到代碼上。也就是說好的技術(shù)方案能體現(xiàn)出最后代碼的邏輯，通過看方案就能知道代碼怎么寫。這樣就防止了在寫代碼過程中邊寫邊改，最后導(dǎo)致代碼結(jié)構(gòu)混亂的問題。

怎么寫技術(shù)方案

如果我們按照后端那一套方法論和模板來做前端方案設(shè)計，發(fā)現(xiàn)根本寫不出來什么內(nèi)容，這時候我們要重新審視方案設(shè)計的套路，來發(fā)現(xiàn)前后端的不同。

業(yè)務(wù)模型可能前后端都是一致的，畢竟我們是解決同一個業(yè)務(wù)問題。但其中也有稍許差別，前端有些數(shù)據(jù)不是從后端獲取的，或者說不一定非要從后端獲取，這點我們需要在做設(shè)計的時候考慮進去。譬如同一個 H5 頁面在微信公眾號內(nèi)和釘釘內(nèi)需要展示不同的主題色。

前后端對于核心流程的定義也不同，對于后端來說核心流程是數(shù)據(jù)的產(chǎn)生、流轉(zhuǎn)、消費，但是提到流程，在前端來說更多的是頁面的流轉(zhuǎn)、組件的交互、用戶的操作。同樣一件事情，在前后端來看完全是兩個東西，比如保存一項數(shù)據(jù)，后端需要關(guān)注的可能是如何校驗、如何存儲、如何索引、如何關(guān)聯(lián)。但前端要關(guān)注的卻是校驗接口的出入?yún)ⅰ⑿ｒ灲Y(jié)果的展現(xiàn)形式如何、是跳轉(zhuǎn)還是覆蓋或者彈窗、不同屏幕和設(shè)備下如何適配。

后端更注重邏輯架構(gòu)與部署圖，因為后端需要為服務(wù)化，服務(wù)間邊界的定義要非常清晰、具體。前端與微服務(wù)對應(yīng)的，應(yīng)該就是組件了，但是組件覆蓋的范圍太廣，從一個按鈕到一個頁面都可以稱之為組件，甚至現(xiàn)在比較火熱的微前端中的一個子應(yīng)用也可以成為一個組件，所以前端的組件需要被劃分成頁面、模塊、控件等不同封裝層次的單元。在這個劃分的過程中，邏輯架構(gòu)自然體現(xiàn)出來了。同時前后端解決的問題不同，導(dǎo)致關(guān)注點也不同，前端需要關(guān)注頁面的還原，比如頁面的元素應(yīng)該如何抽象，樣式應(yīng)該如何復(fù)用，這個是后端不用考慮的。

接口可不僅僅是?http?請求，任何與其它模塊交互邏輯都應(yīng)該明確其入?yún)⒑统鰠ⅰ：蠖诵枰P(guān)注暴露出去的?dubbo?或者?http?接口，因為這體現(xiàn)了系統(tǒng)間交互的邏輯。而對于前端來說對應(yīng)的也應(yīng)該明確獨立模塊或者頁面之間的交互邏輯，所以也就需要明確這些"接口"。

關(guān)于實施方案，前后端的關(guān)注點也有稍許不同，后端更關(guān)心系統(tǒng)之間的集成，舊數(shù)據(jù)的兼容。而前端應(yīng)該關(guān)心的是桌面設(shè)備和移動設(shè)備的區(qū)別，或者微信、支付寶等不同渠道的集成。

對比之后前端技術(shù)方案的脈絡(luò)漸漸清晰起來。結(jié)合上面的方法論，下面就實際案例講解一下。

技術(shù)方案的案例

在政采云產(chǎn)研團隊的研發(fā)流程中，前端方案設(shè)計是在需求和交互評審之后、測試評審和正式開發(fā)之前，屬于需求階段和開發(fā)階段的中間節(jié)點。此時需求的功能和用戶交互場景基本已經(jīng)確定，前后端技術(shù)方案之間互相補充描述清楚需求的可行性、整體架構(gòu)和具體實現(xiàn)。同時在測試分析之前，也是幫助 QA 梳理測試重點和用例場景。

第一章，概述。?一般會簡單描述項目的背景和價值，做一件事情的意義或者說動機是很重要的，一般從需求文檔里進行概括即可。然后解釋后面文檔中需要用到的一些專有名詞，達成大家對一些名詞的共識是很重要的。

第二章，相關(guān)文檔。?收集版本開發(fā)的相關(guān)文檔，這樣開發(fā)的時候只要通過這一個前端技術(shù)方案文檔，就能找到所有的文檔，有時候我也會把這些網(wǎng)頁整理到一個瀏覽器書簽文件夾里。

第三章，任務(wù)拆解。?主要描述開發(fā)任務(wù)歸屬、預(yù)計工時，還有里程碑。

估時是按照頁面維度，拆分頁面內(nèi)主要功能，進行時間估算，時間估算按照靜態(tài) demo 和 JS 交互來分別評估會準一些。之后得出時間乘以一個 1.3 的系數(shù)（因為每周還會有不同的會議、溝通也會占用時間）。

時間評估的時候，像下圖一樣，本地花點時間列一下 —— 這樣的好處是一便于統(tǒng)計和比對，看有無遺漏；二評估出的時間，給到業(yè)務(wù)方、PM 等，會對我們有職業(yè)化上的認可——會認為這樣的評估粒度，時間是準確的你這個人是靠譜的；另外，細粒度的維度，也便于業(yè)務(wù)方尋找需求最長路徑，看需求或者走迭代也方便做出判斷。

第四章，總體設(shè)計。?列舉開發(fā)規(guī)范，還有邏輯架構(gòu)。一圖勝千言，有關(guān)時序的邏輯強烈建議用圖來代替。流程圖、時序圖、狀態(tài)圖，讓你的技術(shù)方案文檔逼格滿滿清晰明了。

下圖為頁面跳轉(zhuǎn)邏輯圖，如果交互有缺失的話，前端技術(shù)方案里可以進行補位

第五章，詳細設(shè)計。?這一章就是整篇技術(shù)方案的重點了，包括功能說明、流程說明、模塊詳細設(shè)計、外部依賴等四個小節(jié)。

最完美的狀態(tài)，就是如下圖所示，這一部分寫完了，代碼也躍然于紙上了。

下圖為下單流程卡券選擇時序圖。復(fù)雜的時序邏輯已經(jīng)不是文字能說的清的了，時序圖讓交互更清晰

下圖為前端組件入?yún)⒃O(shè)計的案例，開源組件庫寫的都不錯，可以直接參考。

最后三章可以寫一寫技術(shù)分析 Checklist、測試數(shù)據(jù)、遺留問題

最后附上政采云前端團隊的前端技術(shù)方案模板，戳這里 (https://staging-gov-open-doc.oss-cn-north-2-gov-1.aliyuncs.com/1072PT/339900/10006126128/202110/dfa4e4a2-8b3c-4372-b002-9d6f701d5f40)。當然大家也可以根據(jù)自己的情況進行內(nèi)容的增刪，譬如我們原本是在技術(shù)方案里維護發(fā)布的 CheckList，但是后端也維護了一個，我們就索性建了一個公用的文檔，歸檔在一起。

最后的最后推薦兩個好用的畫圖工具：

• plantuml (https://plantuml.com/zh)：使用簡單的文字描述畫 UML 圖
• drawio (https://www.draw.io)：在線圖標繪制網(wǎng)站 上面兩個工具都有對應(yīng)的 vscode 擴展。(processon (https://www.processon.com) 也挺好用的，可惜免費版只能存 9 個圖表)

我組建了一個氛圍特別好的 Node.js 社群，里面有很多 Node.js小伙伴，如果你對Node.js學(xué)習(xí)感興趣的話（后續(xù)有計劃也可以），我們可以一起進行Node.js相關(guān)的交流、學(xué)習(xí)、共建。下方加 考拉 好友回復(fù)「Node」即可。

???“分享、點贊、在看” 支持一波??

總結(jié)

首先得承認一個事實，寫文檔和寫作一樣是一件很費時費力的事情，為了畫一個流程圖、為了斟酌一個詞語，可能就會糾結(jié)好久。其次文檔是需要持續(xù)更新的，不是技術(shù)評審開完就封版了，視覺評審、測試分析評審、后續(xù)迭代都有可能影響技術(shù)方案，需要實時跟進。如果能把產(chǎn)品各個版本的技術(shù)方案文檔進行整合，甚至能得到整個產(chǎn)品技術(shù)方案的全貌。

欲速則不達，很多人覺得技術(shù)方案是在延長開發(fā)周期，其實在政采云的落地過程中發(fā)現(xiàn)，技術(shù)方案設(shè)計的越詳細，對質(zhì)量提升，和維護成本降低效果明顯，拉開很長周期來看，是加快了迭代周期。

李開復(fù)老師在《浪潮之巔》的序言中說到：“我認識很多頂尖的工程師，但具備強大敘事能力的優(yōu)秀工程師，我認識的可以說是鳳毛麟角”。表達是軟件開發(fā)工程師重要的軟實力之一，作為軟件工程的最佳實踐，方案設(shè)計在前端開發(fā)過程中還是十分必要的，那么為什么前端領(lǐng)域長時間不注重這個事情呢，我覺得有以下原因：

• 方案設(shè)計依賴技術(shù)能力，而前端技術(shù)棧變化太快，今天的設(shè)計套路放在明天可能就失效了；
• 前端業(yè)務(wù)變化太快，經(jīng)過半年的迭代之后，可能第一版的方案就反應(yīng)不出現(xiàn)有代碼邏輯了；
• 前端的業(yè)務(wù)流程、交互流程比后端復(fù)雜太多，而且可復(fù)用性差，需要花費大量時間去思考和整理，而且對抽象能力有比較高的要求；
• 前端開發(fā)效率高，不會有歷史包袱，有時候直接重寫的效率反而更高；
• 后端上在語言和 IDE 對重構(gòu)的支持遠比前端好太多；
• 后端比較成熟了，比如常見的 mvc 分層都幾乎是約定了，前端要不要 model 層，要不要 service 層都是要討論的，要不要 redux，redux 存什么數(shù)據(jù)，每個人的理解不一樣的；
• 前端人員的抽象思維和工程化能力總體還是比后端弱的；但是這些原因其實都不是我們不做方案設(shè)計的理由，方案設(shè)計是個結(jié)構(gòu)化思維的過程，他不光是能讓項目更好執(zhí)行，也能提升開發(fā)者本身的架構(gòu)能力和宏觀意識。我們要把自己做的東西展示出來，不光展示給同行看，可能還要展示給其他崗位上的工作人員看，甚至展示給用戶看。如果我們只是會寫程序，不會在文檔中恰當且優(yōu)雅地描述自己的想法，那么就真正的成為“碼農(nóng)”了。

所以，同學(xué)們在平時開發(fā)的時候多想一想如何做設(shè)計吧。