科學&紙上談兵&前端技術方案怎么寫
科學的分析方案文檔的利弊
貓會喵喵，狗會汪汪，雞會什么？
機會留給有準備的人。
先說點虛（?）的，等我們的需求或者項目出名了、別人需要學習需要你給出一波裝逼Time的時候，丟出一個圖文并茂的設計文檔。肯定比丟一個代碼倉庫獲得的敬仰多吧？
或者說點實在的等回頭職級評審的時候，一個復雜的需求你都想不起來怎么設計的了還得現畫流程圖貼代碼貼效果......（噓?。?/p>
掌控力
先說說對個人成長的意義，
往日我們提到前端最大的優(yōu)勢 -- 所見即所得。
要說這確實上手門檻低，比起客戶端的編譯動輒一根煙（就目前來說咱們客戶端需要一個小時編譯，一包煙都抽完了）。服務端部署還要上云要滾動來看，前端的試錯成本實在是太低了，這是一個巨大的優(yōu)勢，特別是在試水的時候。
如果用一個模塊的開發(fā)比作一道考試題，我觀察過一些同學（當然包括我自己）都是寫幾行切一下屏幕看看情況，但那就好比推導寫完第一行就去對標準答案一樣。獲得的是很碎片化的思路，長期這樣少了一些 “服務端式” 的錘煉，對較大的模塊或是復雜場景就很難在腦海中形成一個比較清晰的響應。
技術方案可以在一定程度上起到強制大家先想好再寫的作用，補上這部分練習。時間久了貌似就能發(fā)現自己能在腦子里推導整個代碼的運行狀態(tài)了，這樣bug率就會自然而然的低下來，也更容易做出一些前瞻性的設計。
當然我最初的想法其實只是留下一份好得設計文檔可以供以后維護代碼或者需求或者方案的人能夠知道最初的開發(fā)者到底是怎么思考的，如何設計的。以及有哪些隱性的問題可以從文檔中找到答案，讓開發(fā)人員的心智負擔更低。但近一段時間的思考和詢問讓我覺得上面這些問題也有必要說出來。但是否需要先寫文檔再繼續(xù)開發(fā)這點我覺得到要看具體的落地場景。
試錯
俗話說，船小好調頭。
我相信大家一定都有這樣的經歷：比如我們需要寫一個精巧的多模塊重業(yè)務的組件。
一開始模塊劃分非常合理，狀態(tài)傳遞井井有條，然后QA提了一個BUG，在X條件下X元素的位置沒有對齊，于是需要補一個透傳鏈路傳到某一個sub組件里，或是Sub組件需要一路開回調開到頂層之類的?；蚴悄阍O計了一個完美的組件，然后PM說，我需要在X條件下加一個X元素位置在X坐標，并在后續(xù)的一個月時間內增加了Y、Z、α、δ.......
當然這還算好得，更坑爹一點的是，可能開發(fā)末期發(fā)現， 誒？？我怎么特么不把這幾個組件抽成一層讓他來負責 XXX 然后集中在 XXX 里 XXX 呢？------ 算了來不及了等下次重構吧 、 下個需求在重構吧 、這特么這么多東西重構成本太高PM不會同意的 就這樣吧。
有了更好的思路，卻因為時間和工期卡點的原因無法訴諸實現，只能被迫補丁上線的感覺，相信我這并不好受。打開beetle看看上線分支，序號都快四位數了？
而方案就能很好的避免這一切，比如在方案進行的過程中發(fā)現了這個問題，可能還沒到模塊設計階段，后面直接就按更好的方向去設計了，或者只是改幾個圖就行。因為還沒進入Coding階段，進行大塊的調整，一般都沒什么風險，就算真有，如果在項目前期提出 叫“風險”，在項目末期提出那就變成“事故”了
當然文檔不是萬能的，我相信這世上不存在一勞永逸的事情。但我相信這能避免大多數此類問題，能減少多少會隨著代碼掌控力的提升同步提升。具體怎么做會在下述中展開。
回憶
- 溝通成本與記憶成本
隨著業(yè)務復雜度的提升，能夠單打獨斗的項目會越來越少，更多的項目會要求大家合作進行（后端合作也是合作-不是），也有很多時候會隨著時間推移加入進來共同開發(fā)，此時有個文檔給新同學介紹，起碼能節(jié)約本人70%的口舌吧。（特別是我們作為開發(fā)人員口舌也不是特別好得情況下，應該也沒人愿意一整天給新同學講解吧。）
在剛開始的時候，凡事兒寫文檔里再說確實會在短期內提升溝通成本，但是隨著開發(fā)進度過半，大家的記憶力開始逐漸衰退的時候，開頭寫的方案可以起到的喚醒記憶的作用就會逐漸凸顯。
- 代碼之外的額外信息（我認為目前最重要的部分）
從代碼中，大部分時候我們只能看到他做了什么事情，但是“不做的事情” 其實也是很重要的信息。比如有時候看代碼你可能會疑惑，這里怎么不做個緩存呢？這里怎么不加個回調呢？這里為啥......
不做的事情無法通過代碼本身來傳達，但是如果在方案中有討論，并記錄。就可以很好的解答這部分的疑惑。并且也可以在方案中宣講自己設計的動機，不僅講 what 還講 how，加深參與同學的理解，降低這個同學的心智負擔。就可以避免你設計的精美的模塊被來支援的同學隨便加了個跨組件的回調，再被后來入職的萌新同學濫用導致最后變成屎山。
When i wrote this, only God and I understood what I was doing.
Now, God only knows
套路化的文檔解決方案（當然這是我的套路 - 一家之言）
其實這個也是一篇文檔，也能看出我的性格和風格是比輕松而無拘無束的，（你以為我是瞎寫？其實我就是瞎寫的。瞎寫又不用有負擔.jpg）
方案文檔通常要包含一些必要信息，只要信息到位了，章節(jié)標題我認為可以隨意發(fā)揮。
簡單來說就是：
- 我要干什么
- 我要怎么干
- 我為什么要這樣干（我為什么不那樣干？）
- 當然還有我比較關注的：你是不是有啥坑需要標注一下。
那我們就娓娓道來，這幾部分應該如何展開。
我要干什么?
這一階段我想把他稱之為 需求分析， 隨著我們的level提升，對語焉不詳的需求的承接能力需要一個提升。
明確產品的需求
萌新階段，產品：“抄這個”，這種需求要我我肯定懟回去了。（其實我沒膽子懟，都是鈺哥懟的）。但是很多時候對于一些復雜場景并不是產品自己可以hold住的，也會提前接觸部分技術同學進行預研，我們需要把產品不明確的需求轉變?yōu)槊鞔_的需求，進而轉變?yōu)榧夹g描述的需求。
在小風還沒走的時候，他經常問我一些問題，大部分都是這種情況。當然我感覺我已經鍛煉的還可以了。
比如“抄這個” 這種需求，我們就可以進一步追問來獲取更多細節(jié)（其實想想我做的也不好，我大部分說的都是 都可以做排期就行了，但其實我沒概念。），到比如“你是不是想抄他的這個布局機制，為了這個機制有這樣的利這樣這樣的弊，我們可以這樣這樣，你看怎么樣”，這時候我們的段位就高起來了。也能更好的讓我們有更多機會去接觸產品設計，讓技術更多的融入產品。這一過程是一方面是協助產品明確自己想要的東西到底是什么，另一方面也是幫你自己減少后續(xù)風險點。
拆解為技術點
明確了產品的訴求之后，我們就需要再把產品的需求轉變?yōu)榭梢员患夹g描述的需求。并且先給定優(yōu)先級，有些需要取舍的場景可能會需要這個。
拿之前奢侈品的篩選需求來舉例子，大概就能拆成這么幾塊。
- 產品想要一個通用的篩選組件（基礎能力）
- 產品想要在這個通用的能力上大有作為做一大堆事情，期望能把配置化做好，能提供解決產品各種各樣稀奇古怪的要求的能力。（明確要做到的技術點）
我要怎么干，我為什么要這么干？（上）
一般寫方案文檔有兩種情形
- 我基本已經有了較為明確的思路，我需要論證他的可行性。
- 我是誰，我在哪，我怎么就tm接了這個活？這玩意兒咋做？毫無思路！
對于第一種，我認為，我思考這個問題的時候已經有了大致思路，接下來就是在紙上進行推演，避免落地后翻車。這種暫時先不展開，后邊會討論到。
那第二種對于一個無從下手的方案，我該如何展開呢？
我認為該有這么一節(jié)：【方案思路】
怎么說呢，寫方案之前肯定也沒啥思路，但是隨著這一節(jié)的討論，我的思路會逐漸清晰，我完全明白應該怎么做了?。ㄆ鋵嵨乙矝]經歷過這一步，后續(xù)的技術需求可以這么搞。）
梳理核心鏈路
大多數調研類需求都會涉及一個“如何打通XX”的問題，這樣的需求大多可以歸納成為一條或多條核心鏈路，然后圍繞著如何確保核心鏈路順利運轉來展開。所以對于這類需求，第一件事：先畫流程圖。
以我之前做過的停留時長來舉例 - 需求是停留時長，停留時長是怎么被計算的呢？這一套鏈路是什么。如果需要多端適配，那么每個端的這套鏈路如何被打通呢?
組件設計類方案則不一定會有如此顯著的流程圖，可能更注重模塊劃分，比如比較復雜的頁面有20個組件，他們之間說是相互獨立但又有微妙的聯系，不過即便如此，也并不是沒有核心鏈路， 可能是需要提煉。（這一點在和浪總多次的希望zzui能夠提供一些組件時能很好的體現，我們并不能給浪總說我這個需求是啥，而是需要提煉一下，我需要zzui提供一個什么樣的組件，他需要有什么樣的能力，和一個什么樣的API讓我使用。）
這里可能也有一些經驗層面的判斷在里面，如果大家要是拿捏不準我覺得可以拋出來大家討論一下。
舉個例子吧
- 比如篩選組件，核心在于 - 多組件之間的聯動和數據解析。
- 比如停留時長，核心在于 - 計算之后的數據應該在什么時間節(jié)點發(fā)送且數據如何保存。當然這還伴隨著多端兼容的問題
篩選組件的核心鏈路
細化流程
確定了核心鏈路之后，就需要進一步細化了。怎么細化呢？- 靠捫心自問。
我和一位大佬聊天的時候聽他講過信息論的一些東西，最讓我印象深刻的叫做：“信息是不確定性的減少”。什么意思呢？比如我現在有一個比較復雜的需求，還需要server的同學提供一些能力。我需要盤一下手頭的信息，然后整理一波，問問自己要做這個事情還差什么。（到目前為止主要差時間和想法）
比如前期：
- 是不是要用到一些奇奇怪怪的知識點？比如webRTC、webSocket之類的，我不會？怎么辦？，那方案里標記一下我不會（然后學）
- 比如用到一個第三方的庫或者解決方案，怎么用？不知道。得去看一下。
- 怎么對接服務端？不知道，需要問服務端的兄弟或者讓他們給出文檔。
然后上面第一輪問題問了一遍，繼續(xù)問自己第二輪
- 我和server端的鏈接是否是穩(wěn)固的？斷線了斷網了咋整？
- 服務端和RTC穩(wěn)固嗎？？
類似這種問題，當然第二點貌似看起來不需要我太去關心，但是我認為還是問一下比較穩(wěn)妥。萬一這個問題去問服務端的同學說不定他們沒想到但是被你提醒以后風險-1
那還可以換個方向問
- 前端會出現什么意外需要處理嗎？
- server端會出現什么意外，導致我需要處理嗎？
這些疑問又會讓我們催生出更加完整且有強度的設計。
還有一些常規(guī)問題。
- 這套方案的api該怎么設計。我需要讓別人怎么用，接入成本小一些？
- 如果方案過于復雜是不是這套方案就行不通？是不是該放棄這個想法？
類似， 總之就是不斷給自己的方案挑刺的過程，用一輪一輪的badcase來惡心自己，看看自己的方案能否扛住。
就我之前停留時長的經歷來說，我對于走一步看一步的實現感到非常的畏懼。一遍一遍的寫出來卻遇到了各種各樣的問題非常折磨人，而且代碼一遍一遍的改，到后邊根本就不在意代碼怎么組織了，只想快點完成這個任務。
經過一輪又一輪的“捫心自問”，我們會發(fā)現一系列的不確定性的東西正在漸漸變少，以往這些沒想明白的點在項目中后期會表現為風險，這個項目可能就會相對穩(wěn)的多。
我傾向于用問答的方式來維護這些問題， 確保是能得到解答的。當然我這個是在最后QA環(huán)節(jié)。當然也不是所有問題都能找到答案的，解決不了的，那就只能找leader或者拋出來一起討論了。
最終，所有的問題都得到了解答，或者有了臨時方案頂替不至于捅婁子。那這個方案就八九不離十了。接下來我認為就進入到下一個階段，模塊設計了。
我要怎么干，我為什么這么干？（下）
同樣的標題，用了兩次，是因為這兩部分很多時候是混在一起的起碼是掛鉤的，所以大部分時候他倆都是寫在一起的。至少我貌似就是寫在一起的。
比如，我可以方案思路之后直接形成完備的模塊劃分方案。
那模塊劃分到底是什么呢？前半截的思路部分，其實是挖掘出需求的全貌，降低不確定性，提升技術性。而這里的模塊劃分，則更偏向于代碼組織，確保設計的良好，可行的落地方式。
舉例來說，思路一節(jié)里發(fā)現我們要做的事情有 A,B, CDEFGH。這要這些事全做了，基本這個大需求就穩(wěn)了。但是落地上肯定不能函數套函數塞進一個文件完事對吧。那其實我們需要一個邏輯層面的劃分。
我們把每個即將分配的模塊都視為一個個的工人， 我們接下來就需要把之前的ABCDEDF分配給這些人。那怎么分呢？這個就很藝術了，基于每個項目的具體情況都有極大地側重點的不同。這個就只能具體項目具體分析了。
舉個例子吧，對于奢侈品來說大部分的能力是通用的，所以奢侈品的組件需要盡可能的通用。但游戲的需求可能更多更靈活，更流程他就更需要更靈活的組件，等等。而且我們應該保證一些指標，比如現在在提的加載速度優(yōu)化。（我之前設計篩選的時候就沒有顧及到這個）
模塊劃分需要有多細呢？
其實把主要的一些大塊拆出來，能維護就行了。咱們的需求也沒有大到那么離譜，還記得我前幾個月說的compositionAPI嗎？hooks拆起來啊 同學們！
紙上談兵到運籌帷幄
其實我說了這么多也在紙上談兵，對于我之前踩到的坑來說，我覺得我可以提供一些想法。
快速展開
首先，寫方案并不是線性的。并不是思路完全好了以后在去寫方案，因為前面也提到了試錯，其實在方案上掉頭的成本還是挺低的。先列出來一堆問題，在去一個個解決把他們都記下來其實方案就寫好一半了。
高效傳達
圖片 >> 文字
我們都知道視覺的傳達比文字更容易理解，所以引入更多的圖，引入更少的直接代碼，都可以很好的幫別人理解你的方案，而良好的圖也可以更好的組織自己的語言。
這也是為什么我認為用飛書寫文檔會好一些，因為dashen畫圖的體驗實在是太差了。差到極致了！
這里其實還有個題外話，以前我畫圖感覺很有包袱，比如流程圖必須圓角矩形起止，菱形判斷節(jié)點，（都是大學論文害的。）但是我的一個好朋友幫我破除了這個包袱，whatever，我覺得重點應該是抓住核心：傳達信息， 只要把想傳達的信息傳達到位了，圖其實丑一點都無所謂。而且不用嚴絲合縫的畫圖其實真的挺快的。我上一篇例子文檔的3張圖我原本以為要畫幾十分鐘，結果10分鐘3張都畫完了。如果不是什么正式場合，這種非標準的圖我覺得大家都可以隨便畫畫，意思到位就行了。不需要有那么多負擔。
顏色的使用（構想）
畫圖的時候如果有什么側重點，可以用顏色的變化來解決這個問題。（當然我覺得這個可以當做職級評審時的一種手段？？）
我覺得效果還是挺明顯的，不過這里有一點，顏色應該相對少。因為 都突出 = 都不突出了
回收驗證
在方案完畢，開始進行開發(fā)以后，也不是把方案就丟一邊了。我覺得應該在適當的時候打開方案再看看當時是怎么想的。
- 一開始我說了對答案的故事？在開發(fā)中也能驗證自己的方案設計水平。
設計模塊是否按預期落地了？差別有多大？為什么？
選擇性寫方案/重復利用
并不是每個需求都要寫方案，一些小需求排期在1、2天我覺得就沒有必要寫。方案應該對應的是一些自己不能拿到需求就清楚那些東西該劃分成什么樣模塊需要怎么寫的時候才需要寫文檔。
當PM反復在對一次設計的文檔中的內容反復進行迭代時，我們應該基于該文檔去維護，而不是重寫。這樣也能在重復整理的過程中更加清晰的認識這套需求是如何運作的，且方案在重復修改的過程中，也能知道未來對于該項目如何進行重構。（找到優(yōu)化點進行優(yōu)化、是否能更加自動化......）
總結
-- 設計階段 --
- 明確產品需求 背景和為什么寫清楚。
- 為了完成這個需求我們具體要做哪些事情。
- 梳理核心鏈路，這一套實現的核心鏈路流程是怎么樣的。
- 把鏈路的各個節(jié)點細化一下，具體我們需要如何實現這個節(jié)點。
-- 項目組織階段 --
- 把實現各個節(jié)點的抽象邏輯細化到模塊圖。我們如何組織這個節(jié)點。
- 方案并不是一蹴而就的，他可能是伴隨著你的開發(fā)而編寫的。
- 開發(fā)完以后回頭拿方案驗證一下落地效果如何，和方案有什么偏差，在去把方案修正一下這就是一份存根文檔。
- 當這個需求有迭代或者功能追增的時候，這個文檔就是你下一篇方案的起點。
PS：過程中遇到各種各樣的意外問題，或者一些不尋常的坑記得備注。不僅要寫how 還要寫why
什么樣的需求需要文檔呢？
舉個例子：
- 這個需求需要長期維護
- 這個東西他有一定的復雜度，他不容易直接從代碼中能窺見整個需求的全貌。
- 這個東西需要提供給第三方使用。
- 這個東西需要各端協作，有依賴除業(yè)務側技術外的其他關聯，如中臺 搜索等。
就這么多~ 大家有問題可以討論下。我在這里只是提供了我的一些思路。文檔這個事情我不能要求大家去寫，我提出了一些問題，也提出了這個解決辦法。希望大家在遇到上述問題時能用方案文檔的解決方案來解決。嘔心瀝血之作！希望大家輕噴～～
