1 前言

今天我們來(lái)了解一些關(guān)于軟件設(shè)計(jì)文檔的基礎(chǔ)知識(shí)，這樣你在學(xué)習(xí)后面的具體案例時(shí)，就能更加清楚地理解文檔是基于什么方式來(lái)組織的了。

首先，請(qǐng)你設(shè)想這樣一個(gè)場(chǎng)景：如果公司安排你做架構(gòu)師，要你在項(xiàng)目開(kāi)發(fā)前期進(jìn)行軟件架構(gòu)設(shè)計(jì)，你該如何開(kāi)展你的工作？如何輸出你的工作成果？如何確定你的設(shè)計(jì)是否滿足用戶需求？你是否有把握最后交付的軟件是滿足要求的？是否有把握讓團(tuán)隊(duì)每個(gè)工程師清楚自己的職責(zé)范圍并有效地完成開(kāi)發(fā)工作……

這些問(wèn)題其實(shí)都是軟件開(kāi)發(fā)管理與技術(shù)架構(gòu)的核心訴求，而架構(gòu)師的核心工作就是做好軟件設(shè)計(jì)，解決這些訴求。這些問(wèn)題搞定了，軟件的開(kāi)發(fā)過(guò)程和結(jié)果也就都得到了保證。那怎么實(shí)現(xiàn)這些訴求呢？我們主要的手段就是軟件建模，以及將這些軟件模型組織成一篇有價(jià)值的軟件設(shè)計(jì)文檔。

基于 Spring Boot + MyBatis Plus + Vue & Element 實(shí)現(xiàn)的后臺(tái)管理系統(tǒng) + 用戶小程序，支持 RBAC 動(dòng)態(tài)權(quán)限、多租戶、數(shù)據(jù)權(quán)限、工作流、三方登錄、支付、短信、商城等功能

項(xiàng)目地址：https://github.com/YunaiV/ruoyi-vue-pro

視頻教程：https://doc.iocoder.cn/video/

2 軟件建模

所謂軟件建模，就是為要開(kāi)發(fā)的軟件建造模型。

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

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

那么我們是根據(jù)什么進(jìn)行軟件建模的呢？要解答這個(gè)疑問(wèn)，你需要先知道，在軟件開(kāi)發(fā)中，有兩個(gè)客觀存在。

一個(gè)是我們要解決的領(lǐng)域問(wèn)題。比如我們要開(kāi)發(fā)一個(gè)電子商務(wù)網(wǎng)站，那么客觀的領(lǐng)域問(wèn)題就是如何做生意，賣(mài)家如何管理商品、管理訂單、服務(wù)用戶，買(mǎi)家如何挑選商品，如何下訂單，如何支付等等。對(duì)這些客觀領(lǐng)域問(wèn)題的抽象就是各種功能及其關(guān)系、各種模型對(duì)象及其關(guān)系、各種業(yè)務(wù)處理流程。

另一個(gè)客觀存在就是最終開(kāi)發(fā)出來(lái)的軟件系統(tǒng)。軟件系統(tǒng)要解決的問(wèn)題包括軟件由哪些主要類(lèi)組成，這些類(lèi)如何組織構(gòu)成一個(gè)個(gè)的組件，這些類(lèi)和組件之間的依賴關(guān)系如何，運(yùn)行期如何調(diào)用，需要部署多少臺(tái)服務(wù)器，服務(wù)器之間如何通信等。

而對(duì)這兩個(gè)客觀存在進(jìn)行抽象化處理的手段，就是我們的軟件模型。

一方面我們要對(duì)領(lǐng)域問(wèn)題和要設(shè)計(jì)的軟件系統(tǒng)進(jìn)行分析、設(shè)計(jì)、抽象，另一方面，我們根據(jù)抽象出來(lái)的模型進(jìn)行開(kāi)發(fā)，最終實(shí)現(xiàn)出一個(gè)軟件系統(tǒng)，這就是軟件開(kāi)發(fā)的主要過(guò)程。而對(duì)領(lǐng)域問(wèn)題和軟件系統(tǒng)進(jìn)行分析、設(shè)計(jì)和抽象的這個(gè)過(guò)程，就是軟件建模設(shè)計(jì)。

基于 Spring Cloud Alibaba + Gateway + Nacos + RocketMQ + Vue & Element 實(shí)現(xiàn)的后臺(tái)管理系統(tǒng) + 用戶小程序，支持 RBAC 動(dòng)態(tài)權(quán)限、多租戶、數(shù)據(jù)權(quán)限、工作流、三方登錄、支付、短信、商城等功能

項(xiàng)目地址：https://github.com/YunaiV/yudao-cloud

視頻教程：https://doc.iocoder.cn/video/

3 軟件設(shè)計(jì)方法

因此，軟件設(shè)計(jì)其實(shí)就是軟件建模的過(guò)程。我們通過(guò)軟件建模工具，將軟件模型畫(huà)出來(lái)，實(shí)現(xiàn)軟件設(shè)計(jì)。

在實(shí)踐中，通常用來(lái)進(jìn)行軟件建模畫(huà)圖的工具是 UML，統(tǒng)一建模語(yǔ)言。UML 包含的軟件模型有 10 種，其中常用的有 7 種：類(lèi)圖、序列圖、組件圖、部署圖、用例圖、狀態(tài)圖和活動(dòng)圖。

下面我們簡(jiǎn)單了解下這 7 種常用 UML 圖的使用場(chǎng)景和基本樣例。在專欄后面的設(shè)計(jì)文檔中，你會(huì)多次見(jiàn)到它們，看多了，你就懂了，也就自然會(huì)畫(huà)了。當(dāng)然，如果你想更詳細(xì)地學(xué)習(xí) UML 知識(shí)，我也非常鼓勵(lì)，并且推薦你閱讀馬丁富勒的《UML 精粹》一書(shū)。

類(lèi)圖

類(lèi)圖是最常見(jiàn)的 UML 圖形，用來(lái)描述類(lèi)的特性和類(lèi)之間的靜態(tài)關(guān)系。

一個(gè)類(lèi)包含三個(gè)部分：類(lèi)的名字、類(lèi)的屬性列表和類(lèi)的方法列表。類(lèi)之間有 6 種靜態(tài)關(guān)系：關(guān)聯(lián)、依賴、組合、聚合、繼承、泛化。把相關(guān)的一組類(lèi)及其關(guān)系用一張圖畫(huà)出來(lái)，就是類(lèi)圖。

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

時(shí)序圖

類(lèi)圖之外，另一種常用的圖是時(shí)序圖，類(lèi)圖描述類(lèi)之間的靜態(tài)關(guān)系，時(shí)序圖則用來(lái)描述參與者之間的動(dòng)態(tài)調(diào)用關(guān)系。

組件圖

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

組件圖描述組件之間的靜態(tài)關(guān)系，主要是依賴關(guān)系，如果你想要描述組件之間的動(dòng)態(tài)調(diào)用關(guān)系，可以使用組件時(shí)序圖，以組件作為參與者，描述組件之間的消息調(diào)用關(guān)系。

部署圖

部署圖描述軟件系統(tǒng)的最終部署情況，比如需要部署多少服務(wù)器，關(guān)鍵組件都部署在哪些服務(wù)器上。

部署圖是軟件系統(tǒng)最終物理呈現(xiàn)的藍(lán)圖，根據(jù)部署圖，所有相關(guān)者，諸如客戶、老板、工程師都能清晰地了解到最終運(yùn)行的系統(tǒng)在物理上是什么樣子，和現(xiàn)有的系統(tǒng)服務(wù)器的關(guān)系，和第三方服務(wù)器的關(guān)系。根據(jù)部署圖，還可以估算服務(wù)器和第三方軟件的采購(gòu)成本。

因此部署圖是整個(gè)軟件設(shè)計(jì)模型中，比較宏觀的一種圖，是在設(shè)計(jì)早期就需要畫(huà)的一種模型圖。根據(jù)部署圖，各方可以討論對(duì)這個(gè)方案是否認(rèn)可。只有對(duì)部署圖達(dá)成共識(shí)，才能繼續(xù)后面的細(xì)節(jié)設(shè)計(jì)。

用例圖

用例圖通過(guò)反映用戶和軟件系統(tǒng)的交互，描述系統(tǒng)的功能需求。

圖中小人形象的元素，被稱為角色，角色可以是人，也可以是其他的系統(tǒng)。系統(tǒng)的功能可能會(huì)很復(fù)雜，所以一張用例圖可能只包含其中一小部分功能，這些功能被一個(gè)矩形框框起來(lái)，這個(gè)矩形框被稱為用例的邊界。框里的橢圓表示一個(gè)一個(gè)的功能，功能之間可以調(diào)用依賴，也可以進(jìn)行功能擴(kuò)展。

狀態(tài)圖

狀態(tài)圖用來(lái)展示單個(gè)對(duì)象生命周期的狀態(tài)變遷。

業(yè)務(wù)系統(tǒng)中，很多重要的領(lǐng)域?qū)ο蠖加斜容^復(fù)雜的狀態(tài)變遷，比如賬號(hào)，有創(chuàng)建狀態(tài)、激活狀態(tài)、凍結(jié)狀態(tài)、欠費(fèi)狀態(tài)等等各種狀態(tài)。此外，用戶、訂單、商品、紅包這些常見(jiàn)的領(lǐng)域模型都有多種狀態(tài)。

這些狀態(tài)的變遷描述可以在用例圖中用文字描述，隨著角色的各種操作而改變，但是用這種方式描述，狀態(tài)散亂在各處，不要說(shuō)開(kāi)發(fā)的時(shí)候容易搞錯(cuò)，就是產(chǎn)品經(jīng)理自己在設(shè)計(jì)的時(shí)候，也容易搞錯(cuò)對(duì)象的狀態(tài)變遷。

UML 的狀態(tài)圖可以很好地解決這一問(wèn)題，一張狀態(tài)圖描述一個(gè)對(duì)象生命周期的各種狀態(tài)，及其變遷的關(guān)系。如圖所示，門(mén)的狀態(tài)有開(kāi) Opened、關(guān) Closed 和鎖 Locked 三種，狀態(tài)與變遷關(guān)系用一張狀態(tài)圖就可以搞定。

活動(dòng)圖

活動(dòng)圖主要用來(lái)描述過(guò)程邏輯和業(yè)務(wù)流程。UML 中沒(méi)有流程圖，很多時(shí)候，人們用活動(dòng)圖代替流程圖。

活動(dòng)圖和早期流程圖的圖形元素也很接近，實(shí)心圓代表流程開(kāi)始，空心圓代表流程結(jié)束，圓角矩形表示活動(dòng)，菱形表示分支判斷。

此外，活動(dòng)圖引入了一個(gè)重要的概念——泳道。活動(dòng)圖可以根據(jù)活動(dòng)的范圍，將活動(dòng)根據(jù)領(lǐng)域、系統(tǒng)和角色等劃分到不同的泳道中，使流程邊界更加清晰。

我們上面介紹了 UML 建模常用的 7 種模型，那么這 7 種模型分別應(yīng)用在軟件設(shè)計(jì)的什么階段？用來(lái)表達(dá)什么樣的設(shè)計(jì)意圖呢？

4 軟件文檔設(shè)計(jì)

軟件設(shè)計(jì)文檔就是架構(gòu)師的主要工作成果，它需要闡釋本文開(kāi)頭提到的各種訴求，描繪軟件的完整藍(lán)圖，而軟件設(shè)計(jì)文檔的主要組成部分就是軟件模型。

軟件設(shè)計(jì)過(guò)程可以拆分成需求分析、概要設(shè)計(jì)和詳細(xì)設(shè)計(jì)三個(gè)階段。

在需求分析階段，主要是通過(guò)用例圖來(lái)描述系統(tǒng)的功能與使用場(chǎng)景；對(duì)于關(guān)鍵的業(yè)務(wù)流程，可以通過(guò)活動(dòng)圖描述；如果在需求階段就提出要和現(xiàn)有的某些子系統(tǒng)整合，那么可以通過(guò)時(shí)序圖描述新系統(tǒng)和原來(lái)的子系統(tǒng)的調(diào)用關(guān)系；可以通過(guò)簡(jiǎn)化的類(lèi)圖進(jìn)行領(lǐng)域模型抽象，并描述核心領(lǐng)域?qū)ο笾g的關(guān)系；如果某些對(duì)象內(nèi)部會(huì)有復(fù)雜的狀態(tài)變化，比如用戶、訂單這些，可以用狀態(tài)圖進(jìn)行描述。

在概要設(shè)計(jì)階段，通過(guò)部署圖描述系統(tǒng)最終的物理藍(lán)圖；通過(guò)組件圖以及組件時(shí)序圖設(shè)計(jì)軟件主要模塊及其關(guān)系；還可以通過(guò)組件活動(dòng)圖描述組件間的流程邏輯。

在詳細(xì)設(shè)計(jì)階段，主要輸出的就是類(lèi)圖和類(lèi)的時(shí)序圖，指導(dǎo)最終的代碼開(kāi)發(fā)，如果某個(gè)類(lèi)方法內(nèi)部有比較復(fù)雜的邏輯，那么可以將這個(gè)方法的邏輯用活動(dòng)圖進(jìn)行描述。

我們?cè)诿總€(gè)設(shè)計(jì)階段使用幾種 UML 模型對(duì)領(lǐng)域或者系統(tǒng)進(jìn)行建模，然后將這些模型配上必要的文字說(shuō)明寫(xiě)入到文檔中，就可以構(gòu)成一篇軟件設(shè)計(jì)文檔了。

我們專欄中的十幾講軟件設(shè)計(jì)案例，都是按照這樣的方式組織的，你可以在學(xué)習(xí)的過(guò)程中，一方面了解各種系統(tǒng)軟件是如何設(shè)計(jì)的，一方面也可以借鑒設(shè)計(jì)文檔是如何寫(xiě)作的。

同時(shí)也要說(shuō)明一下，設(shè)計(jì)文檔的寫(xiě)法并沒(méi)有一定之規(guī)，最重要的是這個(gè)文檔能否向閱讀者傳遞出架構(gòu)師完整的設(shè)計(jì)意圖。而不同的閱讀者關(guān)注點(diǎn)是不同的，老板、客戶、運(yùn)維、測(cè)試、開(kāi)發(fā)這些角色都是設(shè)計(jì)文檔的閱讀者，他們想要看到的東西顯然是不一樣的。

客戶和測(cè)試人員可能更關(guān)注功能性需求和實(shí)現(xiàn)邏輯，老板和運(yùn)維人員可能更關(guān)注非功能需求和整體架構(gòu)，而開(kāi)發(fā)人員可能更關(guān)注整體架構(gòu)與關(guān)鍵技術(shù)細(xì)節(jié)。

我們專欄的案例基本上是以開(kāi)發(fā)人員作為閱讀視角進(jìn)行編寫(xiě)的，你在閱讀這些案例時(shí)，會(huì)明顯感覺(jué)到我的表達(dá)方式和其他專欄文章不太一樣，措辭會(huì)更“堅(jiān)硬”一點(diǎn)，文字和讀者的距離也有點(diǎn)“疏離”，而這正是設(shè)計(jì)文檔自身的特質(zhì)。

架構(gòu)、系統(tǒng)，文檔、相關(guān)人員之間的關(guān)系可以參考下面這張圖。

每個(gè)軟件系統(tǒng)都需要有一個(gè)架構(gòu)，每個(gè)架構(gòu)都包含若干架構(gòu)元素。架構(gòu)元素就是前面提到的服務(wù)器、組件、類(lèi)、消息、用例、狀態(tài)等等。這些元素之間的關(guān)系是什么？如何把它們組織在一起？我們可以用部署圖、組件圖、時(shí)序圖等各種模型圖來(lái)描述。

架構(gòu)最終需要一個(gè)文檔來(lái)承載，把這些模型圖放進(jìn)這個(gè)文檔，再配以適當(dāng)?shù)奈淖终f(shuō)明，就是一篇架構(gòu)設(shè)計(jì)文檔。而設(shè)計(jì)文檔是給人閱讀的，這些人就是系統(tǒng)的相關(guān)方。不同的相關(guān)方關(guān)注點(diǎn)不同，也需要由不同的模型圖來(lái)進(jìn)行表達(dá)，所以架構(gòu)師應(yīng)該針對(duì)不同的相關(guān)方，使用不同的模型圖輸出不同的架構(gòu)文檔。

5 小結(jié)

軟件設(shè)計(jì)就是在軟件開(kāi)發(fā)之前，對(duì)要解決的業(yè)務(wù)問(wèn)題和對(duì)要實(shí)現(xiàn)的軟件系統(tǒng)進(jìn)行思考，并將這個(gè)思考的結(jié)果通過(guò)軟件模型表達(dá)出來(lái)的過(guò)程。

人類(lèi)作為萬(wàn)物之靈，最大的特點(diǎn)就是，在行動(dòng)之前就已經(jīng)在頭腦中將行動(dòng)的過(guò)程和行動(dòng)的結(jié)果構(gòu)建成了一個(gè)藍(lán)圖，然后將這個(gè)藍(lán)圖付諸實(shí)踐。我們的祖先將第一塊石頭打磨成石器的時(shí)候，就已經(jīng)擁有了這種能力。軟件系統(tǒng)的開(kāi)發(fā)是一個(gè)復(fù)雜的智力活動(dòng)，參與其中的我們更需要擁有構(gòu)建藍(lán)圖并付諸實(shí)踐的能力。

目前有個(gè)很火的詞叫“元宇宙”，“元”通俗地講，就是一切開(kāi)始的地方，是關(guān)于如何用自己描述自己，是抽象之上的抽象。這種“元”能力對(duì)架構(gòu)師而言，非常重要。架構(gòu)師只有掌握各種技術(shù)背后的技術(shù)，了解各種問(wèn)題背后的問(wèn)題，才能超越當(dāng)下的種種羈絆，設(shè)計(jì)出面向未來(lái)的架構(gòu)。