《軟件架構設計文檔》模板

1、vProject NameVersio n:<1.0>Software Architecture Docume ntDate: < yyyy-mm-dd >vdocument identifier>目錄1.文檔簡介31.1文檔目的31.2文檔范圍31.3定義、縮寫詞和縮略語31.4參考資料32.架構描述方式32.1架構視圖閱讀指南32.2圖表與模型閱讀指南43.架構設計目標43.1關鍵功能43.2關鍵質量屬性43.3業(yè)務需求和約束因素54.架構設計原則54.1架構設計原則54.2備選架構設計方案及被否原因54.3架構設計對后續(xù)工作的限制（詳設，部署等）55.邏輯架

2、構視圖65.1職責劃分與職責確定65.2接口設計與協(xié)作機制75.3重要設計包96.開發(fā)架構視圖106.1Project 劃分106.2Project 1106.2.1 Project目錄結構指導116.2.2程序單元組織116.2.3框架與應用之間的關系（可選）116.3Project 2126.4Project n 127.運行架構視圖127.1控制流組織127.2控制流的創(chuàng)建、銷毀、通信137.3加鎖設計138.物理架構視圖138.1物理拓撲138.2軟件到硬件的映射148.3優(yōu)化部署15vProject NameVersio n:<1.0>Software Architect

3、ure Docume ntDate: < yyyy-mm-dd >vdocument identifier>9.數(shù)據(jù)架構視圖159.1持久化機制的選擇169.2持久化存儲方案169.3數(shù)據(jù)同步與復制策略1610.關鍵質量屬性的設計原理16ADMEMSPage 2 of 17vProject NameVersio n:<1.0>Software Architecture Docume ntDate: < yyyy-mm-dd >vdocument identifier>1. 文檔簡介幫助讀者對本文檔建立基本印象，并為閱讀后續(xù)內容掃清障礙。1.1 文

4、檔目的文檔目的，非項目目的。否則造成同一項目多個文檔之間的內容重復，不利于文檔維護。本 小節(jié)應指明文檔針對的讀者對象，最好列出各種讀者角色，并說明每種讀者角色應該重點閱讀 的章節(jié)。1.2 文檔范圍文檔的Scope，非項目的Scope。否則造成同一項目多個文檔之間的內容重復，不利于文檔 維護。1.3 定義、縮寫詞和縮略語集中列舉文檔中的定義、縮寫詞和縮略語。1.4 參考資料本項目經(jīng)審核的計劃書、合同、上級批文；本項目的其他已發(fā)表文件；本文檔引用的文件資 料，如軟件開發(fā)標準。具體而言，應包括參考資料的題目（必須）、編號、版本號（必須）、 發(fā)表日期、發(fā)布方，必要時還可以說明如何使用這些資料。2. 架

5、構描述方式為了讓讀者更好地理解架構文檔，在本節(jié)應當說明文檔涉及的架構視圖，并指明為了描 述設計決策用到了哪些圖表和模型。2.1 架構視圖閱讀指南以多視圖的方式來組織架構文檔是大勢所趨。ADMEMS推薦的是經(jīng)過優(yōu)化的 5視圖方法，如下圖所示。vProject NameVersio n:<1.0>Software Architecture Docume ntDate: < yyyy-mm-dd >vdocument identifier>面向控制流面向文件面向Table 或文杵而向對彖 或結構化邏輯架構、職奇劃分 職責間協(xié)作運行架構 控制流 控制流組織程序單元 程序單

6、元組織數(shù)扌居架構y捋久數(shù)據(jù)單元物理架構、 物理節(jié)點 、 物理節(jié)點拓卅1./面向節(jié)點22圖表與模型閱讀指南對后續(xù)文檔內容中所用到的建模語言（例如UML ）、表格（例如目標-場景-決策表）等進行說明。3. 架構設計目標功能、質量、約束，一個都不能少。3.1 關鍵功能對架構設計至關重要的功能，包括如下4類：核心功能、必做功能、高風險功能、獨特功能。所謂獨特功能，指這個功能覆蓋了上述3類功能沒有涉及到的職責。3.2關鍵質量屬性人之所以痛苦，很多時候是因為追求錯誤的東西。下圖是ADMEMS方法確定關鍵質量的 5ADMEMSPage 5 of 17vProject NameVersio n:<1.0

7、>Software Architecture Docume ntDate: < yyyy-mm-dd >vdocument identifier>3.3業(yè)務需求和約束因素ADMEMS方法創(chuàng)造性地提出約束需求的 4大類型，這是一種極為實用的分類方式。特別是業(yè) 務需求對架構設計而言是一種約束的觀點，解決了很多架構師的現(xiàn)實困惑。下圖標明了4類約束在“需求層次-需求方面矩陣（又稱 ADMEMS矩陣）”中的位置，可以幫助我們理解產(chǎn)生 約束需求的根源。廣義功能質量約東ADMEMSec口慈ifiH力潘IPage 6 of 17ADMEMSec口慈ifiH力潘IPage # of 17

8、業(yè)務級用戶級需求開發(fā)級需求用戶需求彳了為需求運行期質量開發(fā)期質量/ II.* I耳開發(fā)團臥磨餚長 尸n " 省石構建壞境I業(yè)務環(huán)境分批丈施競爭因丟與咅浄并X堆滬4. 架構設計原則投標時經(jīng)常講“架構設計原則”，但到了架構文檔，這些著眼大局的考慮卻“丟了”。ADMEMS方法推薦的本文檔模板，認為應當把它們“找回來”。4.1 架構設計原則著重描述重大的權衡取舍考慮。4.2 備選架構設計方案及被否原因在概念架構一級，對備選架構設計方案進行描述，并闡述它們未被采用的原因。這有利于團 隊了解當前架構設計方案的來龍去脈，提高團隊對當前架構設計方案的認可度。4.3 架構設計對后續(xù)工作的限制（詳設，部

9、署等）架構設計不僅應該包含“指導”，也應該包含重要的“限制”。例如，一份只是說明“性能 和可擴展性都重要”的架構文檔，實際上忽視了“可擴展性和性能之間存在的矛盾關 系”。此時，最有效的辦法就是在架構文檔中明確說明“任何提升可擴展性的架構設計和 詳細設計，都應通過架構團隊的評審才能引入，以確保性能目標不受重大影響”。ADMEMSec口慈ifiH力潘IPage # of 17vProject NameVersio n:<1.0>Software Architecture Docume ntDate: < yyyy-mm-dd >vdocument identifier>

10、;5.邏輯架構視圖關注點：此架構設計視圖的關注點是職責劃分。注意：邏輯架構視圖無疑是最重要的，但同時也應避免“架構=模塊+接口”等以偏概全的認識。參考：任何復雜系統(tǒng)的架構設計都不是一蹴而就的，所以架構師需要理性思維過程的指導。針對邏輯架構設計這個關鍵環(huán)節(jié)，一線架構師實踐指南一書給出了2條建議：一是“以質疑驅動的螺旋思維”，二是相對分離地考慮“結構方面的切分”和“行為方面的定義”。下圖 所示即為ADMEMS方法推薦的邏輯架構設計理性思維過程。質就自已的設計， 特殊功能場景支持嗎 耦合性、重用性咋樣結構方面的切分5.1包接口± .-I d aa完善序列圖行為方面的約定讓職責協(xié)作起來* 驗

11、還能否完成功能? 功能完成得是否好?職責劃分與職責確定內容：將系統(tǒng)切分成更小的單元，并明確這些單元的職責。具體而言，職責單元可以是層、 子系統(tǒng)、模塊、關鍵類等。意義：一句話，職責劃分不合理，功能和質量都會受到影響。也就是說，功能需求和質量需 求無一不和職責劃分相關：一方面，每個功能都是由一條職責協(xié)作鏈完成的；另一方面，職責 劃分方式也影響著質量，于是需要職責模型針對特定質量屬性要求做出相應調整和優(yōu)化。很多 人認為架構設計就是職責劃分的藝術，雖略顯片面，但足以表明職責劃分的重要性。參考：基于對業(yè)界大量案例的研究，ADMEMS方法梳理出了 “模塊劃分的 3種必用手段”，如下圖所示，更多內容可參考一

12、線架構師實踐指南一書。ADMEMSPage 8 of 17vProject NameVersio n:<1.0>Software Architecture Docume ntDate: < yyyy-mm-dd >vdocument identifier>架構本身考慮人的因素考慮5.2 接口設計與協(xié)作機制內容：本節(jié)描述接口的定義，以及協(xié)作的方式和規(guī)范。意義：恰恰是因為有了各模塊之間“未來合作的契約”，分頭開發(fā)各模塊才有了基本保證。參考：ADMEMS方法推薦利用“包-接口”圖，來識別接口。下圖為一個“包-接口”圖的示例。ADMEMSPage 9 of 17vProj

13、ect NameVersio n:<1.0>Software Architecture Docume ntDate: < yyyy-mm-dd >vdocument identifier>進度展現(xiàn) 回到接口Facade甜眷描述鐵種搖口習能援沖機制內祚撫沖達“瓠定血11客ijT M相剛童口進行回返對超出額定九11喜債的內容進打肖催廉右接口參考：ADMEMS方法推薦使用序列圖，建議少用、甚至杜絕使用協(xié)作圖。下圖為一個序列圖 的示例。vProject NameVersio n:<1.0>Software Architecture Docume ntDate:

14、 < yyyy-mm-dd >vdocument identifier>龍扌擰癢軸，i論阿耀出gL11IiiiWrite C）"J11111亠Callbsak （Buffer A IIT1 1110ulpui（ Jh 用緩紳區(qū)）滿 f IJIIIL11Callback £ 吐度）L1il煒進度J1Callback ifHti J1r15.3 重要設計包內容：對重要子系統(tǒng)的設計進行“灰盒”級描述。意義：“每個子系統(tǒng)在架構設計中都應保持黑盒子”的觀點，過于理想化了。對于業(yè)務層、 通用協(xié)作機制而言，經(jīng)常需要在架構設計期間就引入“灰盒”級描述。參考：類圖和灰盒包圖

15、，在本節(jié)中較多出現(xiàn)。下圖為一灰盒包圖示例。ADMEMS畋b齦卿邀比方玉|Page 11 of 17vProject NameVersio n:<1.0>Software Architecture Docume ntDate: < yyyy-mm-dd >vdocument identifier>授現(xiàn)層:Adapter/t ；* 一*l1zLWGanttChartlmpI調用來口第=方的4甘特閨繪制包Gintert ace.'Ganttf hartADMEMS畋徑如Wifi H方住Page # of 17ADMEMS畋徑如Wifi H方住Page # of

16、17業(yè)務繪讀収數(shù)擁interface.?rgMgiMadc6. 開發(fā)架構視圖關注點：此架構設計視圖的關注點是程序單元組織。注意：此架構設計視圖是必須的、不應“剪裁”掉的。但實際情況卻是，很多架構師不關注 開發(fā)架構視圖，導致很多程序開發(fā)人員抱怨“架構師就知道高來高去，架構對編程工作沒什么 指導性”。6.1 Project 劃分內容：本節(jié)說明整個系統(tǒng)將劃分成哪幾個Project來開發(fā)，其中，Project指開發(fā)環(huán)境所感知到的“工程”。意義：基本好處是，有利于開發(fā)的組織；而對一些大型的集成系統(tǒng)而言，由于同時涉及了Web應用、桌面應用、嵌入式應用等軟件形態(tài)，所以此時Project劃分其實是不得不做的；

17、最后，我們推薦核心代碼應主動地切分到單獨的Project以進行獨立的軟件配置管理（ SCM），以降低核心代碼外泄的風險。參考：Project劃分必然是屬于“架構設計”的工作，嚴格來講僅靠“需求分析”劃分的業(yè)務 域（Bus in ess Area ）直接映射到Project經(jīng)常意味著工作內容的遺漏。其實，業(yè)界不少有見地 的專家已經(jīng)認識到 WBS （工作分解結構）做得太早太草率危害很大，就與“ Project劃分不到 位”不無關系。6.2 Project 1內容：對Project劃分后的每個 Project進行目錄結構、程序單元組織、框架與應用關系的說vProject NameVersio n:&

18、lt;1.0>Software Architecture Docume ntDate: < yyyy-mm-dd >vdocument identifier>明。621 Project目錄結構指導內容：關于該Project 一級目錄、二級目錄等基本目錄結構的約定。意義：為團隊并行開發(fā)提供必要基礎，讓不同程序小組看到自己應該負責的程序目錄。參考：不要把所有程序目錄的約定都定義得太細，否則這份架構文檔就要天天更新了。622 程序單元組織內容：源碼、程序庫、框架、目標碼等類型程序單元之間的編譯依賴關系。意義：或許有人認為這沒什么技術含量，但架構設計本來就不是只關心技術含量最高

19、問題 的。君不見，很多軟件工程師跳槽到新的企業(yè)之后，竟然連一個能正常編譯源碼的開發(fā)環(huán)境都 建不起來一一其實，他們“不知道Project所依賴的Library有哪些”是其中重要原因一一這本應在架構文檔中給出明確描述的。6.2.3 框架與應用之間的關系(可選)內容：框架(Framework )。意義：既然不適用 Framework的開發(fā)越來越少了，既然程序員犯的很多錯誤都和對Framework理解不到位有關，架構師就有責任明確說明Framework和待開發(fā)系統(tǒng)之間的關系。參考：下圖描述了 JGraph框架和待開發(fā)應用的關系。參考：下圖描述了Struts框架和待開發(fā)應用的關系。ADMEMS畋徑如Wi

20、fi H方住Page 15 of 17vProject NameVersio n:<1.0>Software Architecture Docume ntDate: < yyyy-mm-dd >vdocument identifier>戕用區(qū)1Struts框架區(qū)6.3 Project 2 內容：對Project劃分后的每個 Project進行目錄結構、程序單元組織、框架與應用關系的說 明。6.4 Project n 內容：對Project劃分后的每個 Project進行目錄結構、程序單元組織、框架與應用關系的說 明。7. 運行架構視圖關注點：此架構設計視圖的關注點

21、是控制流組織。注意：進程和線程是廣為人知的控制流實現(xiàn)技術，但在架構設計思維當中，對于系統(tǒng)軟件和 嵌入式軟件極為重要的中斷服務程序也是控制流，這樣利于架構師統(tǒng)一利用不同控制流手段設 計并行和并發(fā)。7.1 控制流組織內容：控制流有哪些，每條控制流各是何種形式（例如進程、線程、中斷服務程序），哪些 軟件單元是控制流的起點，整條控制流中分別調用了哪些軟件單元。意義：這是對系統(tǒng)運行時結構的刻畫，主要反映系統(tǒng)的動態(tài)結構。vProject NameVersio n:<1.0>Software Architecture Docume ntDate: < yyyy-mm-dd ><

22、document identifier>7.2 控制流的創(chuàng)建、銷毀、通信內容：描述進程、線程和中斷服務程序的創(chuàng)建和銷毀，以及多條控制流之間的通信關系的定 義。意義：一旦引入了多條控制流，附加工作就產(chǎn)生了一一此時控制流的創(chuàng)建和銷毀、以及控制 流之間的通信關系往往是必須考慮的。7.3 加鎖設計內容：系統(tǒng)中有多條控制流在同時運行的情況下，一個經(jīng)典問題是多于一條控制流可能會同 時修改某些數(shù)據(jù)結構，而造成數(shù)據(jù)的不一致。為此，架構師需要關注加鎖設計，合理引入臨界 區(qū)或同步機制。意義：加鎖設計事關系統(tǒng)的正確性。值得注意的是，忽略加鎖設計造成的問題往往以“不易 重現(xiàn)的Bug ”的形式出現(xiàn)，困惑的程序員會

23、對測試人員說，“你看你報的Bug在我機器上根本就不存在呀”。參考：對通用組件、通用模塊的設計而言，加鎖設計應予以專門關注，思維要點是研究未來 通用模塊的各種可能使用場景。8. 物理架構視圖關注點：此架構設計視圖的關注點是物理節(jié)點（Node ）分布，以及軟件到硬件的具體映射關系。注意：物理節(jié)點即可以是 PC機或服務器，也可以是單片機、單板機或專用機，從而物理架構 視圖既適用于描述企業(yè)信息系統(tǒng)，也適合于描述嵌入式軟件系統(tǒng)。8.1 物理拓撲內容：一為硬件選型，二為硬件之間的拓撲連接關系。意義：對于分布式系統(tǒng)的設計，此節(jié)極為重要、而且是必須的。參考：下圖是某企業(yè)級系統(tǒng)的物理拓撲圖。ADMEMSPage

24、 17 of 17蚊口農(nóng)雹IfiH方澆vProject NameVersio n:<1.0>Software Architecture Docume ntDate: < yyyy-mm-dd >vdocument identifier>上級廿理部門訪問層!(Tier)右PASSIH務器1A轂據(jù)昨服務器業(yè)務層1(Tier) 1I徽據(jù)層7(Tier)ADMEMSPage # of 17ADMEMSPage # of 17參考：下圖是某嵌入式系統(tǒng)的物理拓撲圖。ADMEMSPage # of 17ADMEMSPage # of 178.2 軟件到硬件的映射并說明具體的“映

25、射方內容：明確每個物理節(jié)點上有哪些（一到多個）軟件的目標單元, 式”是安裝、是部署、還是燒寫、抑或是下載。vProject NameVersio n:<1.0>Software Architecture Docume ntDate: < yyyy-mm-dd >vdocument identifier>軟件系統(tǒng)一一和上述硬件、硬件拓撲意義：如果把此節(jié)漏了，就無法表明本文檔的主題 的關系。參考：下圖所示為設備調試系統(tǒng)中，軟件到硬件的映射關系。ADMEMSPage 19 of 17ADMEMSPage # of 178.3 優(yōu)化部署內容：為達降低成本、提高性能和可靠性

26、等等目標，應特別關注的部署考慮。意義：物理架構設計的優(yōu)劣，造成的成本差異和質量差異，可能是天壤之別。所以必須重 視。參考：下圖展示的，是 ADMEMS方法重點推薦的“物理架構設計思維要點”，更多內容可參 考一線架構師實踐指南一書。*I/眾終目標經(jīng)濟性技術可行性易維護性f f f p投資與維護嚴a Ei |不合理1i -CI特定性能目標/性能持續(xù)可用性可伸縮性ii Jx1 f的滿足/1.L11通信開銷計算開銷思維裳點計算和通信開銷小 畫少計算和通信時內 77/S5WCPU/網(wǎng)絡沖突內存爭用硬盤爭用1CPU爭用數(shù)據(jù)爭申果構師設討內容節(jié)點選擇扮布楣撲軟件單元和籤據(jù)單 元的職責與分布増加Cached計

27、；網(wǎng)絡爭用I _ _數(shù)據(jù)單元物理節(jié)點思維層 結杲層一.I ;rl ;A9. 數(shù)據(jù)架構視圖關注點：此架構設計視圖的關注點是持久化。具體而言，場景化可以借助扁平文件、關系數(shù) 據(jù)庫、實時數(shù)據(jù)庫、Flash等方式中的一種或多種完成。vProject NameVersio n:<1.0>Software Architecture Docume ntDate: < yyyy-mm-dd >vdocument identifier>注意：本視圖單獨歸檔時，請在此節(jié)注明其文檔名稱等信息。9.1持久化機制的選擇內容：如下持久化機制的一種或多種：扁平文件、關系數(shù)據(jù)庫、實時數(shù)據(jù)庫、Flash。意義：不要假設在你的系統(tǒng)中，持久化只需一種機制；隨著如今的系統(tǒng)變得越來越復雜，我 們經(jīng)常需要綜合利用不同持久化機制。9.2 持久化存儲方案內容：持久化數(shù)據(jù)的格式定義。意義：統(tǒng)一定義表、文件格式、Flash數(shù)據(jù)結構等內容。9.3 數(shù)據(jù)同步與復制策略內容：由于數(shù)據(jù)分