關鍵要點
-
通過創建和維護架構圖來提供準確且有價值的內容並非易事。大多數情況下，我們要麼創建了太多的文檔，要麼太少，或者不相關，因爲我們沒能準確地定位文檔的受益人及其實際的需求。
-
我們常犯的最大的一個錯誤是爲系統中具有高波動性的部分創建詳細的架構圖。除非是自動生成的，否則手動維護它們對我們來說就是一種負擔。
-
在實踐中，大多數利益相關者對詳細架構圖不感興趣，但會對一兩個反映系統模塊和邊界的高級架構圖感興趣。除此之外，要深入理解系統，代碼纔是事實的來源，但在大多數情況下，只有開發人員會對代碼感興趣。
-
爲了創建具備一定質量的架構圖，可以進行頭腦風暴，並與團隊就什麼對他們來說纔是真正有用的東西上達成一致。不要嘗試爲源代碼中不言自明的東西或爲了迎合架構方法而創建架構圖。
-
架構圖的主要目的應該是促進協作、增強溝通、提供願景和指導。
-
在牆上繪製一兩個高級架構圖並在會議（站會等）期間使用它們。作爲一名架構師，你應該讓它們可見，變得有價值，並作爲項目文化的一部分。不要將它們隱藏起來或放在利益相關者不易接觸到的地方。
我們嘗試通過創建架構圖（作爲技術文檔的一部分）來反映應用程序的內部狀態，但大多數時候我們都沒能做對。由此產生的架構圖可能非常全面，也可能非常模糊。有時，架構圖根本就是不相關的。我之前寫過一些關於如何創建有用架構圖的技巧。
即使創建了相關的架構圖，我們也很少更新它們，作爲持續開發過程的一部分。實際上，我們只是時不時地更新文檔，可能是在某些sprint期間（當有時間更新文檔時）或在發佈特定版本之前。另一方面，大多數開發人員（參加我的軟件架構課程的同事或學生）不贊成創建和維護技術文檔，他們認爲這些任務乏味、耗時，而且價值不如其他任務，他們甚至認爲如果源代碼寫得足夠好，文檔不是必需的。雖然總會有例外，但我很確定，在架構圖方面，對於大多數項目來說幾乎都是一樣的。
我們做錯了什麼以及如何改進
首先，最重要的是要了解誰是架構圖和技術文檔的真正受益者。文檔的數量和質量應該反映出利益相關者的需求，因爲只有這樣，我們才能創建準確且恰到好處的文檔。
主要受益者應該是直接參與項目的團隊（開發人員、測試工程師、業務分析師、DevOps工程師，等等）。根據我的經驗，在團隊之外，很少有利益相關者真正關心文檔。在最好的情況下，他們可能對一兩個高級架構圖（例如上下文圖、應用程序或軟件組件圖）感興趣，這些圖粗略地描述了系統的結構並提供了高層次的系統視圖。
但是，在大多數情況下，我們並沒有確定真正的受益者及其真正的需求，直接就創建了過多的文檔。這些文檔很快就會成爲維護負擔，並且很快就會過時。而在其他一些情況下，我們直接省略了架構圖，因爲沒有時間，或者沒有興趣，或者沒有人願意接受這個任務。除此之外，敏捷宣言宣稱，團隊應該更加重視軟件本身而不是文檔，也就是不鼓勵繁瑣的文檔處理過程。
爲了找到恰當的文檔級別平衡點，可以嘗試在團隊中這麼做：
詢問每個同事，他們需要文檔爲他們提供怎樣的內容，以及應該包含哪些類型的架構圖。收集他們的意見，然後進行集體討論，並就團隊真正需要哪些的東西達成一致。團隊之外可能會有一兩個有影響力的利益相關者，他們會提出額外的需求，架構師也有責任將這些人的需求考慮在內。在這個基礎上，創建適當數量和質量的技術文檔，以滿足利益相關者的需求。如果開發人員能夠了解文檔的真正價值，並對其剩餘的價值感興趣，可以讓他們參與更新和維護文檔。最後，每個人都會變得很愉快。但是，如果他們不瞭解文檔的必要性或者他們根本不在乎，你幾乎可以忽略它，因爲很難由一個人（架構師）來維護文檔，這應該是團隊成員的共同責任。
過去，在瀑布式項目中，因爲採用了綜合性的企業架構方法（我故意不說出是哪些方法），或者是一些象牙塔架構師提出的要求，我們創建了太多的文檔。當軟件項目開始大規模擁抱敏捷方法時，一個常見的誤解是人們認爲他們不需要文檔，因爲軟件比文檔更重要。當然，這是兩個極端的情況。並不存在什麼精確的方法或科學的過程來明確地指定項目需要多少文檔纔是恰當的。所有當前的軟件架構方法都是純建議或指南。過去遵循的那些綜合性的架構過程在現今的項目中被大大簡化，甚至已經不存在了。這並不意味着我們應該創建更少的文檔，或者根本不創建文檔，而是應該專注於創建具備真正價值的文檔，同時不妨礙團隊的進展。除此之外，並不是所有的文檔都會提供價值。但這並不等同於“所有的文檔都沒有價值”。此外，因爲不同的環境（如經濟、政治等）、業務目標和利益相關者等因素，對一個項目有意義的文檔對於另一個項目來說可能並沒有那麼有用。
在這些情況下，很難得出這個問題的正確答案：多少文檔（即架構圖）纔算是適當的？最後，它關係到每個項目和架構師的經驗，可以說是“視情況而定”。適當的能夠提供價值的文檔數量取決於團隊需要什麼。我的建議是與團隊一起決定需要創建多少技術文檔，無論這對團隊來說意味着什麼。如果文檔對你的項目來說毫無意義（爲什麼會這樣？），這也是可以接受的。將團隊做出的決定記錄下來，讓所有利益相關者都知曉。如果有兩三個架構圖是有用的，那麼請確保隨時更新它們，保持它們的一致性，並且總是能反映系統的狀態。不要專注於任何不會帶來價值的事情。
那麼，我們用架構圖來做什麼？
一般而言，架構圖和文檔應該主要用於團隊內部和團隊之間的協作、溝通、願景和指導。它們還應該包含項目的重要設計決策（在某個特定時刻採取）。
架構圖應該幫助每個人看到大局，瞭解周圍的環境。在我看來，這應該是創建和維護架構圖背後的根本原因。
例如，上下文架構圖完全滿足了這種需求，並提供了關於系統邊界的大量細節，從而可以看到全局。它有助於團隊在不同的利益相關者之間達成共識，並簡化溝通。我參加了很多會議，當大屏幕上出現這樣的上下文架構圖時，省去了很多問題，並消除了關於高級系統架構的不確定性。
不過，我們經常會嘗試創建綜合性的文檔來反映系統的內部狀態，它們可以是狀態圖、活動圖、類圖、實體圖、併發圖等形式。但這些很快就會過時，除非它們是基於源代碼通過一些“神奇”的工具自動生成的。
如果人們不需要它們，那麼創建這些詳細的架構圖有什麼意義呢？業務利益相關者的抽象圖綽綽有餘了。在大多數情況下，對於開發人員來說，源代碼（即單一事實來源）纔是他們真正需要的。因此，請停止爲代碼中自解釋的內容創建詳細的架構圖，或者當沒有真正受衆時。
因此，創建有意義的小型架構圖，並將它們加到技術文檔中。對於大多數應用程序，可能需要兩三種架構圖。最常見的是上下文圖、組件圖、系統圖或部署圖。
我的真實項目示例
在我的項目中，我主要使用兩種類型的架構圖：
請將這些圖視爲簡單的示例，主要作爲每種圖應該提供哪些合理信息的指導。圖中的信息應該與相應的抽象級別相關，還必須滿足利益相關者的需求。
在實踐中，你可能傾向於向圖中添加越來越多的細節，但是如果它們對利益相關者沒有真正的用處，就會導致額外的噪音，增加維護成本，而且容易過時。這些圖中的一些細節，例如協議和數據格式，可能對技術利益相關者來說比較方便，因爲它們是必要的實現細節。然而，正如之前所述，並不存在精確的方法來確定圖中包含多少數量的細節纔算是恰當的，這完全取決於不同的項目。不過，架構師需要知道對利益相關者來說真正有用的是什麼，並創建和維護架構圖來正確地反映這一點。
除了這些架構圖之外的任何額外細節，我可以在源代碼中找到，或者通過某些工具自動生成（例如運行時視圖、開發視圖、系統或基礎設施視圖等）。
我還在會議室中繪製軟件架構圖（包括所有應用程序組件）。在我們的站會和其他會議期間，人們邊指着牆上的這些架構圖邊談論他們的任務、狀態和遇到的問題。這樣，每個團隊成員，從產品所有者到開發人員，都能理解系統的全局，並預見到整體障礙和其他集成挑戰。除此之外，在Sprint期間，它還爲整個團隊提供了更準確的進度狀態，尤其是在分佈式架構中，且人與人之間存在依賴關係時。
我建議你也在團隊中這麼做。通過使用足夠的架構圖繼續加強協作、溝通、願景和指導，否則就不要創建它們，特別是如果團隊不使用它們的話。在大多數情況下，手動創建和維護架構圖，以此來反映代碼行爲純粹是在浪費時間。如果你這樣做了，隨着源代碼的演變，你可能會想要添加越來越多這樣的架構圖，這是一個危險的陷阱。與其創建大量令人精疲力盡的架構圖，不如堅持使用兩到三個從不同抽象層次描述系統的架構圖，這對於團隊來說是非常必要的。經常性地更新它們，如果這個任務不包含太多的細節，並且是團隊文化的一部分，那麼它將變得更容易。
另外，請記住，團隊應該是架構圖的主要受益者。如果它們沒有表現出任何興趣，那麼你應該停止創建它們，因爲這可能是在浪費時間。我們不應該只是“爲了擁有它們”，或者爲了遵循綜合性的架構方法，或者純粹爲了證明我們作爲架構師的角色而去創建架構圖。
關於作者
Ionut Balosin是Luxoft的軟件架構師，在各種商業應用程序方面擁有超過10年的經驗，熱衷於性能和調優以及軟件架構。他經常在各種技術大會上發表演講，是一個技術培訓師。
查看英文原文：