在筆者所在的前端研發(fā)流程中, 【技術(shù)調(diào)研及方案設(shè)計】屬于連接【需求階段】和【開發(fā)階段】的中間節(jié)點。在需求詳評(三審)后了, 需求的功能和交互已經(jīng)基本確定, 而在實際進入開發(fā)之前, 還有一些 待確定的技術(shù)要點需要補全, 這些要點包括:

• 需求的可實現(xiàn)性 (理論上能不能做, 是否能支持某個功能, 某個交互是否能實現(xiàn), 實現(xiàn)功能的成本是否過于巨大),假設(shè)你給PM拍胸口說啥功能你都能實現(xiàn), 然后Ta提了一個這樣的需求^[1]...

• 需求的整體架構(gòu)(前后端交互的流程和方式, 接口的路徑、請求和響應(yīng)參數(shù))

• 需求的具體設(shè)計(前端頁面/組件/服務(wù)的設(shè)計)

而編寫前端設(shè)計文檔就是補全和完善上述這些技術(shù)要點的過程以及過程沉淀出的產(chǎn)物.

為什么寫前端設(shè)計文檔?

Measure twice and cut once 三思而后行

如果所有產(chǎn)品的功能都是在頁面上展示Hello, World的話, 那么我們大概是不需要設(shè)計文檔的，然而現(xiàn)實世界的產(chǎn)品需求功能充滿了復(fù)雜性, 一個頁面可能展示了非常多不同來源數(shù)據(jù), 有不同的交互細節(jié), 周密的業(yè)務(wù)流程, 這就要求我們需要在動手開發(fā)之前先想好這個功能能不能實現(xiàn)以及如何實現(xiàn).

試想一下如果不寫設(shè)計文檔, 擼起袖子就開干可能會有哪些Bad Ending?

• Case 1: 需求要你接入一個第三方SDK, 你和第三方的研發(fā)同學(xué)開了個小會對齊發(fā)現(xiàn)沒有啥問題, 你沒有做詳細的技術(shù)設(shè)計印證是否SDK能完整支持需求, 也沒有測試過SDK, 結(jié)果開發(fā)到一半發(fā)現(xiàn)SDK的功能不能完整支持你的業(yè)務(wù)需求, 如果要支持必須得第三方排期支持, 而這個項目本來預(yù)計要盡快上線的, 你人傻了 (First Blood??）
• Case 2: 需求中的一個功能需要你同時請求多個接口, 你沒有充分考慮這些接口失敗的容災(zāi), 對這些請求的返回聽天由命, 結(jié)果上線后用戶在使用中經(jīng)常遇到一個接口請求成功了, 另一個失敗了,造成數(shù)據(jù)不一致, 用戶反饋功能不可用, 你人傻了again (Double Kill!??)
• Case 3: 需求中需要開發(fā)一個彈窗, 你匆匆一瞥覺得這也就半天就能開發(fā)完, 結(jié)果沒有充分考慮到這個彈窗有五個模式三個形態(tài)八種流程, 低估了2/3的排期, 排期到了QA催促為什么還不提測, 匆匆做完測試之后出現(xiàn)了一堆Bug, 你人傻了one more time (Triple Kill!??)

我是三傻·史塔可嗎?

而設(shè)計前端文檔, 就是盡快能在開發(fā)之前將技術(shù)上不確定的點確定好, 將需求的設(shè)計方式提前構(gòu)思好, 以減少后續(xù)開發(fā)出現(xiàn)風(fēng)險和問題的可能性.雖然技術(shù)文檔也不能100%預(yù)見或者評估出所有潛在的風(fēng)險和問題, 但是技術(shù)文檔能在相當程度上減少這類風(fēng)險.

除了通過設(shè)計文檔盡量避免上述的問題之外, 設(shè)計良好的前端文檔可以幫助你提升開發(fā)的質(zhì)量和效率, 原因如下:

• 當你書寫設(shè)計文檔時就像是在構(gòu)思文章的提綱, 一旦確定了代碼的整體架構(gòu)和組件結(jié)構(gòu), 你就有了構(gòu)建需求的藍圖, 而開發(fā)就是完成各種組成部分的細節(jié), 這比邊干邊想效率要高很多.
• 當你在設(shè)計時將代碼的架構(gòu)、類型、接口定義好, 開發(fā)時甚至可以直接復(fù)用設(shè)計文檔中的代碼
• 而當你完成設(shè)計文檔以后, 組內(nèi)同學(xué)或者其他合作方就可以了解你的設(shè)計, 幫助你判斷設(shè)計方案的優(yōu)劣, 了解你方案中對相關(guān)方的需求和影響, 可以更高效率的對齊技術(shù)信息.

如何寫好前端設(shè)計文檔？

既然編寫設(shè)計文檔可以更好的幫助我們在開發(fā)前階段進行趨利和避害，那么編寫設(shè)計文檔應(yīng)該是一件很有必要的事情了, 在這個判斷下, 我們新的問題是: 如何寫好一篇設(shè)計文檔?

筆者認為一篇合格的設(shè)計文檔應(yīng)該滿足至少幾個條件

• 內(nèi)容完備

• 設(shè)計文檔體現(xiàn)的是用你的大腦去完整執(zhí)行一遍需求流程的模擬, 它必須包含這個需求涉及到的全部環(huán)節(jié)、狀態(tài)與環(huán)境, 你需要考慮到你的上下游和你的關(guān)系, 你如何請求服務(wù)或者別人如何使用你的服務(wù), 你的頁面是在什么環(huán)境下運行(瀏覽器/Webview/CEF), 以及這些相關(guān)環(huán)節(jié)如果出現(xiàn)問題對你的影響, 如果有一種情況被你疏忽了, 那可能都是線上問題或者是事故的禍根;

• 在設(shè)計你的頁面和功能時, 你應(yīng)該把這個頁面或者組件的全部功能列舉清楚, 這些頁面或組件又有什么樣的狀態(tài)變化和交互, 只有把這些方面考慮齊全了, 才可能更客觀的評估工作量的多少.

• 此外, 在設(shè)計文檔中應(yīng)該收集齊開發(fā)需要的各類文檔和資料, 以提升查找所需信息的效率, 例如筆者團隊前端設(shè)計的文檔模版中會收集如下內(nèi)容

• 需求文檔
• 設(shè)計視覺稿
• 服務(wù)端IDL
• 第三方服務(wù)/SDK文檔
• 測試Case
• 埋點文檔
• 運營資源列表(optional)
• 走查及驗收文檔

• 結(jié)構(gòu)清晰: 合理且清晰的文檔組織能夠反映你良好的思考順序, 也便于他人理解, 筆者一般采用需求整體 - 頁面 - 組件/模塊這樣的層次去組織設(shè)計方案, 就像你在開發(fā)一個React/Vue頁面或組件, 也是先設(shè)計父組件, 再去思考組成它的子組件的功能(根據(jù)具體情況也可以先設(shè)計底層模塊和服務(wù)), 就如庖丁解牛, 如果你能對整體結(jié)構(gòu)和各個組成部分之間的結(jié)構(gòu)和邊界界定清晰的話, 相信你的代碼模塊化也會做的更好.
  

• 便于執(zhí)行: 一個理想的設(shè)計文檔應(yīng)該可以做到讓別人來看你的文檔也知道怎么實現(xiàn)需求(這個標準確實有些理想), 但是如果一篇設(shè)計文檔寫完你還是對如何進行開發(fā)毫無頭緒或者存在疑點, 那么這片設(shè)計文檔可能還不夠完善, 更好的設(shè)計文檔應(yīng)該就像是樂高或者宜家的說明書一下, 看著文檔你就應(yīng)該對如何操作了然于胸.

以上是一些關(guān)于設(shè)計文檔的理論描述, 下面讓我們關(guān)注一些更具體的細節(jié)

• 如果你要開發(fā)一個新應(yīng)用

• 創(chuàng)建新的Git倉庫
• 項目初始化
• 項目部署流程
• 接入監(jiān)控

• 如果你要開發(fā)一個新頁面

• 頁面的路由及相應(yīng)的query
• 頁面的整體功能與結(jié)構(gòu)設(shè)計

• 如果你要開發(fā)一個組件, 你需要思考:

• 一個頁面其實和組件的設(shè)計有很多共同之處, 他們都有三個組成部分

• State: 有哪些狀態(tài)? 本地狀態(tài)或需要通過接口獲得的狀態(tài)?
• UI: 用戶界面由哪些部分組成? 狀態(tài)如何驅(qū)動UI的變化
• Logic: 有哪些邏輯? 這些邏輯可以被歸類為若干類子邏輯(操作數(shù)據(jù)、事件響應(yīng)、調(diào)用服務(wù)), 這些邏輯會如何改變狀態(tài), 又如何響應(yīng)用戶的交互或者其他事件?

讓我們舉個??例子

以筆者遇到過的一個復(fù)雜需求為例, 這個需求的內(nèi)容接入用戶反饋的SDK, 并且在反饋的后臺系統(tǒng)看到這個用戶的反饋和用戶信息, 我當時的設(shè)計過程是這樣的:

• 首先在閱讀完需求文檔后，我們了解到這個需求大致有兩部分組成

• (1) C端需求: 在用戶客戶端/App里的頁面增加客服彈窗的入口
• (2) B端需求: 在客服后臺中, 當客服同學(xué)選擇某個用戶的會話時可以看到這個用戶的用戶信息/課程信息/訂單信息

• 讓我們在大腦中完整的跑一下從C端到B端的這個流程

• 用戶在C端提交反饋
• C端的客服 SDK 識別這個用戶的身份信息, 連帶提交的反饋信息傳送到客服的數(shù)據(jù)庫中
• B端的客服登錄以后能夠看到這個反饋信息, 并且能拿到這個用戶的身份信息
• B端客服可以在選中這個反饋會話后繼續(xù)查看用戶的用戶信息、訂單信息(學(xué)生)或課程信息(老師)
• 最終用一張流程圖來概括就是

有了整體的流程結(jié)構(gòu), 讓我們來思考一下其中關(guān)鍵環(huán)節(jié)的細節(jié)

• 客服 SDK 如何識別C端用戶的身份信息?
• C端用戶在登錄和不登錄時身份判斷的差異?
• B端如何獲得反饋者的身份信息
• B端的用戶信息/課程信息/訂單信息頁面如何實現(xiàn)? 是在客服平臺的工程開發(fā)還是使用iframe?
• 如果是iframe, 上面的三個頁面如何獲得反饋者的身份信息
• 經(jīng)過和客服平臺的討論和設(shè)計后, 設(shè)計方案才能確定

在把技術(shù)流程和方案確定以后，我們要開始對功能的實現(xiàn)進行具體的設(shè)計

• C端部分:

• 因為各個頁面的彈窗按鈕樣式和功能一致, 我們需要設(shè)計一個彈窗按鈕組件
• 彈窗按鈕組件底層調(diào)用了客服SDK, 所以底層需要設(shè)計一個客服彈窗服務(wù)模塊
• 在需要引入客服彈窗入口的頁面引入彈窗按鈕組件

• B端部分

• 因為決定在客服平臺植入一組iframe頁面, 所以需要單獨啟動一個獨立的倉庫, 需要進行一些配置工作
• 開發(fā)三個iframe頁面: 用戶信息 / 課程信息 / 訂單信息
• 當這些組成部分都清晰了, 我們才可以動手設(shè)計具體細節(jié)

當走到這里的時候, 需求的整體流程、前后端交互方式、以及具體功能實現(xiàn)可以說基本完成了, 這時候再開始動工就減少了技術(shù)上的不確定性, 開發(fā)思路也了然于胸中, 可謂是文思如泉涌，按鍵如有神??

當然, 即使是到了這一步也不能說是思考的終點, 在開發(fā)、聯(lián)調(diào)、測試、部署中還是可能會有意外事情的發(fā)生, 但是隨著你設(shè)計思路和實踐的逐步完善，這種意外會相對減少，即使發(fā)生你也能游刃有余, 總能夠保證需求高質(zhì)量、高效率的交付, 成為團隊信賴的小伙伴??

最后附上筆者團隊前端的設(shè)計文檔模版

1.需求背景及資源

• 需求背景

• 相關(guān)文檔 & 資源

• 需求文檔:
• 設(shè)計視覺稿:
• 服務(wù)端IDL:
• 第三方服務(wù)/SDK文檔
• 測試Case:
• 埋點文檔:
• 運營資源列表(optional):
• 走查及驗收文檔:

2.排期

需求Timeline

排期拆分

3.設(shè)計方案

整體方案

• 項目搭建
• 部署方案
• 監(jiān)控方案

頁面設(shè)計

• 頁面描述
• URL
• UI & 交互邏輯(UI拆分)
• 狀態(tài)
• 請求邏輯
• 業(yè)務(wù)邏輯
• 埋點邏輯

組件設(shè)計

• 模塊描述
• UI & 交互邏輯
• 狀態(tài) / Props
• 業(yè)務(wù)邏輯
• 埋點邏輯

公用模塊

• 模塊描述
• 業(yè)務(wù)邏輯

4.Todos

• 設(shè)計方案

• 開發(fā)

• 頁面1
• 組件1
• 通用模塊1

• 聯(lián)調(diào)

• 測試

• UI走查

• 上線

感謝你閱讀到這里, 請注意這也只是筆者根據(jù)自身經(jīng)驗提出的一些關(guān)于技術(shù)設(shè)計的建議, 也存在不少筆者未曾設(shè)想的方面和不完善之處, 請讀者也根據(jù)實際情況不斷完善設(shè)計實踐, 并和大家一起分享.

參考資料