1. 從一張草圖到一套系統(tǒng)diagram-design 到底在解決什么問(wèn)題第一次看到 diagram-design 這個(gè)詞很多人會(huì)以為它只是“畫(huà)圖”的另一種說(shuō)法。但真正在項(xiàng)目里摸爬滾打過(guò)幾年的人會(huì)明白圖這件事從來(lái)不是“畫(huà)得好看”那么簡(jiǎn)單。它背后牽扯的是信息結(jié)構(gòu)、協(xié)作效率、版本管理、交付一致性以及一個(gè)團(tuán)隊(duì)能不能把腦子里的復(fù)雜邏輯用一張所有人都能看懂的圖講清楚。diagram-design 這個(gè)項(xiàng)目標(biāo)題核心落點(diǎn)其實(shí)在“design”上而不是“diagram”。它要處理的不是單張圖的繪制技巧而是一套圍繞圖表的設(shè)計(jì)體系怎么定義圖表的視覺(jué)語(yǔ)言怎么把重復(fù)出現(xiàn)的結(jié)構(gòu)抽象成可復(fù)用的組件怎么讓不同角色的人在同一套規(guī)則下產(chǎn)出風(fēng)格統(tǒng)一、語(yǔ)義清晰的圖。換句話說(shuō)它解決的是“圖越畫(huà)越多、越畫(huà)越亂、越畫(huà)越難維護(hù)”這個(gè)幾乎所有中大型項(xiàng)目都會(huì)遇到的頑疾。我見(jiàn)過(guò)太多團(tuán)隊(duì)在項(xiàng)目初期隨手畫(huà)幾張架構(gòu)圖、流程圖等到項(xiàng)目中期圖的數(shù)量膨脹到幾十張風(fēng)格五花八門(mén)顏色、線型、字體、箭頭含義全都不統(tǒng)一新人接手時(shí)根本分不清哪張圖是最新的、哪張圖里的虛線到底代表異步還是代表廢棄。diagram-design 要做的就是把這套混亂收斂成一套可執(zhí)行的規(guī)范加工具鏈。它適合誰(shuí)如果你是獨(dú)立開(kāi)發(fā)者平時(shí)只需要畫(huà)一兩張示意圖那這套東西可能有點(diǎn)重但只要你所在的團(tuán)隊(duì)超過(guò)三個(gè)人或者項(xiàng)目周期超過(guò)三個(gè)月或者你需要向外部反復(fù)交付圖表那 diagram-design 的價(jià)值就會(huì)立刻顯現(xiàn)出來(lái)。它適合技術(shù)負(fù)責(zé)人、產(chǎn)品經(jīng)理、架構(gòu)師、技術(shù)文檔工程師以及任何需要把復(fù)雜系統(tǒng)講清楚的人。這篇文章我會(huì)從設(shè)計(jì)思路、核心細(xì)節(jié)、實(shí)操落地、問(wèn)題排查幾個(gè)層面把 diagram-design 這套東西拆開(kāi)講透。不是空談理念而是給到你可以直接抄作業(yè)的規(guī)則、參數(shù)和流程。2. 整體設(shè)計(jì)思路為什么圖表也需要一套設(shè)計(jì)系統(tǒng)2.1 圖表混亂的根源不在工具而在缺少約束大部分人把圖表畫(huà)亂第一反應(yīng)是“換個(gè)更好的工具”。但工具換了一圈問(wèn)題依舊。原因很簡(jiǎn)單混亂的根源不是工具能力不足而是沒(méi)有約束。每個(gè)人憑自己的審美和習(xí)慣去畫(huà)顏色隨手選線型隨手定字號(hào)隨手調(diào)最后產(chǎn)出的圖自然無(wú)法統(tǒng)一。diagram-design 的第一個(gè)核心思路就是把“約束”前置。它不追求讓每個(gè)人都能自由發(fā)揮而是先定義一套最小可用規(guī)則讓所有人在這套規(guī)則里工作。這跟代碼規(guī)范是一個(gè)道理不是限制你寫(xiě)代碼的自由而是讓協(xié)作成本降下來(lái)。具體來(lái)說(shuō)這套約束至少覆蓋四個(gè)維度顏色語(yǔ)義、線型語(yǔ)義、形狀語(yǔ)義、排版規(guī)則。顏色不是用來(lái)好看的而是用來(lái)表達(dá)狀態(tài)的線型不是用來(lái)裝飾的而是用來(lái)表達(dá)關(guān)系的形狀不是隨便選的而是對(duì)應(yīng)不同類型的實(shí)體。一旦這些語(yǔ)義固定下來(lái)讀圖的人就不需要每次重新猜測(cè)認(rèn)知負(fù)擔(dān)大幅下降。2.2 從“畫(huà)圖”轉(zhuǎn)向“建模”可復(fù)用才是關(guān)鍵diagram-design 的第二個(gè)思路是把圖表從“一次性繪制”轉(zhuǎn)向“結(jié)構(gòu)化建?！?。傳統(tǒng)畫(huà)圖是所見(jiàn)即所得你拖一個(gè)框、連一條線圖就成型了。但這種方式的致命問(wèn)題是不可復(fù)用同樣的服務(wù)節(jié)點(diǎn)在十張圖里要畫(huà)十遍改一個(gè)名字要改十處。diagram-design 提倡的做法是先把系統(tǒng)里的核心實(shí)體抽象成“圖元”每個(gè)圖元有固定的屬性名稱、類型、所屬層級(jí)、依賴關(guān)系。圖只是這些圖元的一次投影。這樣一來(lái)改一處定義所有引用它的圖都會(huì)同步更新。這本質(zhì)上和前端組件化、后端微服務(wù)化是同一個(gè)思想把重復(fù)的東西抽出來(lái)把變化的東西隔離出去。我實(shí)測(cè)下來(lái)這套思路在系統(tǒng)架構(gòu)圖、部署圖、數(shù)據(jù)流圖這三類圖上收益最大因?yàn)樗鼈兊膶?shí)體重復(fù)度極高。而像一次性的頭腦風(fēng)暴草圖就沒(méi)必要上這套重武器。2.3 分層設(shè)計(jì)讓不同角色各司其職第三個(gè)思路是分層。diagram-design 把圖表工作拆成三層語(yǔ)義層、結(jié)構(gòu)層、表現(xiàn)層。語(yǔ)義層定義“這張圖要表達(dá)什么”由業(yè)務(wù)或架構(gòu)角色負(fù)責(zé)結(jié)構(gòu)層定義“用哪些圖元和關(guān)系來(lái)承載這些語(yǔ)義”由設(shè)計(jì)或文檔角色負(fù)責(zé)表現(xiàn)層定義“最終渲染成什么樣子”由工具自動(dòng)完成。三層分離的好處是改顏色不影響語(yǔ)義改結(jié)構(gòu)不影響業(yè)務(wù)表達(dá)各層可以獨(dú)立演進(jìn)。很多團(tuán)隊(duì)畫(huà)圖累就是因?yàn)槿龑踊煸谝黄饦I(yè)務(wù)的人直接去調(diào)顏色設(shè)計(jì)的人去改業(yè)務(wù)邏輯最后誰(shuí)也說(shuō)不清哪層出了問(wèn)題。分層之后責(zé)任清晰返工率明顯下降。提示分層不是目的降低協(xié)作摩擦才是。如果你的團(tuán)隊(duì)只有兩個(gè)人硬套三層反而增加溝通成本可以合并語(yǔ)義層和結(jié)構(gòu)層。3. 核心細(xì)節(jié)解析顏色、線型、形狀、排版的具體規(guī)則3.1 顏色語(yǔ)義用有限的色板表達(dá)無(wú)限的狀態(tài)顏色是圖表里最容易被濫用的元素。diagram-design 的做法是嚴(yán)格限制色板數(shù)量一般控制在 5 到 7 個(gè)主色每個(gè)主色對(duì)應(yīng)一個(gè)明確語(yǔ)義。比如藍(lán)色代表正常服務(wù)綠色代表新增或健康橙色代表警告或降級(jí)紅色代表故障或廢棄灰色代表外部依賴或非核心。關(guān)鍵點(diǎn)在于顏色必須成對(duì)定義填充色和邊框色。填充色用于大面積區(qū)分邊框色用于強(qiáng)調(diào)邊界。兩者要有足夠的對(duì)比度保證在黑白打印或色弱用戶眼里依然可區(qū)分。我一般會(huì)把填充色的明度調(diào)高、飽和度調(diào)低邊框色則相反這樣整體看起來(lái)干凈不會(huì)因?yàn)轭伾珴M而顯得刺眼。還有一個(gè)容易被忽略的細(xì)節(jié)顏色的數(shù)量要和語(yǔ)義的粒度匹配。如果你定義了十種顏色但實(shí)際只有三種狀態(tài)那多出來(lái)的顏色只會(huì)造成困惑。寧可少而精不要多而雜。3.2 線型語(yǔ)義實(shí)線、虛線、點(diǎn)線的分工線型是表達(dá)關(guān)系類型最直接的手段。diagram-design 里通常約定實(shí)線表示同步調(diào)用或強(qiáng)依賴虛線表示異步消息或弱依賴點(diǎn)線表示可選或未來(lái)規(guī)劃。箭頭方向表示數(shù)據(jù)或控制流的走向雙向箭頭表示雙向通信。這里有個(gè)實(shí)操心得線型不要超過(guò)三種。我見(jiàn)過(guò)有人用實(shí)線、虛線、點(diǎn)線、點(diǎn)劃線、雙線五種線型結(jié)果讀圖的人根本記不住。三種是認(rèn)知的舒適區(qū)超過(guò)三種就要靠圖例反復(fù)查反而降低效率。另外線的粗細(xì)也可以承載語(yǔ)義但建議只區(qū)分兩檔常規(guī)和強(qiáng)調(diào)。常規(guī)線寬 1.5px強(qiáng)調(diào)線寬 3px。不要用 0.5px 這種過(guò)細(xì)的線投影或縮放后會(huì)消失。3.3 形狀語(yǔ)義矩形、圓角矩形、圓柱、云朵各代表什么形狀是最容易被隨意使用的元素。diagram-design 強(qiáng)調(diào)形狀必須和實(shí)體類型綁定。常見(jiàn)的約定是矩形代表服務(wù)或模塊圓角矩形代表流程步驟圓柱代表數(shù)據(jù)庫(kù)或存儲(chǔ)云朵代表外部系統(tǒng)或第三方菱形代表判斷或網(wǎng)關(guān)。這套約定不是強(qiáng)制的但一旦團(tuán)隊(duì)選定就要寫(xiě)進(jìn)規(guī)范文檔所有人遵守。我建議把形狀約定做成一張速查表貼在團(tuán)隊(duì)文檔的顯眼位置新人入職第一周就要熟悉。3.4 排版規(guī)則對(duì)齊、間距、字號(hào)的三條鐵律排版決定了圖的“專業(yè)感”。diagram-design 的排版規(guī)則可以濃縮成三條對(duì)齊、等距、層級(jí)字號(hào)。對(duì)齊是指所有同類元素必須沿同一軸線對(duì)齊要么左對(duì)齊要么居中對(duì)齊不要混用。等距是指同級(jí)元素之間的間距必須一致水平間距和垂直間距分別統(tǒng)一一般水平間距取元素寬度的 1/4垂直間距取元素高度的 1/2。層級(jí)字號(hào)是指標(biāo)題、節(jié)點(diǎn)名、注釋用不同字號(hào)通常標(biāo)題 18px節(jié)點(diǎn)名 14px注釋 12px形成清晰的視覺(jué)層級(jí)。這三條看起來(lái)簡(jiǎn)單但真正做到位的團(tuán)隊(duì)不多。我踩過(guò)的坑是早期覺(jué)得對(duì)齊太麻煩隨手?jǐn)[放結(jié)果圖一多就顯得雜亂無(wú)章后來(lái)強(qiáng)制對(duì)齊后同樣的內(nèi)容看起來(lái)專業(yè)度提升了一個(gè)檔次。元素類型形狀填充色邊框色字號(hào)核心服務(wù)矩形淺藍(lán)深藍(lán)14px流程步驟圓角矩形淺綠深綠14px數(shù)據(jù)存儲(chǔ)圓柱淺灰深灰14px外部系統(tǒng)云朵淺橙深橙14px判斷網(wǎng)關(guān)菱形淺黃深黃14px4. 實(shí)操過(guò)程從零搭建一套 diagram-design 體系4.1 第一步盤(pán)點(diǎn)現(xiàn)有圖表找出共性和痛點(diǎn)不要一上來(lái)就定規(guī)范先盤(pán)點(diǎn)。把團(tuán)隊(duì)現(xiàn)有的所有圖收集起來(lái)按類型分類統(tǒng)計(jì)每類圖的數(shù)量、重復(fù)出現(xiàn)的實(shí)體、常見(jiàn)的修改頻率。這一步的目的是找出哪些圖值得抽象哪些圖是一次性的。我一般會(huì)做一個(gè)簡(jiǎn)單的表格列出圖名、類型、涉及實(shí)體數(shù)、最近一次修改時(shí)間、修改原因。盤(pán)點(diǎn)完你會(huì)發(fā)現(xiàn)真正高頻修改的圖往往只占 20%但它們消耗了 80% 的維護(hù)精力。這 20% 就是 diagram-design 優(yōu)先覆蓋的對(duì)象。4.2 第二步定義圖元庫(kù)和語(yǔ)義規(guī)則基于盤(pán)點(diǎn)結(jié)果抽象出核心圖元。每個(gè)圖元定義四個(gè)屬性唯一標(biāo)識(shí)、顯示名稱、類型、默認(rèn)樣式。類型決定了它用哪種形狀和顏色默認(rèn)樣式可以在具體圖中被覆蓋但覆蓋要有理由。語(yǔ)義規(guī)則要寫(xiě)成文檔包括顏色表、線型表、形狀表、排版規(guī)則。文檔不用長(zhǎng)一頁(yè)紙能說(shuō)清最好。關(guān)鍵是可執(zhí)行每條規(guī)則都要有明確的判斷標(biāo)準(zhǔn)避免“盡量”“適當(dāng)”這種模糊表述。4.3 第三步選擇工具鏈并配置模板工具選型上diagram-design 不綁定特定工具但要求工具支持模板和樣式復(fù)用。常見(jiàn)的組合是用代碼化工具管理圖元定義用渲染工具輸出最終圖。代碼化工具的好處是版本可控、diff 可讀、CI 可集成。配置模板時(shí)把前面定義的色板、線型、字號(hào)寫(xiě)進(jìn)模板文件新建圖時(shí)直接繼承。這樣即使新人不懂規(guī)范只要用模板產(chǎn)出的圖也八九不離十。我實(shí)測(cè)下來(lái)模板能把風(fēng)格統(tǒng)一度從 60% 提升到 90% 以上。4.4 第四步建立評(píng)審和更新機(jī)制規(guī)范定完不是終點(diǎn)而是起點(diǎn)。要建立輕量的評(píng)審機(jī)制新圖提交時(shí)檢查是否符合規(guī)范規(guī)范本身也要定期回顧一般每季度一次根據(jù)實(shí)際使用中的問(wèn)題調(diào)整。更新機(jī)制的關(guān)鍵是“誰(shuí)用誰(shuí)提”。不要由一個(gè)人閉門(mén)造車(chē)定規(guī)范而是讓實(shí)際畫(huà)圖的人參與修訂。我見(jiàn)過(guò)太多規(guī)范因?yàn)槊撾x實(shí)際而被棄用根本原因就是定規(guī)范的人不畫(huà)圖。注意規(guī)范文檔要放在團(tuán)隊(duì)最容易看到的地方不要藏在深層目錄里。我一般會(huì)把它放在項(xiàng)目根目錄的 docs 下并在 README 里鏈接。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 圖元定義太細(xì)導(dǎo)致維護(hù)成本高這是最常見(jiàn)的坑。一開(kāi)始熱情高漲把每個(gè)實(shí)體都定義成圖元結(jié)果圖元數(shù)量膨脹到上百個(gè)維護(hù)成本反而超過(guò)收益。排查思路是只抽象重復(fù)出現(xiàn)三次以上的實(shí)體出現(xiàn)一兩次的用通用圖元代替。圖元庫(kù)要定期清理合并相似圖元?jiǎng)h除不再使用的。5.2 顏色在深色模式下不可讀很多團(tuán)隊(duì)只考慮淺色背景結(jié)果圖在深色模式下慘不忍睹。解決辦法是定義兩套色板或者選擇在深淺背景下都有足夠?qū)Ρ榷鹊念伾?。我一般?huì)把填充色的明度控制在 70% 到 85% 之間這樣在深淺背景下都能看清。5.3 圖元更新后舊圖沒(méi)有同步這是結(jié)構(gòu)化建模的典型問(wèn)題。如果圖是手動(dòng)繪制的圖元更新后舊圖不會(huì)自動(dòng)變。解決辦法是盡量讓圖從圖元定義生成而不是手動(dòng)繪制。如果做不到就建立更新清單圖元變更時(shí)列出受影響的圖逐一更新。5.4 團(tuán)隊(duì)成員不遵守規(guī)范規(guī)范執(zhí)行不下去通常不是規(guī)范本身的問(wèn)題而是缺少反饋。解決辦法是把規(guī)范檢查集成到流程里比如提交圖時(shí)自動(dòng)檢查顏色和字號(hào)不符合就提示。另外規(guī)范要足夠簡(jiǎn)單簡(jiǎn)單到不遵守反而更麻煩。問(wèn)題現(xiàn)象可能原因排查方向解決建議圖元數(shù)量過(guò)多抽象粒度過(guò)細(xì)統(tǒng)計(jì)圖元使用頻率合并低頻圖元深色模式不可讀只定義單套色板檢查對(duì)比度定義雙套色板舊圖未同步手動(dòng)繪制為主檢查生成流程改為圖元生成規(guī)范執(zhí)行差缺少自動(dòng)檢查檢查提交流程集成自動(dòng)校驗(yàn)5.5 獨(dú)家避坑技巧先小范圍試點(diǎn)再推廣不要一上來(lái)就全團(tuán)隊(duì)推廣先在一個(gè)小項(xiàng)目或一個(gè)小組試點(diǎn)跑通流程、收集反饋、調(diào)整規(guī)范再逐步推廣。我踩過(guò)的坑是規(guī)范定完直接全員推行結(jié)果問(wèn)題集中爆發(fā)反而打擊了大家對(duì)規(guī)范的信心。小范圍試點(diǎn)能把問(wèn)題控制在可修復(fù)的范圍內(nèi)。6. 圖表設(shè)計(jì)體系的延展與個(gè)人體會(huì)diagram-design 這套東西跑通之后延展空間其實(shí)很大。最直接的一個(gè)方向是把它和文檔系統(tǒng)打通圖元定義直接引用文檔里的術(shù)語(yǔ)表保證圖和文檔用詞一致。另一個(gè)方向是把它和代碼倉(cāng)庫(kù)打通架構(gòu)圖從代碼里的服務(wù)定義自動(dòng)生成徹底消除圖和代碼不一致的問(wèn)題。我在實(shí)際使用中發(fā)現(xiàn)圖表設(shè)計(jì)體系最大的價(jià)值不是讓圖變好看而是讓團(tuán)隊(duì)在討論系統(tǒng)時(shí)有了共同的視覺(jué)語(yǔ)言。以前開(kāi)會(huì)討論架構(gòu)每個(gè)人腦子里想的圖都不一樣溝通成本極高現(xiàn)在大家看著同一套圖元、同一套語(yǔ)義討論效率明顯提升。最后再分享一個(gè)小技巧定期做“圖審計(jì)”每隔一個(gè)季度把團(tuán)隊(duì)所有的圖過(guò)一遍刪掉過(guò)期的、合并重復(fù)的、更新圖元。圖和人一樣不維護(hù)就會(huì)老化。這個(gè)習(xí)慣堅(jiān)持下來(lái)圖庫(kù)會(huì)一直保持清爽可用。