1. 從一張草圖到一套系統(tǒng)diagram-design 到底在解決什么問(wèn)題第一次聽(tīng)到 diagram-design 這個(gè)詞很多人會(huì)下意識(shí)覺(jué)得它只是“畫圖”的另一種說(shuō)法。但真正在項(xiàng)目里被圖表折磨過(guò)的人都知道畫圖從來(lái)不是難點(diǎn)難點(diǎn)在于圖表的可維護(hù)性、一致性和表達(dá)效率。diagram-design 本質(zhì)上是一套圍繞“圖表即設(shè)計(jì)資產(chǎn)”這個(gè)理念構(gòu)建的方法論與工具鏈組合它要解決的核心問(wèn)題是當(dāng)項(xiàng)目規(guī)模變大、參與人數(shù)變多、迭代頻率變高之后圖表如何像代碼一樣被管理、被復(fù)用、被審查。我接觸這個(gè)方向是從一個(gè)跨平臺(tái)系統(tǒng)項(xiàng)目開(kāi)始的。當(dāng)時(shí)團(tuán)隊(duì)有十幾個(gè)人前后端、算法、產(chǎn)品各畫各的圖結(jié)果同一個(gè)數(shù)據(jù)流在三份文檔里出現(xiàn)了三種畫法箭頭方向不一致、模塊命名不統(tǒng)一、顏色語(yǔ)義混亂。評(píng)審會(huì)上光是爭(zhēng)論“這個(gè)框到底代表服務(wù)還是代表進(jìn)程”就花了二十分鐘。那次之后我開(kāi)始認(rèn)真研究 diagram-design 這套思路核心目標(biāo)很明確讓圖表從一次性消耗品變成可沉淀的工程資產(chǎn)。它適合誰(shuí)來(lái)參考如果你只是偶爾畫一張流程圖發(fā)群里那確實(shí)用不上這么重的體系。但只要你符合下面任意一條diagram-design 就值得你花時(shí)間項(xiàng)目周期超過(guò)三個(gè)月、圖表數(shù)量超過(guò)二十張、有多人協(xié)作畫圖需求、圖表需要隨代碼一起版本管理、或者你需要把圖表嵌入文檔站點(diǎn)自動(dòng)構(gòu)建。這些場(chǎng)景下手工拖拽出來(lái)的圖遲早會(huì)變成技術(shù)債。從技術(shù)構(gòu)成上看diagram-design 并不是某一個(gè)具體軟件而是一個(gè)組合拳聲明式描述語(yǔ)言 版本控制 自動(dòng)化渲染 設(shè)計(jì)規(guī)范約束。聲明式描述讓你用文本定義圖版本控制讓每次修改可追溯自動(dòng)化渲染讓圖能進(jìn) CI 流水線設(shè)計(jì)規(guī)范則保證所有人畫出來(lái)的東西長(zhǎng)得像一家人。這四者缺一不可少了任何一個(gè)體系都會(huì)退化成“高級(jí)一點(diǎn)的畫圖工具”。我見(jiàn)過(guò)太多團(tuán)隊(duì)只做了第一步用文本工具畫圖但顏色、字體、間距全靠個(gè)人審美結(jié)果圖是能版本管理了視覺(jué)上依然是一盤散沙。所以 diagram-design 的關(guān)鍵詞里“design”的分量其實(shí)比“diagram”更重。它要求你在動(dòng)手畫第一張圖之前先把設(shè)計(jì)令牌定下來(lái)主色、輔色、警示色、成功色、圓角半徑、線寬、字號(hào)階梯。這些定好了后面所有圖都從這里取改一處全局生效。2. 核心思路拆解為什么是“聲明式 規(guī)范約束”這條路2.1 聲明式描述相比拖拽式繪制的本質(zhì)優(yōu)勢(shì)拖拽式繪圖的問(wèn)題不在于效率低而在于信息與呈現(xiàn)耦合。你在畫布上挪動(dòng)一個(gè)矩形實(shí)際上同時(shí)改變了三件事這個(gè)元素的位置、它和其他元素的相對(duì)關(guān)系、以及它在視覺(jué)上的權(quán)重。當(dāng)圖變復(fù)雜之后你想調(diào)整“所有數(shù)據(jù)存儲(chǔ)節(jié)點(diǎn)統(tǒng)一往左移”在拖拽工具里只能一個(gè)個(gè)手動(dòng)挪而在聲明式描述里你只需要改一個(gè)分組屬性。我用一個(gè)實(shí)際例子說(shuō)明。假設(shè)有一個(gè)數(shù)據(jù)處理流程包含采集、清洗、轉(zhuǎn)換、存儲(chǔ)四個(gè)階段每個(gè)階段下面有三到五個(gè)子模塊。用拖拽工具畫第一版可能花四十分鐘看起來(lái)還不錯(cuò)。但第二周產(chǎn)品說(shuō)“清洗階段要拆成實(shí)時(shí)清洗和離線清洗兩條線”你就得重新布局之前調(diào)好的對(duì)齊全部作廢。而聲明式描述里你只需要在清洗節(jié)點(diǎn)下增加一個(gè)子分組渲染引擎會(huì)自動(dòng)重新計(jì)算布局你甚至不用打開(kāi)畫布。注意聲明式不等于完全放棄視覺(jué)調(diào)整。好的 diagram-design 流程是“聲明式定義結(jié)構(gòu) 規(guī)范約束樣式 渲染器負(fù)責(zé)布局”人工只在必要時(shí)微調(diào)布局參數(shù)而不是逐個(gè)元素?cái)[位置。2.2 設(shè)計(jì)令牌為什么必須先于圖表定義設(shè)計(jì)令牌這個(gè)概念來(lái)自前端設(shè)計(jì)系統(tǒng)放到 diagram-design 里同樣適用。它的本質(zhì)是把視覺(jué)決策從單張圖中抽離出來(lái)變成全局可復(fù)用的變量。我踩過(guò)的一個(gè)坑是早期沒(méi)有定義令牌每張圖里顏色都是手寫的十六進(jìn)制值結(jié)果有一次品牌色調(diào)整我花了整整一個(gè)下午在二十多張圖里搜索替換還漏了兩處導(dǎo)致顏色不一致。定義令牌的時(shí)候我建議至少覆蓋這幾類令牌類別示例名稱用途說(shuō)明語(yǔ)義色color-primary主流程節(jié)點(diǎn)、核心模塊語(yǔ)義色color-warning異常分支、待處理狀態(tài)語(yǔ)義色color-success完成態(tài)、正常輸出語(yǔ)義色color-neutral輔助說(shuō)明、外部依賴線型stroke-solid主數(shù)據(jù)流線型stroke-dashed異步調(diào)用、可選路徑字號(hào)font-title模塊標(biāo)題字號(hào)font-label連線標(biāo)注、注釋間距gap-module模塊之間最小間距這張表看起來(lái)簡(jiǎn)單但它是整個(gè)體系的地基。有了它新人進(jìn)來(lái)畫圖不需要問(wèn)“用什么顏色”直接查令牌表就行。評(píng)審的時(shí)候也不再爭(zhēng)論“這個(gè)藍(lán)色好不好看”而是討論“這個(gè)節(jié)點(diǎn)該不該用警示色”把審美問(wèn)題轉(zhuǎn)化成語(yǔ)義問(wèn)題效率提升非常明顯。2.3 版本控制與自動(dòng)化渲染的協(xié)同邏輯圖表進(jìn)版本控制很多人以為只是把源文件丟進(jìn)代碼倉(cāng)庫(kù)。但真正的價(jià)值在于圖表變更和代碼變更可以關(guān)聯(lián)審查。比如某個(gè)接口的調(diào)用關(guān)系變了代碼提交里改了接口定義同一批提交里也應(yīng)該包含對(duì)應(yīng)流程圖的修改。評(píng)審的人能同時(shí)看到代碼 diff 和圖 diff判斷兩者是否一致。自動(dòng)化渲染則是把源文件變成可嵌入文檔的圖片或矢量圖。我目前的流程是源文件用文本格式存在倉(cāng)庫(kù)里CI 流水線在每次合并請(qǐng)求時(shí)自動(dòng)渲染成 SVG產(chǎn)物上傳到文檔站點(diǎn)。這樣文檔站點(diǎn)上的圖永遠(yuǎn)和倉(cāng)庫(kù)里的源文件同步不會(huì)出現(xiàn)“文檔里的圖還是三個(gè)月前的版本”這種經(jīng)典問(wèn)題。這里有個(gè)細(xì)節(jié)值得展開(kāi)渲染產(chǎn)物用 SVG 而不是 PNG。SVG 是矢量格式在文檔里縮放不糊而且文本可搜索對(duì) SEO 和可訪問(wèn)性都友好。PNG 只適合需要固定像素尺寸的場(chǎng)景比如某些聊天工具預(yù)覽。我一般兩個(gè)都出SVG 給文檔PNG 給即時(shí)通訊分享。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 圖表源文件的組織結(jié)構(gòu)一個(gè)中等規(guī)模項(xiàng)目圖表數(shù)量很容易超過(guò)三十張。如果全部平鋪在一個(gè)目錄里找起來(lái)會(huì)非常痛苦。我推薦按領(lǐng)域 類型兩級(jí)組織diagrams/ >