SharePoint 頁面上的架構圖已建立於 2009 年。當時它是準確的,反映了系統在一次重大平台遷移時的現狀,由一位架構師繪製,他花了三週時間記錄了每個組件及其相互關係。自 2009 年以來,該系統已收到約 4,800 次提交,15 個團隊為其做出貢獻,圖中所示的四個組件已不再存在,新增了 11 個組件但從未繪製過架構圖,而繪製該圖的架構師已於 2016 年退休。然而,該架構圖仍然存在。當新開發人員加入並詢問「系統如何運作?」時,有人會將 SharePoint 連結發送給他們。此架構圖並非文檔,而是考古資料。
文檔債務是將技術債務應用到文件層面:即文件對系統的描述與系統實際運作方式之間的累積差距。架構漂移,也就是圖表與其所描繪的系統脫節,是最常見且最危險的文檔債務形式。它之所以危險,是因為它會給人一種虛假的自信:一張現成的、看起來專業的圖表會讓利益相關者誤以為系統已被理解,而實際上他們看到的只是一份歷史遺留物,描述的是一個早已不再以圖中所示形式存在的系統。過時的圖表比沒有圖表更糟糕,因為沒有圖表不會促使人們去了解系統的真實情況;而過時的圖表則會誘使人們基於不再適用的資訊採取行動。
導致圖表過時的五大機制
所有關於文件老化的文章都會提到“圖表會隨著時間推移而過時”,但幾乎沒有文章解釋造成這種情況的具體機制。理解這些機制是預防文件老化的前提,因為不同的機制需要不同的預防策略。
1. 累積增量問題。系統圖是系統在某一時刻的快照。快照之後的每一次程式碼變更都會造成系統圖與實際情況之間的增量。單一增量通常很小,例如新增一項服務、重新命名一個元件或新增一個依賴項。單獨來看,每個增量都很容易記錄。問題在於,沒有人會定期記錄這些增量,因為每次變更都更新系統圖會被視為一種沒有即時效益的額外開銷。當未記錄的增量達到 100 個時,系統圖就會出現實質錯誤。當未記錄的增量達到 1,000 個時,系統圖就幾乎完全是虛構的了。
2. 缺失的溯源問題。如果圖表與它所描繪的程式碼之間沒有程式上的關聯,那麼它就無法偵測自身何時變得不準確。當程式碼庫的變更與圖表中的某個說法相矛盾時,沒有任何訊號會觸發。圖表和代碼是彼此獨立的產物,它們恰好都描述了同一個系統,但這種關聯僅存在於繪製圖表的人的腦海中,並且只在他們記得的時候才存在。
3. 所有權移轉問題。架構圖通常由特定人員在特定時間創建。當此人離職時,使架構圖準確無誤的隱性知識,例如哪些組件被有意省略、哪些關係被簡化、哪些標籤是更複雜概念的簡寫等,也隨之流失。架構圖的新保管者繼承的並非自己創建、可能不完全理解的成果,而且由於程式碼庫並非自己設計,因此也沒有動力去維護它。
4. 過度精細導致的衰減問題。過於詳細的圖表比抽象程度適中的圖表更容易過時。一張包含所有微服務、所有 API 端點和所有資料庫表的圖表,每次部署都需要更新。而一張只展示服務域及其主要互動模式的圖表,只需在域邊界發生變化時更新即可。過於精細的圖表的「半衰期」以迭代週期來衡量;而抽象程度適中的圖表的「半衰期」則以季度來衡量。
5. 格式鎖定問題。以 Visio 檔案、PowerPoint 投影片、PNG 匯出或 PDF 附件形式儲存的圖表無法透過程式設計產生、驗證或比較。由於圖表是像素圖像而代碼是文本,因此無法詢問“此圖表是否仍然與代碼匹配?”。圖表建立時選擇的格式決定了該圖表是否能夠與它所描述的系統進行驗證。
遺留系統文件災難
對於擁有活躍開發團隊的現代化雲端原生系統而言,架構圖過時是一個管理問題,可以透過架構即程式碼實踐、動態文件工具和工程規格來解決。系統頻繁變更;如果流程正確,架構圖可以更新以適應變更。
對於遺留系統而言,問題本質上不同,而不僅僅是程度不同。
1992 年大型主機系統設計評審期間繪製的架構圖,自創建以來可能已經累積了 30 年的程式碼變更。對複雜的 COBOL 程序組合進行持續維護,每年產生數百次提交,新增程序,停用舊程序,更新副本,重組 JCL 作業流程。 1992 年的架構圖在當時是準確的,但此後每年的準確性都在逐漸下降。到 2026 年,架構圖與實際系統之間的差距可能比原始系統本身還要大,而且架構圖中未包含的新程式數量可能比原始系統中仍按原設計運行的程式數量還要多。
真正造成災難性後果而非僅僅是不便的原因在於圖表的使用方式。當現代化團隊前來評估系統時,他們並不知道圖表是錯的,也無從得知錯得有多離譜。圖表看起來很專業,包含組件框、關係箭頭和註釋,似乎表明繪製者對系統足夠了解。團隊以此為出發點,任何基於錯誤起點的分析都必然得出錯誤的結論。
Docuwriter 的審計架構明確指出:一次合格的文件審計「能將模糊的疑慮轉化為可檢驗的事實」。對於遺留系統,文件審計幾乎總是得出相同的結論:圖表要麼缺失,要麼年代久遠,所代表的系統早已不復存在。最終浮出水面的可檢驗事實,描述的是一個與任何人實際操作的系統都截然不同的系統。
具體故障模式:一個現代化團隊根據 1992 年的架構圖估算遷移範圍,圖中顯示有 180 個元件。但對實際程式碼庫的結構分析顯示,共有 340 個程序,其中 80 個是死代碼,另外 40 個是 1992 年之後添加的,從未繪製過架構圖。在第一行新程式碼編寫之前,範圍估算就已相差兩倍。
依陳舊程度劃分的圖表類別
並非所有圖表都會以相同的速度過時。過時的速度取決於圖表所描繪的內容、所描繪元素的變化頻率以及圖表對這些元素的表示精確程度。
| 圖表類型 | 哪些方面經常變化 | 陳舊率 | 緩解優先權 |
|---|---|---|---|
| 服務/組件清單 | 新增服務,停用原有服務 | 高 | 關鍵——最高變化頻率 |
| 依賴/整合圖 | 新增 API,更改集成,修改資料流 | 高 | 至關重要——每次部署都可能改變這一點。 |
| 資料模型/實體關係圖 | 架構變更、新增表、列修改 | 中等偏上 | 高-在積極開發過程中,架構變更頻繁。 |
| 序列圖 | 業務邏輯變更、API合約更新 | 媒材 | 高-任何工作流程的改變都會使這些失效。 |
| 基礎設施/部署 | 基礎設施即程式碼驅動頻繁變更 | 高 | Medium — IaC 工具可以自動產生這些 |
| 領域/有界上下文 | 組織和所有權變更 | 低中 | 低-域名邊界每季或更少變化 |
| 決策記錄(ADR) | 很少改變(決策具有歷史意義) | 非常低 | 低-一旦正確記錄,便保持準確。 |
| 程式呼叫圖(COBOL) | 每次程式碼更改都可能改變這一點。 | 很高 | 對傳承至關重要——變化悄無聲息。 |
| 副本/模式(COBOL) | 每次FD更改都會影響多個程序 | 高 | 對傳承至關重要——變革悄無聲息地層層推進 |
底部兩行是特定於舊系統的條目,沒有標準文件指南涵蓋。 COBOL 程式呼叫圖可能會因呼叫樹中任何程式的程式碼變更而失效。一個由 200 個程式共享的副本簿,一旦發生更改,所有程式都會因此失效。這些圖表在任何企業級系統中都具有最高的過時率,一旦過時,後果也最為嚴重,因為它們所描述的程式運行著最關鍵的業務流程。
溯源解決方案:追溯圖表來源
文件缺失的根本原因並非缺乏文件更新流程,而是缺乏溯源信息,即圖表元素與其所代表的程式碼工件之間的可追溯連結。沒有溯源訊息,就無法偵測文檔是否過時。有了溯源信息,過時檢測就能自動完成:如果程式碼工件自圖表生成以來發生了更改,則該圖表已過時。
文檔中的溯源資訊存在於兩個層面:
靜態溯源 靜態溯源是指在某個時間點從程式碼產生的文檔,它包含產生時間戳記以及對文檔所反映的程式碼狀態(提交雜湊值、版本、分析日期)的引用。靜態溯源並不能防止文件過時,但它可以使過時的情況變得可檢測:時間戳表明文檔是由某個提交產生的。 abc123 在特定日期,當前提交是 def456 稍後會進行。兩次提交之間的時間間隔就是文件和目前程式碼之間的時間間隔。
動態溯源是指根據程式碼持續產生的文檔,每次相關的程式碼變更都會重新產生文檔。由於文件始終基於當前的程式碼狀態,因此始終保持最新。這是一種動態文檔模型,它不是那種有人想起來才更新的圖表,而是每次程式碼更改時都會根據程式碼重新產生的圖表。
對於遺留的 COBOL 程式組合而言,實際差異在於:靜態溯源方法會根據目前的 COBOL 原始碼分析產生依賴關係圖並新增時間戳記。每周可以重新運行分析,並將新產生的依賴關係圖與先前的圖進行比較。變更會以連續兩次分析輸出之間的差異形式顯示出來。動態溯源方法則將分析整合到大型機變更管理流程中,並在程式升級到生產環境時產生更新後的依賴關係圖。
圖解即程式碼:哪些有效,哪些不足
現代應對靜態架構圖的方案是將架構圖視為程式碼,以文字格式表達架構文檔,這樣就可以進行版本控制、差異比較、程式碼審查,並且可以程式化產生。 Mermaid、PlantUML 和代碼形式的 C4 模型是主要的工具。
For modern cloud-native systems, diagrams-as-code solves several of the staleness mechanisms: #mermaid-rlk-r1 { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 16px; fill: rgb(25, 25, 25); } #mermaid-rlk-r1 .edge-animation-slow { stroke-dashoffset: 900; animation: 50s linear 0s infinite normal none running dash; stroke-linecap: round; stroke-dasharray: 9, 5 !important; } #mermaid-rlk-r1 .edge-animation-fast { stroke-dashoffset: 900; animation: 20s linear 0s infinite normal none running dash; stroke-linecap: round; stroke-dasharray: 9, 5 !important; } #mermaid-rlk-r1 .error-icon { fill: rgb(204, 120, 92); } #mermaid-rlk-r1 .error-text { fill: rgb(51, 135, 163); stroke: rgb(51, 135, 163); } #mermaid-rlk-r1 .edge-thickness-normal { stroke-width: 1px; } #mermaid-rlk-r1 .edge-thickness-thick { stroke-width: 3.5px; } #mermaid-rlk-r1 .edge-pattern-solid { stroke-dasharray: 0; } #mermaid-rlk-r1 .edge-thickness-invisible { stroke-width: 0; fill: none; } #mermaid-rlk-r1 .edge-pattern-dashed { stroke-dasharray: 3; } #mermaid-rlk-r1 .edge-pattern-dotted { stroke-dasharray: 2; } #mermaid-rlk-r1 .marker { fill: rgb(145, 145, 141); stroke: rgb(145, 145, 141); } #mermaid-rlk-r1 .marker.cross { stroke: rgb(145, 145, 141); } #mermaid-rlk-r1 svg { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 16px; } #mermaid-rlk-r1 p { margin: 0px; } #mermaid-rlk-r1 .label { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; color: rgb(25, 25, 25); } #mermaid-rlk-r1 .cluster-label text { fill: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster-label span { color: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster-label span p { background-color: transparent; } #mermaid-rlk-r1 .label text, #mermaid-rlk-r1 span { fill: rgb(25, 25, 25); color: rgb(25, 25, 25); } #mermaid-rlk-r1 .node rect, #mermaid-rlk-r1 .node circle, #mermaid-rlk-r1 .node ellipse, #mermaid-rlk-r1 .node polygon, #mermaid-rlk-r1 .node path { fill: rgb(240, 240, 235); stroke: rgb(217, 216, 213); stroke-width: 1px; } #mermaid-rlk-r1 .rough-node .label text, #mermaid-rlk-r1 .node .label text, #mermaid-rlk-r1 .image-shape .label, #mermaid-rlk-r1 .icon-shape .label { text-anchor: middle; } #mermaid-rlk-r1 .node .katex path { fill: rgb(0, 0, 0); stroke: rgb(0, 0, 0); stroke-width: 1px; } #mermaid-rlk-r1 .rough-node .label, #mermaid-rlk-r1 .node .label, #mermaid-rlk-r1 .image-shape .label, #mermaid-rlk-r1 .icon-shape .label { text-align: center; } #mermaid-rlk-r1 .node.clickable { cursor: pointer; } #mermaid-rlk-r1 .root .anchor path { stroke-width: 0; stroke: rgb(145, 145, 141); fill: rgb(145, 145, 141) !important; } #mermaid-rlk-r1 .arrowheadPath { fill: rgb(11, 11, 11); } #mermaid-rlk-r1 .edgePaths .path { stroke: rgb(145, 145, 141); stroke-width: 1px; } #mermaid-rlk-r1 .flowchart-link { stroke: rgb(145, 145, 141); fill: none; } #mermaid-rlk-r1 .edgeLabel { background-color: rgb(245, 230, 216); text-align: center; } #mermaid-rlk-r1 .edgeLabel p { background-color: rgb(245, 230, 216); } #mermaid-rlk-r1 .edgeLabel rect { opacity: 0.5; background-color: rgb(245, 230, 216); fill: rgb(245, 230, 216); } #mermaid-rlk-r1 .labelBkg { background-color: rgba(245, 230, 216, 0.5); } #mermaid-rlk-r1 .cluster rect { fill: rgb(204, 120, 92); stroke: rgb(138, 115, 107); stroke-width: 1px; } #mermaid-rlk-r1 .cluster text { fill: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster span { color: rgb(51, 135, 163); } #mermaid-rlk-r1 .node .collapsed-indicator { fill: rgb(138, 115, 107); stroke: none; opacity: 0.6; } #mermaid-rlk-r1 .node .collapsed-separator { stroke: rgb(138, 115, 107); stroke-width: 0.75px; } #mermaid-rlk-r1 div.mermaidTooltip { position: absolute; text-align: center; max-width: 200px; padding: 2px; font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 12px; background: rgb(204, 120, 92); border: 1px solid rgb(138, 115, 107); border-radius: 2px; pointer-events: none; z-index: 100; } #mermaid-rlk-r1 .flowchartTitleText { text-anchor: middle; font-size: 18px; fill: rgb(25, 25, 25); } #mermaid-rlk-r1 rect.text { fill: none; stroke-width: 0; } #mermaid-rlk-r1 .icon-shape, #mermaid-rlk-r1 .image-shape { background-color: rgb(245, 230, 216); text-align: center; } #mermaid-rlk-r1 .icon-shape p, #mermaid-rlk-r1 .image-shape p { background-color: rgb(245, 230, 216); padding: 2px; } #mermaid-rlk-r1 .icon-shape .label rect, #mermaid-rlk-r1 .image-shape .label rect { opacity: 0.5; background-color: rgb(245, 230, 216); fill: rgb(245, 230, 216); } #mermaid-rlk-r1 .label-icon { display: inline-block; height: 1em; overflow: visible; vertical-align: -0.125em; } #mermaid-rlk-r1 .node .label-icon path { fill: currentcolor; stroke: revert; stroke-width: revert; } #mermaid-rlk-r1 .node .neo-node { stroke: rgb(217, 216, 213); } #mermaid-rlk-r1 [data-look=”neo”].node rect, #mermaid-rlk-r1 [data-look=”neo”].cluster rect, #mermaid-rlk-r1 [data-look=”neo”].node polygon { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].swimlane.cluster rect { filter: none; } #mermaid-rlk-r1 [data-look=”neo”].node path { stroke: url(“#mermaid-rlk-r1-gradient”); stroke-width: 1px; } #mermaid-rlk-r1 [data-look=”neo”].node .outer-path { filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].node .neo-line path { stroke: rgb(217, 216, 213); filter: none; } #mermaid-rlk-r1 [data-look=”neo”].node circle { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].node circle .state-start { fill: rgb(0, 0, 0); } #mermaid-rlk-r1 [data-look=”neo”].icon-shape .icon { fill: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].icon-shape .icon-neo path { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 :root { –mermaid-font-family: system-ui,”Segoe UI”,Roboto,Helvetica,Arial,”PingFang SC”,”PingFang TC”,”Hiragino Sans”,”Apple SD Gothic Neo”,”Kohinoor Devanagari”,”Kohinoor Bangla”,”Kohinoor Telugu”,”Tamil Sangam MN”,”Kohinoor Gujarati”,”Malayalam Sangam MN”,”Nirmala UI”,”Noto Sans Devanagari UI”,”Noto Sans Devanagari”,”Noto Sans Bengali UI”,”Noto Sans Bengali”,”Noto Sans Telugu UI”,”Noto Sans Telugu”,”Noto Sans Tamil UI”,”Noto Sans Tamil”,”Noto Sans Gujarati UI”,”Noto Sans Gujarati”,”Noto Sans Kannada UI”,”Noto Sans Kannada”,”Noto Sans Malayalam UI”,”Noto Sans Malayalam”,Thonburi,”Leelawadee UI”,”Noto Sans Thai UI”,”Noto Sans Thai”,Kefa,Ebrima,”Noto Sans Ethiopic”,”Abyssinica SIL”,sans-serif,ui-sans-serif,system-ui,-apple-system,”Segoe UI”,Roboto,”PingFang SC”,”PingFang TC”,”Hiragino Sans”,”Apple SD Gothic Neo”,sans-serif; }API GatewayAuth ServiceOrder ServiceOrder DBNotification ServiceUser DB
這張美人魚圖與它所描繪的代碼一起存放在代碼倉庫中。當開發人員新增服務時,他們會在同一個拉取請求中更新此文件。程式碼審查會包含圖表的變更。文檔和程式碼會同步更新。
圖解即程式碼無法解決的問題:
它並不能解決遺留系統文件的問題。例如,開發人員向大型主機庫新增 COBOL 程式時,如果提交的是編譯後的 JCL 而不是 Git 拉取請求,則不會觸發 Mermaid 檔案更新。大型主機變更管理流程和基於 Git 的文件流程是兩個獨立的系統,彼此之間沒有自動同步機制。
它並不能解決過度精確的問題。 Mermaid流程圖需要手動更新才能支援每項新服務,這仍然需要該流程原本想要取代的人工操作。如果更新流程圖需要手動操作,那麼這一步驟就會被省略。
它不會追溯性地修復舊有的圖表。對於沒有現有機器可讀文件的 COBOL 程式碼庫,圖表即程式碼 (diagrams-as-code) 為未來的文件編寫提供了一個框架,但不會產生目前的文件。
遺留系統的結構分析方法
對於舊系統而言,由於開發工作流程不經過 Git,或者現有文件過於過時,無法作為基於文字的方法的起點,或者程式碼庫從未正式記錄過,因此,以程式碼形式繪製圖表是不切實際的,結構化程式碼分析是唯一能夠從頭開始產生最新、準確文件的機制。
結構分析解析實際程式碼,包括 COBOL 程式、JCL 作業流程、副本、嵌入式 SQL 等,並直接從程式碼內容推導出依賴關係、程式清單和資料結構。其輸出並非由理解程式碼的人員繪製的圖表,而是透過演算法從程式碼本身推導出的圖表。其準確性取決於分析的準確性,而非繪製圖表的開發人員的記憶。
工作流程:
打壞
# Structural analysis pipeline for COBOL documentation
# Step 1: Parse all COBOL source in the portfolio
smart-ts-xl analyze --source /cobol/src --output /docs/analysis/
# Step 2: Generate dependency graph (always current)
smart-ts-xl diagram --type dependency-graph \
--format mermaid \
--output /docs/dependency-graph.md
# Step 3: Generate program inventory (always current)
smart-ts-xl report --type program-inventory \
--format markdown \
--output /docs/program-inventory.md
# Step 4: Diff against previous analysis (detect what changed)
smart-ts-xl diff \
--baseline /docs/analysis/2026-09-01/ \
--current /docs/analysis/2026-10-01/ \
--output /docs/changes/delta-report.md
增量報告(即兩次連續分析之間的差異)是圖表靜態溯源功能自動產生的變更日誌。新增程式、刪除程式、依賴項變更、副本修改:所有這些都會顯示在增量報告中,無需任何手動記錄。
上次分析產生的圖表是截至分析日期的最新文件。按計劃(每週一次或每次產品推廣觸發一次)運行分析,即可按既定節奏生成最新文檔,無需任何持續的人工文檔工作。
文件預防框架
防止文件延遲需要透過具體、可實施的做法來解決五種文件過期機制:
針對累積增量問題:
- 建立分析頻率:高速系統每週一次,穩定係統每月一次。
- 每次分析運行都會從程式碼產生文檔,而不是手動產生。
- 針對每次運行產生一份增量報告,顯示自上次分析以來發生的變化。
針對缺失溯源資訊的問題:
- 每個圖表都包含其生成來源(程式碼分析日期和版本)。
- 切勿在未記錄圖表製作方法和時間的情況下發布圖表。
- 將產生的圖表與產生它們的分析輸出一起儲存。
針對所有權轉移問題:
- 文件產生是流程中的一個環節,而非個人責任。
- 所有文件都歸管道公司所有;任何個人的離職都不會破壞它。
- 產生的文件沒有所有者,因此不會出現所有權轉移的情況。
針對過度精確問題:
- 在建立圖表之前,請為每種圖表類型定義合適的抽象層級。
- 服務/程式層級的元件清單圖,而非功能層級的元件清單圖。
- 域邊界層級的關係圖,而不是單一呼叫層級的關係圖。
- 系統會自動產生詳細的圖表(呼叫圖、資料模式),而不是手繪的。
針對格式鎖定問題:
- 以文字格式(Mermaid、GraphViz DOT、SVG)產生的圖表
- 沒有僅以 Visio、PowerPoint 或 PDF 格式提供的架構文件。
- 圖表原始碼與其所記錄的程式碼一起儲存在版本控制系統中。
SMART TS XL 解決遺留文件債務
對於傳統的 COBOL 和大型主機產品組合, SMART TS XL 是結構分析引擎,它使得基於證據的文檔編製成為可能,並且使得「從程式碼重新生成」成為「更新 2009 SharePoint 圖表」的實用替代方案。
靜態程式碼分析功能會解析每個 COBOL 程式、副本、JCL 作業流程和嵌入式 SQL 語句,從而產生程式清單、複雜度指標和死程式碼識別訊息,這些資訊構成了任何準確的遺留系統文件的基礎層。這份清單以證據為基礎,取代了手動維護的程式清單——後者總是不完整、總是過時,而且總是存在一些無人知曉的錯誤。
應用程式依賴關係映射會產生依賴關係圖,其中包含每個 CALL 關係、每個 COPY 關係以及程式之間的所有資料流,這是架構文件的核心組成部分。每次分析運行時,該圖都會根據程式碼重新生成,從而產生與上次分析結果一致的依賴關係圖,無需在兩次運行之間進行任何人工文檔編寫工作。
影響分析功能會產生增量文件:當程式碼庫變更時,影響分析會識別出相對於先前狀態的所有變化。這份自動化增量報告解決了增量累積的問題,它會自動捕獲並記錄所有可能擴大圖表與實際情況差距的變更。
企業級搜尋功能使文件可查詢:尋找呼叫特定子程序的每個程序(組件的呼叫圖片段)、包含特定副本的每個程序(共享組件的依賴關係範圍)、以及在特定日期之後修改的每個程序(特定時間段的變更日誌)。此搜尋功能即文件介面,它能夠根據當前的分析結果(而非可能已過時多年的靜態圖表)回答有關當前系統狀態的問題。
對於進行以下活動的組織 遺產現代化 程式, SMART TS XL文件產生是前提步驟:現代化專案需要依賴關係圖、程式清單和資料架構文件來定義範圍、安排遷移階段順序並驗證結果。這些文件不能來自 SharePoint 存檔,必須來自程式碼。
唯一準確的圖表是由程式碼推導出的圖表。
SharePoint 頁面上的 2009 年架構圖將持續存在,直到有人明確刪除它。當新開發人員詢問系統運作時,它仍會被發送給他們。它仍將繼續為一些決策提供依據,而它對系統的描述已不再準確。隨著每一次程式碼提交、每一次部署、每一次程式的新增和停用,架構圖與實際系統之間的差距將持續擴大。
另一種選擇並非「更頻繁地更新圖表」。需要人工監督來維護不斷變化程式碼的流程存在一個已知的失效模式:監督機制失效。另一個選擇是基於程式碼產生文檔,以程式碼為真,在程式碼變更時自動更新,並帶有分析時間戳,讓每位讀者都能準確了解文檔的更新程度。
對於現代雲端系統,程式碼即圖表和動態文件工具可以實現這一點。對於傳統的 COBOL 系統,結構化程式碼分析可以實現這一點。機制有所不同,但原理相同:圖表從程式碼中導出時是準確的,一旦與產生它的程式碼分離,就會開始累積錯誤。
唯一保持最新的圖表是由程式碼繪製的圖表。


