《軟件架構設計文檔》

1、<Project Name>Software Architecture DocumentVersion <1.0>Revision HistoryDateVersionDescriptionAuthor< yyyy-mm-dd ><x.x><details><name>目錄1. 文檔簡介1.1 文檔目的1.2 文檔范圍1.3 定義、縮寫詞和縮略語1.4 參考資料2. 架構描述方式2.1 架構視圖閱讀指南2.2 圖表與模型閱讀指南3. 架構設計目標3.1 關鍵功能3.2 關鍵質量屬性3.3 業(yè)務需求和約束因素4. 架構設計原

2、則4.1 架構設計原則4.2 備選架構設計方案及被否原因4.3 架構設計對后續(xù)工作的限制（詳設，部署等）5. 邏輯架構視圖5.15.25.3職責劃分與職責確定 接口設計與協(xié)作機制 重要設計包6.開發(fā)架構視圖6.1Project 劃分6.2Project 16.2.1Project 目錄結構指導6.2.2程序單元組織6.2.3框架與應用之間的關系（可選）6.3Project 2 6.4Project n 7.運行架構視圖7.1控制流組織7.2控制流的創(chuàng)建、銷毀、通信7.3加鎖設計8. 物理架構視圖8.1 物理拓撲8.2 軟件到硬件的映射8.3 優(yōu)化部署9. 數(shù)據(jù)架構視圖9.1 持久化機制的選擇9

3、.2 持久化存儲方案9.3 數(shù)據(jù)同步與復制策略10. 關鍵質量屬性的設計原理1. 文檔簡介幫助讀者對本文檔建立基本印象，并為閱讀后續(xù)內(nèi)容掃清障礙。1.1 文檔目的 文檔目的，非項目目的。否則造成同一項目多個文檔之間的內(nèi)容重復，不利于文檔維護。本 小節(jié)應指明文檔針對的讀者對象，最好列出各種讀者角色，并說明每種讀者角色應該重點閱讀 的章節(jié)。 1.2 文檔范圍文檔的 Scope ，非項目的 Scope 。否則造成同一項目多個文檔之間的內(nèi)容重復，不利于文檔 維護。 1.3 定義、縮寫詞和縮略語 集中列舉文檔中的定義、縮寫詞和縮略語。1.4 參考資料 本項目經(jīng)審核的計劃書、合同、上級批文；本項目的其他已

4、發(fā)表文件；本文檔引用的文件資 料，如軟件開發(fā)標準。具體而言，應包括參考資料的題目（必須）、編號、版本號（必須）、 發(fā)表日期、發(fā)布方，必要時還可以說明如何使用這些資料。 2. 架構描述方式 為了讓讀者更好地理解架構文檔，在本節(jié)應當說明文檔涉及的架構視圖，并指明為了描 述設計決策用到了哪些圖表和模型。 2.1 架構視圖閱讀指南 以多視圖的方式來組織架構文檔是大勢所趨。推薦的是經(jīng)過優(yōu)化的5 視圖方法，如下圖所示。 2.2 圖表與模型閱讀指南對后續(xù)文檔內(nèi)容中所用到的建模語言（例如UML ）、表格（例如目標 -場景 -決策表）等進行說明。 3.3.13.23.34.4.14.24.35.5.1架構設計目

5、標功能、質量、約束，一個都不能少。關鍵功能對架構設計至關重要的功能，包括如下4 類：核心功能、必做功能、高風險功能、獨特功能。所謂獨特功能，指這個功能覆蓋了上述 3 類功能沒有涉及到的職責。 關鍵質量屬性人之所以痛苦，很多時候是因為追求錯誤的東西。下圖是確定關鍵質量的5 大原則的整體思路圖。 業(yè)務需求和約束因素創(chuàng)造性地提出約束需求的 4 大類型，這是一種極為實用的分類方式。特別是業(yè)務需求對架構 設計而言是一種約束的觀點，解決了很多架構師的現(xiàn)實困惑。下圖標明了 4 類約束在“需求層 次- 需求方面矩陣”中的位置，可以幫助我們理解產(chǎn)生約束需求的根源。架構設計原則投標時經(jīng)常講“架構設計原則”，但到了

6、架構文檔，這些著眼大局的考慮卻“丟了”。 推薦的本文檔模板，認為應當把它們“找回來”。 架構設計原則著重描述重大的權衡取舍考慮。 備選架構設計方案及被否原因在概念架構一級，對備選架構設計方案進行描述，并闡述它們未被采用的原因。這有利于團 隊了解當前架構設計方案的來龍去脈，提高團隊對當前架構設計方案的認可度。 架構設計對后續(xù)工作的限制（詳設，部署等）架構設計不僅應該包含“指導”，也應該包含重要的“限制”。例如，一份只是說明“性能 和可擴展性都重要”的架構文檔，實際上忽視了“可擴展性和性能之間存在的矛盾關 系”。此時，最有效的辦法就是在架構文檔中明確說明“任何提升可擴展性的架構設計和 詳細設計，都

7、應通過架構團隊的評審才能引入，以確保性能目標不受重大影響”。 邏輯架構視圖關注點：此架構設計視圖的關注點是職責劃分。注意：邏輯架構視圖無疑是最重要的，但同時也應避免“架構= 模塊 + 接口”等以偏概全的認識。 參考：任何復雜系統(tǒng)的架構設計都不是一蹴而就的，所以架構師需要理性思維過程的指導。 針對邏輯架構設計這個關鍵環(huán)節(jié)，一線架構師實踐指南一書給出了 2 條建議：一是“以質 疑驅動的螺旋思維”，二是相對分離地考慮“結構方面的切分”和“行為方面的定義”。下圖 所示即為推薦的邏輯架構設計理性思維過程。 職責劃分與職責確定內(nèi)容：將系統(tǒng)切分成更小的單元，并明確這些單元的職責。具體而言，職責單元可以是層、

8、 子系統(tǒng)、模塊、關鍵類等。 意義：一句話，職責劃分不合理，功能和質量都會受到影響。也就是說，功能需求和質量需求無一不和職責劃分相關：一方面，每個功能都是由一條職責協(xié)作鏈完成的；另一方面，職責劃分方式也影響著質量，于是需要職責模型針對特定質量屬性要求做出相應調(diào)整和優(yōu)化。很多 人認為架構設計就是職責劃分的藝術，雖略顯片面，但足以表明職責劃分的重要性。 參考：基于對業(yè)界大量案例的研究，梳理出了“模塊劃分的3 種必用手段”，如下圖所示，更多內(nèi)容可參考一線架構師實踐指南一書。 5.2 接口設計與協(xié)作機制內(nèi)容：本節(jié)描述接口的定義，以及協(xié)作的方式和規(guī)范。意義：恰恰是因為有了各模塊之間“未來合作的契約”，分頭

9、開發(fā)各模塊才有了基本保證。參考：推薦利用“包 -接口”圖，來識別接口。下圖為一個“包-接口”圖的示例。 參考：推薦使用序列圖，建議少用、甚至杜絕使用協(xié)作圖。下圖為一個序列圖的示例。5.3 重要設計包內(nèi)容：對重要子系統(tǒng)的設計進行“灰盒”級描述。意義：“每個子系統(tǒng)在架構設計中都應保持黑盒子”的觀點，過于理想化了。對于業(yè)務層、 通用協(xié)作機制而言，經(jīng)常需要在架構設計期間就引入“灰盒”級描述。 參考：類圖和灰盒包圖，在本節(jié)中較多出現(xiàn)。下圖為一灰盒包圖示例。6. 開發(fā)架構視圖關注點：此架構設計視圖的關注點是程序單元組織。注意：此架構設計視圖是必須的、不應“剪裁”掉的。但實際情況卻是，很多架構師不關注 開發(fā)

10、架構視圖，導致很多程序開發(fā)人員抱怨“架構師就知道高來高去，架構對編程工作沒什么 指導性”。 6.1 Project 劃分內(nèi)容：本節(jié)說明整個系統(tǒng)將劃分成哪幾個 Project 來開發(fā)，其中， Project 指開發(fā)環(huán)境所感知 到的“工程”。 意義：基本好處是，有利于開發(fā)的組織；而對一些大型的集成系統(tǒng)而言，由于同時涉及了Web 應用、桌面應用、嵌入式應用等軟件形態(tài)，所以此時 Project 劃分其實是不得不做的；最 后，我們推薦核心代碼應主動地切分到單獨的 Project 以進行獨立的軟件配置管理（ SCM ）， 以降低核心代碼外泄的風險。 參考： Project 劃分必然是屬于“架構設計”的工作

11、，嚴格來講僅靠“需求分析”劃分的業(yè)務域（ Business Area ）直接映射到 Project 經(jīng)常意味著工作內(nèi)容的遺漏。其實，業(yè)界不少有見地 的專家已經(jīng)認識到 WBS （工作分解結構）做得太早太草率危害很大，就與“ Project 劃分不到 位”不無關系。 6.2 Project 1 內(nèi)容：對 Project 劃分后的每個 Project 進行目錄結構、程序單元組織、框架與應用關系的說 明。Project 目錄結構指導 內(nèi)容：關于該 Project 一級目錄、二級目錄等基本目錄結構的約定。意義：為團隊并行開發(fā)提供必要基礎，讓不同程序小組看到自己應該負責的程序目錄。參考：不要把所有程序目錄

12、的約定都定義得太細，否則這份架構文檔就要天天更新了。程序單元組織內(nèi)容：源碼、程序庫、框架、目標碼等類型程序單元之間的編譯依賴關系。意義：或許有人認為這沒什么技術含量，但架構設計本來就不是只關心技術含量最高問題 的。君不見，很多軟件工程師跳槽到新的企業(yè)之后，竟然連一個能正常編譯源碼的開發(fā)環(huán)境都 建不起來其實，他們“不知道 Project 所依賴的 Library 有哪些”是其中重要原因這本 應在架構文檔中給出明確描述的。 6.2.3 框架與應用之間的關系（可選） 內(nèi)容：框架（ Framework ）。 意義：既然不適用 Framework 的開發(fā)越來越少了，既然程序員犯的很多錯誤都和對Frame

13、work 理解不到位有關，架構師就有責任明確說明 Framework 和待開發(fā)系統(tǒng)之間的關 系。 參考：下圖描述了 JGraph 框架和待開發(fā)應用的關系。 參考：下圖描述了 Struts 框架和待開發(fā)應用的關系。 6.3 Project 2 內(nèi)容：對 Project 劃分后的每個 Project 進行目錄結構、程序單元組織、框架與應用關系的說 明。6.4 Project n 內(nèi)容：對 Project 劃分后的每個 Project 進行目錄結構、程序單元組織、框架與應用關系的說 明。7. 運行架構視圖關注點：此架構設計視圖的關注點是控制流組織。注意：進程和線程是廣為人知的控制流實現(xiàn)技術，但在架構

14、設計思維當中，對于系統(tǒng)軟件和 嵌入式軟件極為重要的中斷服務程序也是控制流，這樣利于架構師統(tǒng)一利用不同控制流手段設 計并行和并發(fā)。 7.1 控制流組織內(nèi)容：控制流有哪些，每條控制流各是何種形式（例如進程、線程、中斷服務程序），哪些 軟件單元是控制流的起點，整條控制流中分別調(diào)用了哪些軟件單元。 意義：這是對系統(tǒng)運行時結構的刻畫，主要反映系統(tǒng)的動態(tài)結構。7.2 控制流的創(chuàng)建、銷毀、通信內(nèi)容：描述進程、線程和中斷服務程序的創(chuàng)建和銷毀，以及多條控制流之間的通信關系的定義。意義：一旦引入了多條控制流，附加工作就產(chǎn)生了此時控制流的創(chuàng)建和銷毀、以及控制 流之間的通信關系往往是必須考慮的。 7.3 加鎖設計 內(nèi)

15、容：系統(tǒng)中有多條控制流在同時運行的情況下，一個經(jīng)典問題是多于一條控制流可能會同 時修改某些數(shù)據(jù)結構，而造成數(shù)據(jù)的不一致。為此，架構師需要關注加鎖設計，合理引入臨界 區(qū)或同步機制。 意義：加鎖設計事關系統(tǒng)的正確性。值得注意的是，忽略加鎖設計造成的問題往往以“不易 重現(xiàn)的 Bug ”的形式出現(xiàn)，困惑的程序員會對測試人員說，“你看你報的 Bug 在我機器上根 本就不存在呀”。 參考：對通用組件、通用模塊的設計而言，加鎖設計應予以專門關注，思維要點是研究未來 通用模塊的各種可能使用場景。 8. 物理架構視圖關注點：此架構設計視圖的關注點是物理節(jié)點（Node ）分布，以及軟件到硬件的具體映射關系。 注意

16、：物理節(jié)點即可以是 PC 機或服務器，也可以是單片機、單板機或專用機，從而物理架構 視圖既適用于描述企業(yè)信息系統(tǒng)，也適合于描述嵌入式軟件系統(tǒng)。 8.1 物理拓撲 內(nèi)容：一為硬件選型，二為硬件之間的拓撲連接關系。意義：對于分布式系統(tǒng)的設計，此節(jié)極為重要、而且是必須的。參考：下圖是某企業(yè)級系統(tǒng)的物理拓撲圖。參考：下圖是某嵌入式系統(tǒng)的物理拓撲圖。8.2 軟件到硬件的映射 內(nèi)容：明確每個物理節(jié)點上有哪些（一到多個）軟件的目標單元，并說明具體的“映射方 式”是安裝、是部署、還是燒寫、抑或是下載。 意義：如果把此節(jié)漏了，就無法表明本文檔的主題軟件系統(tǒng)和上述硬件、硬件拓撲 的關系。 參考：下圖所示為設備調(diào)試

17、系統(tǒng)中，軟件到硬件的映射關系。8.3 優(yōu)化部署 內(nèi)容：為達降低成本、提高性能和可靠性等等目標，應特別關注的部署考慮。意義：物理架構設計的優(yōu)劣，造成的成本差異和質量差異，可能是天壤之別。所以必須重 視。參考：下圖展示的，是 ADMEMS 方法重點推薦的“物理架構設計思維要點”，更多內(nèi)容可參 考一線架構師實踐指南一書。 9. 數(shù)據(jù)架構視圖 關注點：此架構設計視圖的關注點是持久化。具體而言，場景化可以借助扁平文件、關系數(shù) 據(jù)庫、實時數(shù)據(jù)庫、 Flash 等方式中的一種或多種完成。 注意：本視圖單獨歸檔時，請在此節(jié)注明其文檔名稱等信息。9.1 持久化機制的選擇 內(nèi)容：如下持久化機制的一種或多種：扁平文件、關系數(shù)據(jù)庫、實時數(shù)據(jù)庫、Flash 。意義：不要假設在你的系統(tǒng)中，持久化只需一種機制；隨著如今的系統(tǒng)變得越來越復雜，我 們經(jīng)常需要綜合利用不同持久化機制。 9.2 持久化存儲方案 內(nèi)容：持久化數(shù)據(jù)的格式定義。意義：統(tǒng)一定義表、文件格式、Flash 數(shù)據(jù)結構等內(nèi)容。 9.3 數(shù)據(jù)同步與復制策略 內(nèi)容：由于數(shù)據(jù)分布所引起的，包含數(shù)據(jù)分布、同步、復制等內(nèi)容的重要設計決策。意義：在數(shù)據(jù)分布的情況下，此節(jié)為必須。參考：在實際中，數(shù)據(jù)分布的策略絕大多數(shù)情況下不會超越下圖所示的6 種手段，更多內(nèi)容可參考一線架構師實踐指南一書