談一份技術設計文檔中應該出現的圖

談一份技術設計文檔中應該出現的圖

前言

最近在聽過李智慧老師的課，正好在講一份技術架構文檔如何編寫，覺得李老師說的很清晰也很明白。我們今天就再次對此話題進行一番討論。只求能更詳細的說明問題，技術的路的沒有盡頭，也希望大家多加指，大家一起進步。

淺談做軟件架構

正如李老師所說，一切皆可以用架構來概述。要想做好一件事情，在最開始一定是有一個合理的架構規劃。從軟件開發的早期，開發人員使用傳統的瀑布開發模型，開發拿到需求之後按部就班缺少規劃，越到後面發現每一個階段的開展都需要依賴上一步驟的成果才能進行，軟件開發過程中的變數很多，越到最後越發現這樣沒有規劃的工作會很難做好一件事情。到後來，人們對合作方式和項目架構加以改進，不同的情況就去使用不同的戰略戰術，比如什麼場景使用什麼樣的項目合作方式才能更好的得到結果。如果一個團隊的能力平均，那這個團隊做到民主製程序員組更容易成功。若這個團隊某個人的能力更突出，可能主程序組合作方式更有效率。複雜的情況，可能現代的程序員組更好。這一切組合都來自於對實際情況的認真思考。事情都需要提前做好規劃，生活需要有架構。

進入正題

4+1 視圖模型

引自：https://www.ibm.com/developerworks/cn/rational/r-4p1-view/index.html

我們常聽說4+1軟件視圖，它基本能涵蓋我們所有的軟件架構設計，我們不做4+1背景介紹了，我們只來提煉一些精髓，方便我們架構文檔的設計。

軟件架構涉及到抽象、分解和組合、風格和美學

大神總有如上說，也確實說的好。軟件架構是一些元素、形式、關係/約束的組合。軟件架構 ＝ {元素，形式，關係/約束}
4個視圖指的是：

• 邏輯視圖
• 過程視圖
• 物理視圖
• 開發視圖
  最後用一些場景或約束來貫穿整體，從而形成5個視圖。
  下圖爲4+1視圖對應我們軟件工程中各角色各階段的分工產物，總結的很清晰到位。
  

部署圖

正式規劃一個項目文檔，在描述清楚一些技術或非技術需求後，最先開始需要着手的就是部署圖。部署圖可以體現對整體架構的規劃，部署圖需要體現出節點或組件間的依賴關係。通過部署圖，可以瞭解到整體項目的規劃部署，從而對整體架構有一個宏觀的認識。

組件圖

組件圖體現出對系統內部的一個微觀架構的規劃。一個架構可以分爲宏觀視角和微觀視角，如果說部署圖體現的是架構的宏觀視角，那麼組件圖更多體現的是架構的微觀視角，更多的是體現在一個服務內部的組件規劃。一個系統的組件規劃，也更適合出現在整體架構的開始，例如架構部署圖後緊接着就是組件規劃圖。

序列圖/時序圖

序列圖是表示時序活動的一種圖，可以用來描述系統間的時序關係、組件間的時序關係或是接口之間的時序調用關係。序列圖適合出現在一個軟件設計文檔的各個地方，如果需要體現不同系統之間的調用關係，比如一個商城交易服務，會涉及到支付、庫存、物流、訂單等不同系統服務，那麼時序圖就可以體現他們之間的調用關係或是返回結果。如果是一個系統內部組件之間的調用，那麼時序圖就應該出現在組件設計部分，用來體現組件間的調用關係。如果是接口調用，那麼時序圖更應該體現接口之間的交互信息。

用例圖

用例圖其實更適合於需求分析階段，以不同的角色去定位不同場景的用例關係。在一份軟件設計文檔中，更多的細節是針對不同的場景去設計具體的實現， 這時候用例圖就可以體現一個場景規劃的作用，讓讀者更容易明白該模塊設計的意圖。

活動圖/狀態圖

活動圖和狀態圖既適合於某個場景內部的設計中，也可以出現在整體規劃開始，讓人一眼就看明白系統的活動狀態。

• 活動圖
  
• 狀態圖
  

類圖

類圖在UML中是最具體最詳細的設計體現了，所以一般也只會出現在技術詳細設計中，開發人員基本可以按照此進行編碼開發了。類圖可以出現在組件設計模塊，用來體現某一組件具體的落地實現。

其他圖

一份合格的技術設計文檔中，大體包括以上設計圖來表達一份技術描述通常已經足夠了。我們大部分都是喜歡看圖勝過看文字或是語音，在圖形之外，我們可以結合場景用一些文字來輔助描述，正好起到點睛之筆了。
在上面提到的設計圖外，我們更多還會用很多圖，例如

• ER圖
• 流程圖
• 泳道圖
• HIPO圖
• 結構圖
• 等等
  其實仔細看，這只是UML中組件圖或活動圖或狀態圖的變形了。具體用哪種圖才能說明場景問題，也需要看我們不同的使用場景了。

最後的建議

技術文檔如何才能做到條理清晰，和架構師的敘事邏輯也有很大的關係。比如我們的故事是倒序還是正序，結構採用總分還是分總，也是值得我們考慮的事情。