1. 從一張草圖到一套系統(tǒng)diagram-design 到底在解決什么問題第一次看到 “diagram-design” 這個(gè)標(biāo)題很多人會(huì)以為它只是教你怎么把圖畫得好看一點(diǎn)。但真正做過系統(tǒng)設(shè)計(jì)、寫過技術(shù)方案、跟產(chǎn)品經(jīng)理吵過架構(gòu)圖的人都知道畫圖這件事從來不只是“美不美”的問題。它背后牽扯的是信息層級(jí)、邏輯關(guān)系、閱讀動(dòng)線、協(xié)作效率甚至是一個(gè)團(tuán)隊(duì)對(duì)系統(tǒng)認(rèn)知是否對(duì)齊。我見過太多項(xiàng)目代碼寫得漂漂亮亮結(jié)果一張架構(gòu)圖發(fā)到群里三個(gè)人能讀出四種理解最后開會(huì)兩小時(shí)全在糾正圖上的箭頭方向。所以 diagram-design 這個(gè)主題我理解它要解決的核心問題是如何用一套可復(fù)用的設(shè)計(jì)方法把復(fù)雜的系統(tǒng)、流程、數(shù)據(jù)結(jié)構(gòu)、業(yè)務(wù)關(guān)系轉(zhuǎn)化成一張讓人一眼看懂、且不容易產(chǎn)生歧義的圖。它既包含視覺層面的排版、配色、對(duì)齊、留白也包含邏輯層面的分層、分組、連線規(guī)則、標(biāo)注體系。適合誰來參考如果你是開發(fā)者、產(chǎn)品經(jīng)理、技術(shù)文檔寫作者、解決方案架構(gòu)師或者任何需要靠圖來溝通的人這套東西都值得花時(shí)間琢磨。我自己在過往項(xiàng)目里踩過的坑很典型早期畫架構(gòu)圖恨不得把所有組件都塞進(jìn)去結(jié)果圖比代碼還難讀后來走向另一個(gè)極端為了簡(jiǎn)潔把關(guān)鍵依賴關(guān)系省掉導(dǎo)致運(yùn)維同學(xué)部署時(shí)才發(fā)現(xiàn)少了一個(gè)中間件。反復(fù)折騰之后我才明白diagram-design 的本質(zhì)不是“畫圖”而是信息設(shè)計(jì)。圖只是載體真正要設(shè)計(jì)的是讀者從這張圖上獲取信息的路徑。這篇文章我會(huì)從設(shè)計(jì)思路、核心細(xì)節(jié)、實(shí)操流程、常見問題幾個(gè)維度把 diagram-design 拆開講透盡量讓你看完就能直接上手改自己手頭那堆圖。2. 內(nèi)容整體設(shè)計(jì)與思路拆解2.1 為什么 diagram-design 要先定“讀者”再定“畫法”很多人畫圖的第一步是打開工具拖一個(gè)矩形出來。這個(gè)習(xí)慣得改。diagram-design 的第一原則是先明確這張圖給誰看、在什么場(chǎng)景下看、看完要做什么決策。這三個(gè)問題決定了圖的粒度、標(biāo)注詳細(xì)程度、甚至配色方案。舉個(gè)實(shí)際場(chǎng)景。給管理層看的系統(tǒng)全景圖他們關(guān)心的是業(yè)務(wù)模塊之間的價(jià)值流轉(zhuǎn)和成本分布不關(guān)心你用的是什么消息隊(duì)列。這時(shí)候圖上的節(jié)點(diǎn)應(yīng)該是“訂單中心”“風(fēng)控引擎”“結(jié)算服務(wù)”這種業(yè)務(wù)語義單元連線標(biāo)注的是“同步調(diào)用”“異步通知”這種業(yè)務(wù)影響而不是“HTTP”“gRPC”。反過來給運(yùn)維團(tuán)隊(duì)看的部署圖節(jié)點(diǎn)必須精確到具體服務(wù)實(shí)例、中間件版本、網(wǎng)絡(luò)區(qū)域連線要標(biāo)注端口和協(xié)議。同一套系統(tǒng)兩張圖的畫法完全不同但都叫 diagram-design。我自己的做法是在動(dòng)手之前先寫一句話“這張圖是給____看的他們看完要決定____。”如果這句話寫不出來說明你還沒想清楚別急著畫。這個(gè)習(xí)慣幫我省掉了大量返工時(shí)間。有一次做跨團(tuán)隊(duì)接口對(duì)齊我一開始畫了一張大而全的圖結(jié)果兩個(gè)團(tuán)隊(duì)各自只關(guān)心自己那一半整張圖對(duì)他們來說都是噪音。后來拆成兩張每張只保留相關(guān)鏈路溝通效率立刻上來了。2.2 分層思維diagram-design 的骨架邏輯圖亂不亂九成取決于分層有沒有做好。diagram-design 里我習(xí)慣把信息分成三層背景層、結(jié)構(gòu)層、標(biāo)注層。背景層是分組框、區(qū)域底色、泳道用來表達(dá)“這些東西屬于同一個(gè)范疇”結(jié)構(gòu)層是節(jié)點(diǎn)和連線表達(dá)“誰和誰有關(guān)系”標(biāo)注層是文字、圖標(biāo)、編號(hào)表達(dá)“這個(gè)關(guān)系是什么性質(zhì)”。這三層如果混在一起圖就會(huì)糊。常見錯(cuò)誤是把標(biāo)注直接寫在連線上線一多就變成蜘蛛網(wǎng)。更好的做法是給連線編號(hào)然后在圖旁邊用表格列出編號(hào)對(duì)應(yīng)的說明。這樣圖面干凈信息也不丟。另一個(gè)錯(cuò)誤是分組框套太多層三層以上的嵌套基本沒人能看懂。我的經(jīng)驗(yàn)是分組最多兩層超過兩層就拆圖。分層還有一個(gè)好處是方便迭代。需求變了只需要改結(jié)構(gòu)層背景層和標(biāo)注層可以復(fù)用。我在一個(gè)持續(xù)半年的項(xiàng)目里維護(hù)過一套架構(gòu)圖因?yàn)橐婚_始就分好了層后面每次加模塊只需要在結(jié)構(gòu)層補(bǔ)節(jié)點(diǎn)整體風(fēng)格完全沒亂。如果當(dāng)初把所有信息都堆在一起改到第三版就沒人愿意看了。2.3 工具選型別讓工具綁架你的設(shè)計(jì)diagram-design 用什么工具畫這個(gè)問題我被問過無數(shù)次。我的答案是工具不重要重要的是你的設(shè)計(jì)規(guī)則能不能被工具穩(wěn)定執(zhí)行。但現(xiàn)實(shí)中工具確實(shí)會(huì)影響你的表達(dá)上限所以還是得選。代碼化繪圖工具適合需要版本管理、頻繁迭代的場(chǎng)景圖就是代碼可以 diff、可以 review、可以 CI 檢查。拖拽式工具適合快速出圖、非技術(shù)同學(xué)參與的場(chǎng)景上手快但容易風(fēng)格不統(tǒng)一。在線白板適合頭腦風(fēng)暴階段的草圖但不適合作為最終交付物。我自己的組合是草圖階段用白板正式圖用代碼化工具對(duì)外交付再導(dǎo)出成通用格式。這樣既保留了思考的靈活性又保證了最終產(chǎn)物的可維護(hù)性。選型時(shí)我會(huì)重點(diǎn)看三個(gè)指標(biāo)是否支持自定義樣式模板、是否支持圖層或分組、導(dǎo)出格式是否矢量。前兩個(gè)決定你能不能建立統(tǒng)一規(guī)范第三個(gè)決定圖放大后會(huì)不會(huì)糊。注意不要因?yàn)槟硞€(gè)工具流行就換掉現(xiàn)有流程。我見過團(tuán)隊(duì)一年換三次繪圖工具結(jié)果每套圖風(fēng)格都不一樣維護(hù)成本反而更高。工具是服務(wù)于設(shè)計(jì)規(guī)則的規(guī)則穩(wěn)定了換工具只是遷移成本問題。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 節(jié)點(diǎn)設(shè)計(jì)形狀、尺寸、命名的統(tǒng)一規(guī)則節(jié)點(diǎn)是圖的基本單元節(jié)點(diǎn)一亂整張圖就亂。diagram-design 里我給節(jié)點(diǎn)定了三條硬規(guī)則形狀表達(dá)類型、尺寸表達(dá)層級(jí)、命名表達(dá)職責(zé)。形狀方面矩形代表服務(wù)或模塊圓角矩形代表外部系統(tǒng)圓柱代表數(shù)據(jù)存儲(chǔ)菱形代表決策點(diǎn)平行四邊形代表輸入輸出。這套規(guī)則一旦定下來就不要隨意打破。我見過一張圖里矩形和圓角矩形混用讀者根本分不清哪個(gè)是內(nèi)部哪個(gè)是外部。尺寸方面核心節(jié)點(diǎn)可以稍大但同一層級(jí)的節(jié)點(diǎn)尺寸必須一致否則讀者會(huì)誤以為大的更重要。命名方面節(jié)點(diǎn)文字應(yīng)該是“名詞職責(zé)”比如“訂單服務(wù)”“用戶中心”而不是“處理訂單的”“管用戶的”。命名還有一個(gè)細(xì)節(jié)中英文混排要統(tǒng)一。要么全中文要么全英文要么統(tǒng)一用“中文English”格式。我見過圖上有的節(jié)點(diǎn)寫“Order Service”有的寫“用戶服務(wù)”讀起來非常割裂。如果團(tuán)隊(duì)有國際化需求建議統(tǒng)一用英文加中文注釋或者反過來但一定要一致。節(jié)點(diǎn)數(shù)量也要控制。一張圖超過 15 個(gè)節(jié)點(diǎn)閱讀壓力就明顯上升。超過 20 個(gè)基本沒人會(huì)仔細(xì)看。這時(shí)候應(yīng)該考慮拆圖或者把次要節(jié)點(diǎn)折疊成分組。我自己的經(jīng)驗(yàn)是核心鏈路圖控制在 7 到 12 個(gè)節(jié)點(diǎn)之間讀者最容易接受。3.2 連線設(shè)計(jì)箭頭、線型、交叉處理連線是圖里最容易出問題的地方。diagram-design 里連線的核心原則是每一條線都要有明確語義不能有裝飾性連線。箭頭方向表達(dá)依賴或數(shù)據(jù)流向這個(gè)必須統(tǒng)一。如果 A 調(diào)用 B箭頭從 A 指向 B如果 A 和 B 是雙向同步用雙向箭頭或者兩條單向箭頭。不要一會(huì)兒用箭頭表示調(diào)用一會(huì)兒用箭頭表示數(shù)據(jù)流向讀者會(huì)瘋。線型方面實(shí)線表示同步或強(qiáng)依賴虛線表示異步或弱依賴點(diǎn)線表示可選或未來規(guī)劃。這套規(guī)則在技術(shù)圖里幾乎是通用語言照著用就行。交叉處理是難點(diǎn)。線一多必然交叉完全避免不現(xiàn)實(shí)但可以優(yōu)化。我的做法是優(yōu)先調(diào)整節(jié)點(diǎn)位置減少交叉其次用跳線符號(hào)最后才允許直接交叉。跳線就是在線交叉處畫一個(gè)小弧表示兩條線不相連。這個(gè)細(xì)節(jié)很小但能大幅降低誤讀概率。另外連線上的文字標(biāo)注要盡量少能編號(hào)就編號(hào)能放圖例就放圖例。還有一個(gè)容易被忽略的點(diǎn)連線的粗細(xì)。除非有明確的主次鏈路區(qū)分否則所有連線粗細(xì)應(yīng)該一致。我見過用粗線表示“重要”的圖但什么是重要沒有定義結(jié)果所有線都變粗了等于沒區(qū)分。3.3 配色與排版讓圖“呼吸”起來配色不是審美問題是信息層級(jí)問題。diagram-design 里我用色遵循“三色原則”主色用于核心節(jié)點(diǎn)輔助色用于次要節(jié)點(diǎn)強(qiáng)調(diào)色只用于需要特別注意的地方。超過三種顏色圖就開始花。具體怎么選技術(shù)架構(gòu)圖我傾向冷色調(diào)藍(lán)灰為主穩(wěn)定、專業(yè)業(yè)務(wù)流程圖可以用暖色調(diào)橙黃為主有活力。但不管什么色調(diào)背景一定要淺節(jié)點(diǎn)顏色和背景的對(duì)比度要足夠。我見過深色背景配深藍(lán)節(jié)點(diǎn)的圖投影儀上一放什么都看不清。排版的核心是留白和對(duì)齊。留白不是浪費(fèi)空間是給眼睛休息的地方。節(jié)點(diǎn)之間、分組之間、圖與邊界之間都要留出足夠間距。對(duì)齊則是讓圖看起來“整齊”的關(guān)鍵所有節(jié)點(diǎn)盡量對(duì)齊到網(wǎng)格連線盡量水平或垂直。斜線雖然有時(shí)能減少交叉但會(huì)破壞整體秩序感非必要不用。提示導(dǎo)出圖之前把圖縮小到 50% 看一眼。如果縮小后還能看清主干結(jié)構(gòu)說明層級(jí)和配色是成功的如果縮下去就糊成一團(tuán)說明細(xì)節(jié)太多、對(duì)比不夠需要精簡(jiǎn)。3.4 標(biāo)注與圖例別讓讀者猜標(biāo)注是圖的說明書。diagram-design 里標(biāo)注分兩種圖內(nèi)標(biāo)注和圖例。圖內(nèi)標(biāo)注用于節(jié)點(diǎn)和連線的直接說明圖例用于解釋符號(hào)、顏色、線型的含義。圖內(nèi)標(biāo)注要短最好控制在 10 個(gè)字以內(nèi)。超過 10 個(gè)字就應(yīng)該考慮放到圖例或旁邊的說明文檔里。我見過節(jié)點(diǎn)里塞了一整段話的圖節(jié)點(diǎn)被撐得巨大整張圖比例失調(diào)。圖例則是必須的尤其是用了非通用符號(hào)的時(shí)候。圖例位置一般在圖的右下角或底部不要放在左上角因?yàn)樽x者習(xí)慣從左上開始讀圖圖例放那里會(huì)打斷閱讀動(dòng)線。還有一個(gè)細(xì)節(jié)編號(hào)系統(tǒng)。如果圖里有大量連線需要說明給連線編號(hào)然后在圖下方用表格列出“編號(hào)-說明”。這個(gè)做法在復(fù)雜系統(tǒng)圖里特別有效圖面干凈信息完整。編號(hào)規(guī)則要簡(jiǎn)單比如 L1、L2、L3不要用復(fù)雜編碼。4. 實(shí)操過程與核心環(huán)節(jié)實(shí)現(xiàn)4.1 從需求到草圖信息收集與結(jié)構(gòu)梳理實(shí)操第一步不是畫圖是收集信息。我會(huì)先列一個(gè)清單這張圖要表達(dá)哪些實(shí)體、哪些關(guān)系、哪些約束。實(shí)體就是節(jié)點(diǎn)候選關(guān)系就是連線候選約束就是分組和層級(jí)依據(jù)。收集完之后我會(huì)用紙筆或者白板畫一版草圖。草圖不追求好看只追求邏輯完整。這個(gè)階段我會(huì)刻意問自己三個(gè)問題有沒有遺漏的關(guān)鍵實(shí)體有沒有多余的不相關(guān)實(shí)體關(guān)系方向有沒有搞反這三個(gè)問題能篩掉大部分低級(jí)錯(cuò)誤。草圖階段還有一個(gè)技巧用不同顏色的便簽代表不同層級(jí)。比如黃色代表業(yè)務(wù)層藍(lán)色代表服務(wù)層綠色代表數(shù)據(jù)層。這樣一眼就能看出層級(jí)是否清晰有沒有跨層混亂。我在一個(gè)跨部門項(xiàng)目里用這個(gè)方法十分鐘就發(fā)現(xiàn)兩個(gè)團(tuán)隊(duì)對(duì)“服務(wù)層”的定義不一致及時(shí)對(duì)齊后省了大量返工。4.2 從草圖到正式圖規(guī)則落地與樣式統(tǒng)一草圖確認(rèn)后進(jìn)入正式圖制作。這個(gè)階段最重要的是建立樣式模板。我會(huì)先定義好節(jié)點(diǎn)樣式、連線樣式、字體字號(hào)、配色方案然后批量應(yīng)用。不要一個(gè)一個(gè)節(jié)點(diǎn)手動(dòng)調(diào)那樣既慢又容易不一致。以代碼化工具為例我會(huì)先寫一個(gè)樣式配置文件定義好各類節(jié)點(diǎn)的形狀、顏色、邊框、字體。然后畫圖時(shí)只引用樣式名不直接寫具體參數(shù)。這樣后面要改風(fēng)格只需要改配置文件所有圖同步更新。這個(gè)做法在維護(hù)多張圖的時(shí)候特別省事。正式圖制作過程中我會(huì)反復(fù)導(dǎo)出預(yù)覽。每加幾個(gè)節(jié)點(diǎn)就導(dǎo)出看一眼確認(rèn)整體比例和留白是否合適。不要等全部畫完再看那時(shí)候調(diào)整成本太高。預(yù)覽時(shí)重點(diǎn)看三個(gè)地方節(jié)點(diǎn)是否對(duì)齊、連線是否交叉過多、文字是否溢出。4.3 參數(shù)計(jì)算間距、字號(hào)、畫布尺寸怎么定這部分很多人靠感覺其實(shí)可以算。diagram-design 里我常用的參數(shù)規(guī)則是節(jié)點(diǎn)間距不小于節(jié)點(diǎn)寬度的 1/3字號(hào)不小于畫布寬度的 1/100畫布寬高比優(yōu)先 4:3 或 16:9。舉個(gè)例子。假設(shè)畫布寬度 1600px那么正文字號(hào)至少 16px標(biāo)題字號(hào) 24px 到 32px。節(jié)點(diǎn)寬度如果是 160px節(jié)點(diǎn)間距至少 53px取整 60px。這樣算下來一行最多放 1600 / (16060) ≈ 7 個(gè)節(jié)點(diǎn)。如果節(jié)點(diǎn)更多就要考慮換行或縮小節(jié)點(diǎn)。畫布尺寸方面如果要打印用 A4 或 A3 比例如果要投屏用 16:9如果要嵌入文檔寬度控制在 1200px 到 1600px 之間太大加載慢太小看不清。這些參數(shù)不是死的但有一個(gè)計(jì)算依據(jù)比純靠感覺靠譜得多。4.4 交付與迭代圖不是畫完就結(jié)束圖畫完只是開始。diagram-design 的完整流程還包括交付和迭代。交付時(shí)我會(huì)同時(shí)給出三種格式矢量圖用于放大和印刷位圖用于快速預(yù)覽源文件用于后續(xù)修改。并且會(huì)在圖旁邊附一個(gè)簡(jiǎn)短的說明講清楚這張圖的閱讀順序和關(guān)鍵結(jié)論。迭代方面我會(huì)給圖打版本號(hào)每次修改記錄變更點(diǎn)。這樣當(dāng)有人問“為什么這里多了一個(gè)節(jié)點(diǎn)”時(shí)能快速追溯。如果圖是嵌入文檔的我還會(huì)在文檔里保留一個(gè)“圖例說明”章節(jié)解釋圖中用到的所有符號(hào)和縮寫。注意不要把源文件只存在自己電腦里。我吃過虧項(xiàng)目交接時(shí)源文件找不到接手的人只能對(duì)著導(dǎo)出的圖片重畫浪費(fèi)了大量時(shí)間。源文件應(yīng)該和代碼一樣納入版本管理或者至少放在團(tuán)隊(duì)共享空間。5. 常見問題與排查技巧實(shí)錄5.1 圖太亂怎么辦從信息層級(jí)入手圖亂是最高頻的問題。排查順序是先看分組是否清晰再看連線是否過多最后看標(biāo)注是否冗余。分組不清晰就重新劃分區(qū)域連線過多就合并同類關(guān)系標(biāo)注冗余就移到圖例或外部說明。我遇到過一個(gè)典型案例一張微服務(wù)架構(gòu)圖30 多個(gè)節(jié)點(diǎn)50 多條連線完全沒法看。后來做了三件事把非核心服務(wù)折疊成“其他服務(wù)”分組把同步調(diào)用和異步調(diào)用分開畫成兩張圖把連線上的文字全部改成編號(hào)加圖例。改完之后節(jié)點(diǎn)降到 12 個(gè)連線降到 15 條閱讀體驗(yàn)完全不同。5.2 讀者看不懂怎么辦換位思考與用戶測(cè)試圖看不懂往往是作者陷入了“知識(shí)詛咒”——自己太熟悉系統(tǒng)忘了別人不知道。解決辦法是找一個(gè)不了解這個(gè)系統(tǒng)的人讓他看圖并復(fù)述他理解的內(nèi)容。他卡住的地方就是圖需要改的地方。我自己的習(xí)慣是重要圖發(fā)布前至少找兩個(gè)人試讀。一個(gè)是同團(tuán)隊(duì)但不參與該模塊的人一個(gè)是跨團(tuán)隊(duì)的人。前者能發(fā)現(xiàn)專業(yè)術(shù)語問題后者能發(fā)現(xiàn)背景知識(shí)缺失問題。這個(gè)步驟花 10 分鐘能省掉后面無數(shù)解釋成本。5.3 常見問題速查表問題現(xiàn)象可能原因排查方法解決建議圖面擁擠節(jié)點(diǎn)過多或間距過小數(shù)節(jié)點(diǎn)數(shù)量量節(jié)點(diǎn)間距拆圖或增大間距節(jié)點(diǎn)控制在 15 個(gè)以內(nèi)連線像蜘蛛網(wǎng)連線過多或交叉過多統(tǒng)計(jì)連線數(shù)量檢查交叉點(diǎn)合并同類連線調(diào)整節(jié)點(diǎn)位置使用跳線顏色雜亂用色超過三種或?qū)Ρ炔蛔銠z查顏色數(shù)量和對(duì)比度回歸三色原則確保前景背景對(duì)比明顯文字看不清字號(hào)過小或背景干擾縮小到 50% 預(yù)覽增大字號(hào)簡(jiǎn)化背景提高對(duì)比讀者理解偏差符號(hào)不統(tǒng)一或缺少圖例找試讀人復(fù)述統(tǒng)一符號(hào)規(guī)則補(bǔ)充圖例和說明后續(xù)難維護(hù)缺少樣式模板或源文件丟失檢查是否有樣式配置和版本管理建立樣式模板源文件納入版本管理5.4 獨(dú)家避坑技巧我踩過的那些坑第一個(gè)坑過度追求美觀忽略邏輯。早期我花大量時(shí)間調(diào)顏色和陰影結(jié)果圖是好看了但邏輯關(guān)系畫錯(cuò)了被評(píng)審時(shí)一眼看穿。后來我定了個(gè)規(guī)矩邏輯確認(rèn)之前不碰樣式。第二個(gè)坑一張圖想表達(dá)所有信息。這是新手最容易犯的錯(cuò)。一張圖承載太多信息等于沒有信息?，F(xiàn)在我強(qiáng)制自己一張圖只回答一個(gè)問題。如果還有別的問題再畫一張。第三個(gè)坑忽略圖的閱讀動(dòng)線。讀者看圖是有順序的一般是從左上到右下從核心到邊緣。如果圖的布局違背這個(gè)動(dòng)線讀者就會(huì)迷路。我的做法是把最重要的節(jié)點(diǎn)放在左上或中心次要節(jié)點(diǎn)向外擴(kuò)散并用編號(hào)或箭頭引導(dǎo)閱讀順序。第四個(gè)坑不寫圖注。圖注不是可有可無的它是圖的“使用說明”。我現(xiàn)在每張正式圖都會(huì)配一段 100 字以內(nèi)的圖注說明這張圖表達(dá)什么、閱讀順序是什么、關(guān)鍵結(jié)論是什么。這個(gè)小習(xí)慣讓圖的溝通效率提升非常明顯。6. 進(jìn)階技巧讓 diagram-design 成為團(tuán)隊(duì)資產(chǎn)6.1 建立團(tuán)隊(duì)繪圖規(guī)范一個(gè)人畫得好不算什么團(tuán)隊(duì)都能畫得一致才有價(jià)值。diagram-design 的進(jìn)階玩法是把它變成團(tuán)隊(duì)規(guī)范。規(guī)范內(nèi)容至少包括節(jié)點(diǎn)形狀規(guī)則、連線規(guī)則、配色方案、字體字號(hào)、圖例格式、命名約定、版本管理方式。規(guī)范不用一開始就很完善可以先從最常用的三類圖開始架構(gòu)圖、流程圖、部署圖。每類圖定一個(gè)模板新圖從模板開始畫。模板里預(yù)置好樣式和示例降低上手門檻。我參與過的一個(gè)團(tuán)隊(duì)把繪圖規(guī)范寫進(jìn)了技術(shù)文檔模板新項(xiàng)目啟動(dòng)時(shí)直接套用圖的質(zhì)量立刻上了一個(gè)臺(tái)階。6.2 圖與文檔的聯(lián)動(dòng)圖不是孤立的它應(yīng)該和文檔聯(lián)動(dòng)。我的做法是圖里每個(gè)節(jié)點(diǎn)都對(duì)應(yīng)文檔里的一個(gè)章節(jié)或一個(gè)代碼模塊。這樣讀者看圖時(shí)能快速定位到詳細(xì)說明看文檔時(shí)也能快速找到對(duì)應(yīng)的圖。實(shí)現(xiàn)方式很簡(jiǎn)單在節(jié)點(diǎn)命名或標(biāo)注里加上文檔鏈接的錨點(diǎn)或者在圖下方列出“節(jié)點(diǎn)-文檔章節(jié)”對(duì)照表。這個(gè)做法在大型項(xiàng)目里特別有用因?yàn)閳D是概覽文檔是細(xì)節(jié)兩者聯(lián)動(dòng)才能既見森林又見樹木。6.3 自動(dòng)化檢查讓工具幫你守規(guī)則如果團(tuán)隊(duì)用代碼化繪圖工具可以寫一些自動(dòng)化檢查腳本。比如檢查節(jié)點(diǎn)數(shù)量是否超標(biāo)、連線是否有未標(biāo)注的、顏色是否超出規(guī)范范圍。這些檢查可以集成到 CI 流程里圖提交時(shí)自動(dòng)跑一遍不符合規(guī)范的直接打回。我寫過最簡(jiǎn)單的檢查腳本就是統(tǒng)計(jì)節(jié)點(diǎn)數(shù)量和連線數(shù)量超過閾值就報(bào)警。雖然簡(jiǎn)單但很有效能擋住大部分“圖越畫越大”的問題。進(jìn)階一點(diǎn)可以檢查節(jié)點(diǎn)命名是否符合約定、是否有孤立節(jié)點(diǎn)、是否有循環(huán)依賴。這些檢查能大幅提升圖的整體質(zhì)量。6.4 從圖到系統(tǒng)認(rèn)知diagram-design 的長期價(jià)值最后說點(diǎn)務(wù)實(shí)的。diagram-design 做得好短期看是圖好看、溝通順長期看是團(tuán)隊(duì)對(duì)系統(tǒng)的認(rèn)知更清晰。一張好的架構(gòu)圖本身就是系統(tǒng)設(shè)計(jì)的濃縮。新人入職看圖就能快速理解系統(tǒng)結(jié)構(gòu)跨團(tuán)隊(duì)協(xié)作看圖就能對(duì)齊邊界技術(shù)評(píng)審看圖就能發(fā)現(xiàn)潛在問題。我在一個(gè)持續(xù)兩年的項(xiàng)目里前后畫了 20 多張圖形成了完整的圖集。后來項(xiàng)目交接時(shí)這套圖集成了最重要的資產(chǎn)之一接手團(tuán)隊(duì)靠它在一周內(nèi)就摸清了系統(tǒng)全貌。這比讀幾十萬字文檔快得多。所以 diagram-design 不只是畫圖技巧它是系統(tǒng)認(rèn)知的可視化沉淀。你畫的每一張圖都是在為團(tuán)隊(duì)積累認(rèn)知資產(chǎn)。這個(gè)內(nèi)容后續(xù)還可以這樣擴(kuò)展把圖集和代碼倉庫關(guān)聯(lián)每次代碼結(jié)構(gòu)變更時(shí)自動(dòng)提醒更新對(duì)應(yīng)圖或者把圖集做成可交互的版本點(diǎn)擊節(jié)點(diǎn)跳轉(zhuǎn)到對(duì)應(yīng)代碼或文檔。這些方向都值得嘗試但前提是先把基礎(chǔ)的 diagram-design 規(guī)則跑通。規(guī)則穩(wěn)了工具和自動(dòng)化才有意義。