用 LaTeX 畫軟體架構圖

最近在實驗一些從頭刻一個系統架構的最精準方法。除了程式碼要解耦、邏輯要對稱：到底該怎麼用最工程化的方式，「刻」出一張不會亂跑、且能精準表達邏輯的架構圖？讓我想到 LaTeX。以前在寫論文的時候 LaTeX 真的是好朋友，解決了很多排版的問題，但缺點就是難上手，很多語法要記，還有不太直覺。不過這些缺點在 AI 時代被縮小了。

當然畫圖工具很多，但對本來就有在用 LaTeX 的人來說，這是一個選項。

為什麼不直接用 Mermaid ？

在當今的開發流程中，Mermaid 已經是很多人的標配了。但用過的人一定會發現，當系統架構稍微複雜一點，這些基於演算法的自動排版很難調整。

設想現在要畫一個基本架構圖。假設我們有一個非常常見的微服務架構：User 呼叫 API Gateway，Gateway 再將流量分別路由到 Auth Service（身分驗證）與 Order Service（訂單服務），最後這兩個服務都會連線到同一個共用的 Database。在 Mermaid 的世界裡，我們只能定義「關係」，排版則完全交由底層引擎去算。你的程式碼大概會長這樣：

graph TD
    User[User] --> API[API Gateway]
    API --> Auth[Auth Service]
    API --> Order[Order Service]
    Auth --> DB[(Database)]
    Order --> DB

因為 Mermaid 的排版引擎，首要任務是「避免線條交叉」與「尋找最短路徑」，如果要在既有的架構圖中加上其他物件，例如 Extra Monitoring，算出來的結果往往會失去對稱美感。那個共用的 Database 常常會被莫名其妙地擠到某個服務的角落，或是整棵架構樹的重心歪了一邊。

graph TD
    User[User] --> API[API Gateway]
    API --> Auth[Auth Service]
    API --> Order[Order Service]
    API --> Extra[Extra Monitoring Node]
    Auth --> DB[(Database)]
    Order --> DB

LaTeX 的做法：絕對的空間控制權 (Absolute Layout Control)

這讓我想到以前寫論文的最佳幫手 Latex。 LaTeX 與 TikZ 繪圖引擎，這也是這套方法最核心的理念 — — 把排版的控制權 100% 拿回自己手裡。

透過自定義的樣式模板，我們不再依賴系統盲猜，而是直接跟組件確認好整體layout。你可以明確地下達指令：「把 Database 精準錨定在 Gateway 的正下方 5 公分處」，然後「把 Auth 和 Order 服務分別推向左右兩側」。

\documentclass[margin=20pt]{standalone}
\usepackage{../modern-c4-style}

\begin{document}
\begin{tikzpicture}[auto, >=stealth]

    % 1. Central Axis: Place User and API Gateway in the center
    \node[c4_person]  (user) at (0, 0) {User};
    \node[c4_system]  (api)  [below=2cm of user] {API Gateway};

    % 2. Absolute Control: Anchor DB firmly below the API Gateway
    \node[c4_database] (db)  [below=4cm of api] {Database};

    % 3. Symmetrical Layout: Push services to the left and right of the API
    \node[c4_container] (auth)  [left=2cm of api] {Auth Service};
    \node[c4_container] (order) [right=2cm of api] {Order Service};

    % 3.5 Add Extra Node while maintaining symmetry
    \node[c4_external] (extra) [below right=2cm and 1cm of order] {Extra Monitoring};

    % 4. Routing Lines
    \draw[c4_rel] (user) -- (api);
    \draw[c4_rel] (api) -- (auth);
    \draw[c4_rel] (api) -- (order);

    \draw[c4_rel] (api.south east) edge[bend right=40] node[below, sloped] {Metrics} (extra.south west);

    % Use |- to draw elegant orthogonal (right-angle) lines
    \draw[c4_rel] (auth.south) |- (db.west); 
    \draw[c4_rel] (order.south) |- (db.east); 

\end{tikzpicture}
\end{document}

我可以確保 User 到 Database 佈局的中軸線不動。

這看起來好像把一個簡單的 mermaid 複雜化了。還要自己去定義空間配置跟個物件的座標。在以前確實非常麻煩 … 但我發現用 AI Agent 去操作 tex file 非常快速，一瞬間就可以把layout 畫好 8成以上，自己再進來微調字型大小等細節。甚至還可以事先把所有風格檔寫好。再寫好 AI Agent Skill ，直接完成 Document as a Code 加上 Diagram as a Code 🚀。

我把 class 跟 style 檔案寫好放在 github 上，有興趣的話可以參考一下。 https://github.com/PenHsuanWang/latex-diagram-drawing

簡單說一下調整圖表方式

• 調整位置： 直接在 .tex 檔裡面修改 [below=2cm of user] 等相對距離參數。
• 字體大小： 可以透過 font=\small 或全域變數來靈活定義。

如果要調整位置可以直接在 tex 檔裡面調整

字體大小也可以自己定義

LaTeX 在工程上的優勢

既然我們談到了「Document as a Code 加上 Diagram as a Code」，除了能用 AI 幫忙寫 code 之外，這套純文字的工作流在團隊協作與長期維護上，還有兩個傳統工具難以企及的優勢。

1. Git 版本控制與 Code Review 終於對齊了

回想一下我們過去使用 Visio、Draw.io 或是 Excalidraw 畫圖的經驗。這些工具產出的通常是 .vsdx、.drawio 或 .png 等二進位或封閉格式檔案。當系統架構發生演進時，你在 Git 的 Commit 紀錄裡只能看到「檔案已修改」，卻無法得知細節。同事發 PR 的時候，Reviewer 根本無從得知「到底是 A 服務被移除了？」還是「B 服務新增了一條連向 C 服務的線？」。 但切換到 LaTeX 後，因為所有的節點和連線都是純文字的 .tex 檔，架構的每一次迭代（例如從單體架構拆分為微服務），都能在 Git 的 Commit 歷史中留下清清楚楚的軌跡。透過原生的 Git Diff，新增了什麼模組、修改了哪條路由一目瞭然。這對於技術文件的長期維護與團隊 Code Review 來說，tex是一個方便維護的方式。

2. 像寫 CSS 一樣的模組化與樣式重用

另一個讓AI 可以加入圖表協作，加強工程實作的點，是強大的「模組化」能力。想像一下，如果團隊想把架構圖的主題色換成更現代的色系。用傳統的繪圖軟體，你可能要手動打開幾十張圖表，用滑鼠一個個點選方塊去修改顏色，不僅耗時還非常容易漏改。 但在 LaTeX 的架構裡，我們可以像寫網頁的 CSS 一樣集中管理樣式。以我的專案為例，所有的視覺設定都被抽離到了 modern-c4-style.sty 這個檔案中。我在裡面定義了一次全域變數（例如 \definecolor{SystemBlue}{HTML}{3B82F6}），一旦未來需要更改主體顏色，我只需要修改這個檔案裡的一行色碼。重新編譯後，專案裡所有的架構圖就會瞬間、毫無遺漏地套用新顏色。這才是完美的樣式重用，真正落實了 DRY (Don’t Repeat Yourself) 原則。

額外的成本與缺點

當然，追求極致的排版控制權必然伴隨著權衡（Trade-offs），我們也必須誠實面對引入 LaTeX 所帶來的隱藏成本。首先是「環境摩擦力」與「團隊學習曲線」的挑戰：相較於 Mermaid 在 GitHub 或 Notion 中隨插即用的網頁原生支援，LaTeX 必須仰賴額外的 CI/CD Pipeline 進行編譯才能產出圖檔，增加了基礎設施的維護成本；且 TikZ 語法對多數工程師而言相對生硬，即便有 AI 輔助，一旦編譯出錯仍需具備先備知識才能人工除錯，這無疑拉低了團隊的「公車指數」，增加推廣難度。更深層的工程隱憂則在於「模型與視圖（Model-View）的高度耦合」：當我們寫下 \node [below=4cm] {Database} 時，其實是將「業務邏輯（它是一個資料庫）」與「排版邏輯（它在下方 4 公分處）」死死綁定。這違背了現代架構提倡的關注點分離原則，一旦未來需要將圖表資訊自動化轉換為清單或循序圖，這些被硬編碼在座標內的節點資料將變得極難抽離與重構。