前言

大家好，我是飄渺。

今天我們來了解一些關于軟件設計文檔的基礎知識，這樣你在學習后面的具體案例時，就能更加清楚地理解文檔是基于什么方式來組織的了。

首先，請你設想這樣一個場景：如果公司安排你做架構師，要你在項目開發前期進行軟件架構設計，你該如何開展你的工作？如何輸出你的工作成果？如何確定你的設計是否滿足用戶需求？你是否有把握最后交付的軟件是滿足要求的？是否有把握讓團隊每個工程師清楚自己的職責范圍并有效地完成開發工作……

這些問題其實都是軟件開發管理與技術架構的核心訴求，而架構師的核心工作就是做好軟件設計，解決這些訴求。這些問題搞定了，軟件的開發過程和結果也就都得到了保證。那怎么實現這些訴求呢？我們主要的手段就是軟件建模，以及將這些軟件模型組織成一篇有價值的軟件設計文檔。

軟件建模

所謂軟件建模，就是為要開發的軟件建造模型。

模型是對客觀存在的抽象，例如著名的物理學公式 E=mc2，就是質量能量轉換的物理規律的數學模型。除了物理學公式以外，還有一些東西也是模型，比如地圖是對地理空間的建模；機械裝置、電子電路、建筑設計的各種圖紙是對物理實體的建模。而軟件，也可以通過各種圖進行建模。

軟件系統龐大復雜，通過軟件建模，我們可以抽象軟件系統的主要特征和組成部分，梳理這些關鍵組成部分的關系。在軟件開發過程中依照模型的約束開發，系統整體的格局和關系就會可控。相關人員從始至終都能清晰了解軟件的藍圖和當前的進展，不同的開發工程師會清晰自己開發的模塊和其他同事工作內容的關系與依賴，并按照這些模型開發代碼。

那么我們是根據什么進行軟件建模的呢？要解答這個疑問，你需要先知道，在軟件開發中，有兩個客觀存在。

一個是我們要解決的領域問題。比如我們要開發一個電子商務網站，那么客觀的領域問題就是如何做生意，賣家如何管理商品、管理訂單、服務用戶，買家如何挑選商品，如何下訂單，如何支付等等。對這些客觀領域問題的抽象就是各種功能及其關系、各種模型對象及其關系、各種業務處理流程。

另一個客觀存在就是最終開發出來的軟件系統。軟件系統要解決的問題包括軟件由哪些主要類組成，這些類如何組織構成一個個的組件，這些類和組件之間的依賴關系如何，運行期如何調用，需要部署多少臺服務器，服務器之間如何通信等。

而對這兩個客觀存在進行抽象化處理的手段，就是我們的軟件模型。

圖片

一方面我們要對領域問題和要設計的軟件系統進行分析、設計、抽象，另一方面，我們根據抽象出來的模型進行開發，最終實現出一個軟件系統，這就是軟件開發的主要過程。而對領域問題和軟件系統進行分析、設計和抽象的這個過程，就是軟件建模設計。

軟件設計方法

因此，軟件設計其實就是軟件建模的過程。我們通過軟件建模工具，將軟件模型畫出來，實現軟件設計。

在實踐中，通常用來進行軟件建模畫圖的工具是 UML，統一建模語言。UML 包含的軟件模型有 10 種，其中常用的有 7 種：類圖、序列圖、組件圖、部署圖、用例圖、狀態圖和活動圖。

下面我們簡單了解下這 7 種常用 UML 圖的使用場景和基本樣例。在專欄后面的設計文檔中，你會多次見到它們，看多了，你就懂了，也就自然會畫了。當然，如果你想更詳細地學習 UML 知識，我也非常鼓勵，并且推薦你閱讀馬丁富勒的《UML 精粹》一書。

類圖

類圖是最常見的 UML 圖形，用來描述類的特性和類之間的靜態關系。

一個類包含三個部分：類的名字、類的屬性列表和類的方法列表。類之間有 6 種靜態關系：關聯、依賴、組合、聚合、繼承、泛化。把相關的一組類及其關系用一張圖畫出來，就是類圖。

比如你在后面的課程中會遇到下面這幅圖，它就是類圖。你可以把我上面說的類圖包含元素和圖片一一對照，感受類圖的用法。

圖片

時序圖

類圖之外，另一種常用的圖是時序圖，類圖描述類之間的靜態關系，時序圖則用來描述參與者之間的動態調用關系。

圖片

組件圖

組件是比類粒度更大的設計元素，一個組件中通常包含很多個類。組件圖有的時候和包圖的用途比較接近，組件圖通常用來描述物理上的組件，比如一個 JAR、一個 DLL 等等。在實踐中，我們進行模塊設計的時候，用得更多的就是組件圖。

圖片

組件圖描述組件之間的靜態關系，主要是依賴關系，如果你想要描述組件之間的動態調用關系，可以使用組件時序圖，以組件作為參與者，描述組件之間的消息調用關系。

部署圖

部署圖描述軟件系統的最終部署情況，比如需要部署多少服務器，關鍵組件都部署在哪些服務器上。

圖片

部署圖是軟件系統最終物理呈現的藍圖，根據部署圖，所有相關者，諸如客戶、老板、工程師都能清晰地了解到最終運行的系統在物理上是什么樣子，和現有的系統服務器的關系，和第三方服務器的關系。根據部署圖，還可以估算服務器和第三方軟件的采購成本。

因此部署圖是整個軟件設計模型中，比較宏觀的一種圖，是在設計早期就需要畫的一種模型圖。根據部署圖，各方可以討論對這個方案是否認可。只有對部署圖達成共識，才能繼續后面的細節設計。

用例圖

用例圖通過反映用戶和軟件系統的交互，描述系統的功能需求。

圖片

圖中小人形象的元素，被稱為角色，角色可以是人，也可以是其他的系統。系統的功能可能會很復雜，所以一張用例圖可能只包含其中一小部分功能，這些功能被一個矩形框框起來，這個矩形框被稱為用例的邊界。框里的橢圓表示一個一個的功能，功能之間可以調用依賴，也可以進行功能擴展。

狀態圖

狀態圖用來展示單個對象生命周期的狀態變遷。

業務系統中，很多重要的領域對象都有比較復雜的狀態變遷，比如賬號，有創建狀態、激活狀態、凍結狀態、欠費狀態等等各種狀態。此外，用戶、訂單、商品、紅包這些常見的領域模型都有多種狀態。

這些狀態的變遷描述可以在用例圖中用文字描述，隨著角色的各種操作而改變，但是用這種方式描述，狀態散亂在各處，不要說開發的時候容易搞錯，就是產品經理自己在設計的時候，也容易搞錯對象的狀態變遷。

UML 的狀態圖可以很好地解決這一問題，一張狀態圖描述一個對象生命周期的各種狀態，及其變遷的關系。如圖所示，門的狀態有開 Opened、關 Closed 和鎖 Locked 三種，狀態與變遷關系用一張狀態圖就可以搞定。

圖片

活動圖

活動圖主要用來描述過程邏輯和業務流程。UML 中沒有流程圖，很多時候，人們用活動圖代替流程圖。

圖片

活動圖和早期流程圖的圖形元素也很接近，實心圓代表流程開始，空心圓代表流程結束，圓角矩形表示活動，菱形表示分支判斷。

此外，活動圖引入了一個重要的概念——泳道。活動圖可以根據活動的范圍，將活動根據領域、系統和角色等劃分到不同的泳道中，使流程邊界更加清晰。

我們上面介紹了 UML 建模常用的 7 種模型，那么這 7 種模型分別應用在軟件設計的什么階段？用來表達什么樣的設計意圖呢？

軟件文檔設計

軟件設計文檔就是架構師的主要工作成果，它需要闡釋本文開頭提到的各種訴求，描繪軟件的完整藍圖，而軟件設計文檔的主要組成部分就是軟件模型。

軟件設計過程可以拆分成需求分析、概要設計和詳細設計三個階段。

在需求分析階段，主要是通過用例圖來描述系統的功能與使用場景；對于關鍵的業務流程，可以通過活動圖描述；如果在需求階段就提出要和現有的某些子系統整合，那么可以通過時序圖描述新系統和原來的子系統的調用關系；可以通過簡化的類圖進行領域模型抽象，并描述核心領域對象之間的關系；如果某些對象內部會有復雜的狀態變化，比如用戶、訂單這些，可以用狀態圖進行描述。

在概要設計階段，通過部署圖描述系統最終的物理藍圖；通過組件圖以及組件時序圖設計軟件主要模塊及其關系；還可以通過組件活動圖描述組件間的流程邏輯。

在詳細設計階段，主要輸出的就是類圖和類的時序圖，指導最終的代碼開發，如果某個類方法內部有比較復雜的邏輯，那么可以將這個方法的邏輯用活動圖進行描述。

我們在每個設計階段使用幾種 UML 模型對領域或者系統進行建模，然后將這些模型配上必要的文字說明寫入到文檔中，就可以構成一篇軟件設計文檔了。

我們專欄中的十幾講軟件設計案例，都是按照這樣的方式組織的，你可以在學習的過程中，一方面了解各種系統軟件是如何設計的，一方面也可以借鑒設計文檔是如何寫作的。

同時也要說明一下，設計文檔的寫法并沒有一定之規，最重要的是這個文檔能否向閱讀者傳遞出架構師完整的設計意圖。而不同的閱讀者關注點是不同的，老板、客戶、運維、測試、開發這些角色都是設計文檔的閱讀者，他們想要看到的東西顯然是不一樣的。

客戶和測試人員可能更關注功能性需求和實現邏輯，老板和運維人員可能更關注非功能需求和整體架構，而開發人員可能更關注整體架構與關鍵技術細節。

我們專欄的案例基本上是以開發人員作為閱讀視角進行編寫的，你在閱讀這些案例時，會明顯感覺到我的表達方式和其他專欄文章不太一樣，措辭會更“堅硬”一點，文字和讀者的距離也有點“疏離”，而這正是設計文檔自身的特質。

架構、系統，文檔、相關人員之間的關系可以參考下面這張圖。

圖片

每個軟件系統都需要有一個架構，每個架構都包含若干架構元素。架構元素就是前面提到的服務器、組件、類、消息、用例、狀態等等。這些元素之間的關系是什么？如何把它們組織在一起？我們可以用部署圖、組件圖、時序圖等各種模型圖來描述。

架構最終需要一個文檔來承載，把這些模型圖放進這個文檔，再配以適當的文字說明，就是一篇架構設計文檔。而設計文檔是給人閱讀的，這些人就是系統的相關方。不同的相關方關注點不同，也需要由不同的模型圖來進行表達，所以架構師應該針對不同的相關方，使用不同的模型圖輸出不同的架構文檔。

小結

軟件設計就是在軟件開發之前，對要解決的業務問題和對要實現的軟件系統進行思考，并將這個思考的結果通過軟件模型表達出來的過程。

人類作為萬物之靈，最大的特點就是，在行動之前就已經在頭腦中將行動的過程和行動的結果構建成了一個藍圖，然后將這個藍圖付諸實踐。我們的祖先將第一塊石頭打磨成石器的時候，就已經擁有了這種能力。軟件系統的開發是一個復雜的智力活動，參與其中的我們更需要擁有構建藍圖并付諸實踐的能力。

目前有個很火的詞叫“元宇宙”，“元”通俗地講，就是一切開始的地方，是關于如何用自己描述自己，是抽象之上的抽象。這種“元”能力對架構師而言，非常重要。架構師只有掌握各種技術背后的技術，了解各種問題背后的問題，才能超越當下的種種羈絆，設計出面向未來的架構。