1. 為什么大部分架構(gòu)圖、流程圖讓人看得一頭霧水很多技術(shù)項目做到中期之后最稀缺的資源往往不是代碼注釋而是一張能讓新同學在三分鐘內(nèi)建立全局認知的圖。diagram-design 是我在一次大規(guī)模系統(tǒng)梳理過程中被迫做出來的圖表設(shè)計方案——它不是什么酷炫的設(shè)計軟件也不要求你有平面設(shè)計功底而是一整套從信息結(jié)構(gòu)到視覺表達都有明確約定的實操方法。這篇文章把它完整記錄下來包括背后的原理、落地時選的工具鏈、一次真實的重構(gòu)過程以及那些反復踩過的坑適合經(jīng)常畫架構(gòu)圖、流程圖、時序圖但總覺得畫出來沒人看的開發(fā)者和架構(gòu)師。先說一個我觀察到的規(guī)律凡是團隊協(xié)作順暢的項目文檔里一定有一兩張公認的主圖凡是溝通成本高的項目往往就是缺一張所有人都認的圖。圖的本質(zhì)是思維模型的投影圖亂通常意味著思維沒理順。diagram-design 這個名字看起來很樸素但它的目標很直接——讓每一張圖都能回答三個問題系統(tǒng)里有什么誰和誰有什么關(guān)系事情按什么順序發(fā)生如果畫圖前沒想清這三個問題那畫出來的就只是裝飾過的混亂。1.1 一個反直覺的事實圖不是越滿越好大多數(shù)人畫圖的第一反應是把知道的東西全部畫上去。我曾見過一張系統(tǒng)現(xiàn)狀圖二十多個節(jié)點、十幾條連線每個節(jié)點里都塞了三五行說明文字甚至把配置文件的路徑和備注也搬了上去。結(jié)果整張圖變成一面文字墻放大三倍才能看縮小一版又什么都看不清。問題出在人的認知帶寬上。眼睛在快速掃視一張圖時真正在處理的信息其實很少先看大致分區(qū)再看幾個關(guān)鍵節(jié)點然后沿著主干連線走一遍。如果所有信息都用同等力度被呈現(xiàn)等于沒有重點。我把這種狀態(tài)稱為信息平鋪它是圖表可讀性的頭號殺手。你可以把它類比成一張地圖——如果每條小巷、每個店鋪、每個公交站都標出來這張地圖就失去導航價值了。圖的核心價值恰恰是選擇性地放大關(guān)鍵信息主動屏蔽次要細節(jié)。一張圖能承載的信息量是有限的所以畫圖前必須先做取舍而不是把腦內(nèi)全部存量直接傾倒到畫布上。能夠刪掉的內(nèi)容越多剩下的內(nèi)容才越值錢。1.2 四種最常見的廢圖每張都浪費了團隊的耐心這幾年我評審過的設(shè)計圖沒有一百也有八十至少有一半可以直接歸入下面四類遇到這種圖我通常會讓作者拿回去重畫。第一種是元素堆砌圖。所有節(jié)點平鋪在畫布上核心服務、附屬模塊、外部系統(tǒng)混在一起大小一致、位置隨意。讀者需要自己從一堆方框里猜哪個是入口、哪個是終點。這種圖適合用來自我安慰顯示我畫了架構(gòu)圖實際上誰也不想細看。第二種是箭頭亂飛圖。連線沒有任何布線規(guī)則能直走偏要繞彎能并行偏要交叉。更致命的是不同類型的依賴關(guān)系全部用同一種實線箭頭表達讀者要自己推斷每條箭頭的語義。當連線的走向和含義都需要猜測時這張圖就已經(jīng)失去溝通功能了它只是看起來在表達關(guān)系而已。第三種是彩虹圖。每個模塊一個顏色漸變、熒光、高飽和色全部上陣畫的時候覺得自己層次分明打印成黑白文檔后什么都分不清。顏色如果只是裝飾它就是噪音而不是信息。一張合格的圖應該做到去色之后仍然可以正常閱讀。第四種是說明書圖。作者舍不得丟掉任何信息把一整個項目介紹塞進節(jié)點文字溢出邊界、字號縮到八號讀者要把臉貼到屏幕上才能看清。圖的優(yōu)勢是呈現(xiàn)結(jié)構(gòu)不是承載細節(jié)一旦追求信息完整性就等于放棄了圖形表達的所有優(yōu)勢。你可以對照一下手頭的圖只要命中了其中一條基本就可以認定它在日常協(xié)作中是低效的。不必自責這是大多數(shù)人都會經(jīng)歷的階段。真正的轉(zhuǎn)折點是你意識到畫圖是一種可被設(shè)計的工程活動的時候。2. diagram-design 的底層思路先定信息結(jié)構(gòu)再排視覺元素2.1 項目的起點一張無人能讀懂的全景圖我為什么非要做一個叫 diagram-design 的項目原因是某次線上問題復盤。當時一群人圍著一面墻上面貼著一張?zhí)柗Q系統(tǒng)全景圖的大圖每個人都順著箭頭找鏈路找了五分鐘也沒找到一條完整通路。最后發(fā)現(xiàn)圖里三個不同的箭頭指向同一個節(jié)點但它們分別表達數(shù)據(jù)流向控制調(diào)用和配置依賴作者沒有做任何區(qū)分。復盤結(jié)束后我做了個決定不再依賴個人感覺畫圖而是把圖表設(shè)計當成一個有輸入、有輸出、有規(guī)則的工程流程來對待。于是就有了 diagram-design。它本質(zhì)上是一份我私人的畫圖規(guī)范后來在幾次跨團隊方案評審里被反復使用效果出乎意料地好——不是因為它多專業(yè)而是因為它強迫你在動筆之前先回答問題。這件事給我最大的啟發(fā)是大部分圖爛不是畫圖技巧問題而是思考順序問題。大多數(shù)人是先拉幾個框再連線邊畫邊想畫完自己都不確定邏輯對不對。正確順序應該反過來——先確保信息結(jié)構(gòu)經(jīng)得起推敲再動手設(shè)計視覺呈現(xiàn)。2.2 三個核心維度層級、流向、邊界我把任何一張技術(shù)類圖表都拆成三個基本面層級、流向、邊界。這三者分別回答有什么怎么走歸誰管。層級解決的是主次問題。一張圖必須有一眼可見的層級差核心節(jié)點視覺權(quán)重最大附屬節(jié)點其次外部依賴最弱?？梢杂贸叽?、位置、容器三重手段來表達。最保險的做法是讓核心服務占據(jù)畫布中央偏左的位置體量最大周邊模塊按依賴關(guān)系環(huán)繞排列而不是所有人等大小均勻排開。圖里面所有節(jié)點體量都一樣時層級就消失了這就是我之前說的信息平鋪。流向解決的是順序問題。圖里每一個箭頭都應該有明確語義是同步調(diào)用、異步消息、數(shù)據(jù)流還是物理鏈路這必須通過線型和圖例固定下來。更重要的是一張圖最好只有一條主流向其他都是支流。我畫圖時經(jīng)常問自己如果整張圖只能讀懂一條路徑應該讓讀者讀哪條那條就是主鏈路。主鏈路要盡量平直、少打斷、少交叉從入口一路通到出口。邊界解決的是歸屬問題。哪些模塊屬于同一個業(yè)務域哪些屬于同一個部署單元哪些是外部系統(tǒng)邊界通常用容器表達——一個大圓角矩形把若干個節(jié)點包起來再給它一個名字。邊界畫不清楚圖里就會出現(xiàn)跨系統(tǒng)直連的假象好像不同模塊可以直接通信實際上中間還隔著一層網(wǎng)關(guān)。很多爭議圖本質(zhì)上是邊界畫錯了。2.3 一套最小可行的圖形語言約定形狀、線型、色板只有原則不行必須落地成看得見、可復制的約定。diagram-design 里我規(guī)定了一套三件套形狀表示元素類型線型表示關(guān)系類型顏色表示歸屬或狀態(tài)。形狀方面我規(guī)定圓角矩形代表服務或模塊直角矩形代表數(shù)據(jù)存儲或外部系統(tǒng)菱形代表判斷分支圓柱體代表消息隊列或緩存。不要一個項目里出現(xiàn)七八種形狀形狀越多讀者的記憶負擔越大。只有四種每種都有明確含義配一個圖例放在圖的角落。線型方面實線表示同步強依賴虛線表示異步或弱依賴雙線表示物理鏈路或數(shù)據(jù)復制。這樣既能把復雜的依賴關(guān)系區(qū)分開又不會太燒腦。配合方向還要約定箭頭只在語義明確時出現(xiàn)如果一條線只表達屬于或包含關(guān)系就可以不畫箭頭甚至用普通線段。顏色方面這是我踩坑最多的地方?，F(xiàn)在我的色板嚴格限制在五種以內(nèi)并且每種顏色必須對應一個圖例說明。比如藍色表示核心鏈路灰色表示支撐組件綠色表示數(shù)據(jù)存儲黃色表示外部系統(tǒng)。顏色承擔語義不承擔裝飾。同一層級的所有節(jié)點顏色保持不變哪怕它們在不同容器里。為了兼容黑白打印我還會在關(guān)鍵節(jié)點上加淺底色或邊框粗細變化確保丟掉顏色信息后依然能辨認主次。這套約定并不復雜但它保證了團隊里任何一個人畫出來的圖另一個人都能無障礙讀懂。約定之所以能被堅持是因為它的記憶成本極低——不需要查手冊只要貼在圖例區(qū)就行。比約定更重要的是它逼著你在畫圖前先問這個元素是什么類型這條線是什么關(guān)系這個顏色是什么含義問題答完了圖心里已經(jīng)畫好一半。3. 落地工具鏈把規(guī)范固化到軟件和流程里3.1 為什么我放棄了在線協(xié)作白板選了開源離線繪圖工具規(guī)范定得再好如果工具不支持最后還是會被拋棄。我在 diagram-design 項目里走了一圈彎路一開始用的是在線協(xié)作白板大家都能同時編輯自帶各種便捷的容器模板看起來很適合畫架構(gòu)圖。但用了兩個月就發(fā)現(xiàn)三個問題。第一在線白板的文件格式是私有的導出成圖片之后再想改一處細節(jié)就得回到白板里去操作無法在代碼評審里查看結(jié)構(gòu)性變更。第二多人同時編輯時很容易出現(xiàn)一人拖動節(jié)點、另一個人的布局全亂的情況協(xié)作反而變成了相互干擾。第三在線工具的免費額度有限一旦項目變大文檔數(shù)量一多要么付費要么面臨導出限制。后來我換成了開源離線繪圖工具文件以純文本格式保存每個節(jié)點、每條線都是可讀的文本描述。這意味著圖表文件可以直接放進代碼倉庫跟代碼一起走版本管理和變更評審。離線工具的畫布操作雖然沒那么平滑但勝在確定性高布局是你完全掌控的不會因為別人動了一下畫布而全部亂套。在我這個項目里哪怕犧牲一點界面流暢度也必須換取文件可讀、可 diff、可回溯。代碼評審能把一段邏輯變更講清楚圖表為什么不能答案是完全可以前提是你選的工具愿意把文件格式開放給你。3.2 元件庫和模板頁讓規(guī)范長在工具里而不是躺在文檔里很多人定了規(guī)范就完事了放在新人文檔里吃灰。我的做法是讓規(guī)范長在繪圖工具里打開文件就能用。具體的做法是在繪圖工具里面建一個專門的元件庫頁把之前定義的四類形狀、五類線型、五色色板全部放到這一頁每個元件下方標注它的用途和命名規(guī)則。真正畫圖時從元件庫里復制粘貼而不是從工具欄里從頭拖拽。這樣出來的圖形天然統(tǒng)一不存在有人用了圓角矩形、有人用了直角矩形這種半路走樣的情況。同類型圖使用統(tǒng)一模板頁頁面尺寸統(tǒng)一圖例區(qū)固定放在右下角主標題放在左上角版本號放在頁腳。每個模板頁里還預留了評審意見區(qū)讓評審人可以直接在圖上批注。模板的作用不是限制發(fā)揮而是讓每一次新畫圖都不用重新發(fā)明排版。我實測下來一旦大家習慣了這套模板新圖畫起來的速度反而比自由發(fā)揮快很多因為不需要糾結(jié)每個元件的樣式只需要把精力放在信息組織上。3.3 把圖表納入代碼倉庫diff 審查解決靜默變化圖表一旦進入代碼倉庫就可以享受版本控制系統(tǒng)帶來的好處。我在倉庫里專門建了一個目錄存放所有正式圖表文件。每次有人提交圖表變更代碼評審的 diff 頁面里能直接看到新增了一個節(jié)點刪除了一條連線某個節(jié)點改了顏色這種細顆粒度的變化。這比截圖對比要可靠得多因為截圖只能看到視覺差異看不到作者改動的意圖。評審重點三件事結(jié)構(gòu)是否變化、流向是否被破壞、邊界是否移動。如果只是新增了一個附屬節(jié)點那沒問題如果把主鏈路的箭頭方向反了那就得說明為什么。為了讓評審更省力我要求提交者必須在變更說明里寫清楚這次改動的對象是層級、流向還是邊界。剛開始團隊成員覺得這樣太重了畫個圖還要走評審流程。但隨著圖資產(chǎn)積累得越來越多大家發(fā)現(xiàn)這套機制最大的價值是防止靜默腐化——一張圖被改著改著就偏離了原有設(shè)計但沒有人察覺。有了 diff每次變化都被記錄在案圖的演進歷史完全透明。到今天這套流程已經(jīng)變成項目里約定俗成的規(guī)矩沒有人再問為什么要為一張圖搞這么正式。4. 實戰(zhàn)把一張元素堆疊技術(shù)圖改造成清晰架構(gòu)圖4.1 原圖診斷一眼看去是墻細看全是洞我拿一個真實的改造案例來說。這是一張支付鏈路相關(guān)模塊的技術(shù)現(xiàn)狀圖畫的人其實很有耐心二十六個節(jié)點十六條連線十個不同顏色每個節(jié)點內(nèi)部都有一段描述文字。我第一眼看到這張圖的感覺不是內(nèi)容真多而是壓力真大。為了找出它的問題我按 checklist 過了一遍層級關(guān)系沒有。核心服務、數(shù)據(jù)庫、第三方接口全部平鋪沒有容器沒有主次。流向語義沒有。實線、虛線、粗箭頭混用全都沒有圖例說明有些線甚至沒有方向。邊界歸屬沒有。哪些模塊屬于同一個進程哪些模塊屬于外部系統(tǒng)完全看不出來。顏色語義沒有。十個顏色純屬裝飾沒有一種顏色能讓我一眼看出這是核心鏈路。最致命的是門面節(jié)點里的文字無法快速定位。我嘗試從左上角開始順著連線走走了三步就迷路了——因為兩條線在中間交叉而交叉處沒有橋接標識我無法判斷它們是各自通行還是要發(fā)生交互。這不是讀者粗心而是作者把信息結(jié)構(gòu)層面的問題全部用視覺密度掩蓋了。4.2 重構(gòu)步驟從元素清單到最終布局我將重構(gòu)拆成六個步驟這六個步驟是 diagram-design 方法論的縮影。第一步重新列元素清單。把原圖里的所有節(jié)點抄出來標注類型哪些是服務哪些是存儲哪些是外部依賴哪些只是備注。刪掉備注類和重復類節(jié)點最終保留十六個必要元素。這個步驟最花時間因為它要求你對系統(tǒng)邊界有足夠清晰的認知。第二步劃分層級。我把十六個元素分成五組用戶入口、接入層、核心服務、數(shù)據(jù)層、外部依賴。其中用戶入口和數(shù)據(jù)層是配角核心服務是主角外部依賴只放在邊上。分組完成后再把它們放進容器里每組一個容器容器之間有明確的邊界。第三步確定主鏈路。這張圖最核心的流程是用戶請求從入口進來經(jīng)過接入層由核心服務處理落庫并返回結(jié)果。我把這條主鏈路放在畫布中央偏左從左上到右下路徑盡可能平直。主鏈路上的節(jié)點用核心色填充支鏈路上的節(jié)點用灰色填充。第四步先畫主鏈路再補支路。很多人習慣把所有節(jié)點一次性拖上來我相反一開始畫布上只有三四個節(jié)點入口、核心服務、存儲、出口。主鏈路走通以后再逐個添加分支每加一個就檢查一次新連線是否會造成交叉。這個方法能控制復雜度避免一上手就陷入連通圖。第五步統(tǒng)一線型。同步調(diào)用用實線異步通知用虛線外部系統(tǒng)的 HTTP 調(diào)用用獨立標注。每條線只保留一個含義沒有亦此亦彼的曖昧。第六步刪減文字。每個節(jié)點只留名稱和一行核心說明其他細節(jié)移到圖例或附注區(qū)。如果節(jié)點文字超過二十個字符就說明該信息應該放在文擋而不是圖里。最終呈現(xiàn)在畫布上的是十六個元素五個容器四條主鏈路線八條支路四種顏色。節(jié)點之間零交叉黑白打印后依然能分辨主次。4.3 前后對比與評審反饋從看不懂到三十秒講清改造前后的對比非常鮮明。原圖二十四號節(jié)點擠在 A3 畫布里信息密度極高評審會上大家的第一反應是沉默——因為沒人敢承認自己沒看懂。新圖出來的那天我在評審會上說請大家先用三十秒看這張圖然后每人講一遍主流程。結(jié)果是每個人都講對了連新來的實習生都能順著主鏈路把請求全過程串下來。核心原因不是大家變聰明了而是這張圖已經(jīng)把先看什么、后看什么、什么是重點全部安排好了。閱讀順序就是視覺引導順序不再需要讀者自己去闖迷宮。這次改造也讓我意識到一個規(guī)律圖的復雜度不取決于系統(tǒng)真實復雜度而取決于作者有沒有做信息分級。同樣的系統(tǒng)有人畫成二十六個節(jié)點的混沌網(wǎng)有人畫成十六個節(jié)點的清晰分層結(jié)構(gòu)差距不在于系統(tǒng)只在于思考深度的差異。評審會上不需要夸這張圖漂亮因為它本來就該長這樣——清晰不是恩賜而是設(shè)計的結(jié)果。5. 可讀性自檢清單與踩坑記錄5.1 五條便宜又有效的自檢規(guī)則diagram-design 項目運行一段時間后我沉淀出一份檢查清單。每張圖在提交前都過一遍大概能過濾掉八成以上的常見問題。第一條是三秒鐘原則。把圖縮到剛好能一眼看完的大小盯著它三秒鐘能不能說出主流程說不出說明圖的引導結(jié)構(gòu)有問題。這一條能逼你分清主次。第二條是零交叉原則。全圖連線交叉數(shù)為零這是硬性要求。如果交叉不可避免至少要用橋接線或繞行來消除視覺歧義。交叉不是錯讓人分不清交叉處是否發(fā)生交互才是錯。第三條是顏色可去原則。把圖復制一份轉(zhuǎn)成灰度看看還能不能讀懂。如果信息隨著顏色一起消失了說明你的顏色承擔了唯一表達通道而這不是所有讀者都具備的閱讀條件。第四條是圖例先于圖形原則。一張圖如果出現(xiàn)了三種以上形狀、兩種以上線型或三種以上顏色就必須有圖例。圖例不是附加題它是圖的一部分。第五條是字號底線原則。節(jié)點內(nèi)的文字不得小于某號字保證在 150% 縮放比例下依然可讀。為了塞更多內(nèi)容而縮小字號是止損還是注水答案通常是后者。5.2 踩過的幾個具體坑箭頭、彩虹色和圖例缺失規(guī)范不怕不完美就怕不執(zhí)行。我自己就在執(zhí)行過程中踩過不少坑。第一個坑是強調(diào)箭頭。我第一次畫主鏈路圖時為了突出核心流程把主鏈路的箭頭畫得特別粗還加了深色填充。結(jié)果發(fā)現(xiàn)讀者視線一開始就被箭頭吸走反而忽略了箭頭兩端的節(jié)點——連線的視覺權(quán)重超過了節(jié)點這是本末倒置。后來我規(guī)定連線永遠比節(jié)點輕強調(diào)手段只能作用于節(jié)點本身不能作用于連線。第二個坑是彩虹色復發(fā)了。我以為自己已經(jīng)規(guī)定了五色板結(jié)果在美化階段還是忍不住給某些模塊加了漸變填充。表面上看層次更豐富實際上漸變讓節(jié)點邊界變模糊打印之后更是災難。從那以后我徹底禁止?jié)u變把色板固定在純色范圍內(nèi)。第三個坑是圖例缺失。有一次我用不同顏色區(qū)分生產(chǎn)和測試環(huán)境畫完覺得很清晰結(jié)果新同學對著圖完全懵了——他不知道紅色是生產(chǎn)還是測試因為整張圖右下角沒有圖例。這個坑讓我把圖例必須存在變成了硬性要求而不是可選項。第四個坑是強制網(wǎng)格對齊。為了讓節(jié)點整齊我把所有方框都對齊到同一網(wǎng)格結(jié)果主鏈路被迫繞了一個大彎反而增加了連線交叉。整齊不應該是形式上的而應該服務于信息流。只要信息流清晰少量錯位是可以接受的。5.3 多人協(xié)作下怎么保證規(guī)范不被慢慢磨掉最后是協(xié)作問題。規(guī)范最大的敵人不是沒人讀而是這次破例沒關(guān)系。一旦破例兩次規(guī)范就名存實亡。我的做法有三個。第一默認模板強制約束——所有圖從模板頁復制模板里的色板、元件、圖例區(qū)都是現(xiàn)成的想自由發(fā)揮也得多費力氣。默認約束比事后提醒更有效。第二圖表變更走確認流程。哪怕很小的改動也要走一次快速評審。這不是為了卡人而是為了保持結(jié)構(gòu)的連續(xù)性。評審人不需要審查每一處對齊只需要關(guān)注層級、流向、邊界三個維度有沒有被破壞。如果連續(xù)三次變更都沒有引起結(jié)構(gòu)問題人就可以放行。第三定期做一次結(jié)構(gòu)化回顧大概每個月花半小時把庫里比較重要的圖重新過一遍看看有沒有出現(xiàn)信息平鋪回潮、顏色泛濫或標注缺失的苗頭。提醒比整改成本低得多而且往往復查時就能順手修掉。很多人覺得管圖比畫圖麻煩但實際上開始管理之后畫圖反而變輕松了——因為每次畫圖你用的都是驗證過的模板和元件不需要重新摸索樣式。規(guī)范不是在限制你而是在替你提前解決問題。diagram-design 這個項目做下來我最深的一個體會是圖表設(shè)計的門檻從來不在工具也不在審美而在你是否愿意在動筆之前把結(jié)構(gòu)想清楚。只要信息結(jié)構(gòu)是對的哪怕圖形樸素讀者也能讀懂信息結(jié)構(gòu)不對再漂亮的設(shè)計也只是在給混亂化妝。如果你也想開始我的建議很簡單找一張自己近期畫過的、看了頭疼的圖用本文的步驟重新做一次信息分級然后把它放到三分之一的尺寸下看看——你自己會感受到差距。