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

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

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

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

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

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

Measure twice and cut once 三思而后行

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

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

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

我是三傻·史塔可嗎?

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

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

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

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

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

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

• 內(nèi)容完備

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

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

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

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

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

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

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

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

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

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

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

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

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

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

讓我們舉個(gè)??例子

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

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

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

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

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

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

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

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

• C端部分:

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

• B端部分

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

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

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

最后附上筆者團(tuán)隊(duì)前端的設(shè)計(jì)文檔模版

1.需求背景及資源

• 需求背景

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

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

2.排期

需求Timeline

排期拆分

3.設(shè)計(jì)方案

整體方案

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

頁面設(shè)計(jì)

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

組件設(shè)計(jì)

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

公用模塊

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

4.Todos

• 設(shè)計(jì)方案

• 開發(fā)

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

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

• 測試

• UI走查

• 上線

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

參考資料

?? 謝謝支持

以上便是本次分享的全部內(nèi)容，希望對你有所幫助^_^

喜歡的話別忘了 分享、點(diǎn)贊、收藏 三連哦~。

歡迎關(guān)注公眾號(hào) 前端Sharing  收貨大廠一手好文章~