《軟件架構(gòu)設(shè)計文檔》模板DOC

1、軟件架構(gòu)設(shè)計文檔模板DOC作者:日期:湎鴻1對曲崎®碗隔<Project Name>Software Architecture DocumentVersion <1.0>Revision HistoryDateVersionDescriptionAuthor< yyyy-mm-dd ><x.x><details><name>1 .文檔簡介41.1 文檔目的41.2 文檔范圍41.3 定義、縮寫詞和縮略語41.4 參考資料42 .架構(gòu)描述方式42.1 架構(gòu)視圖閱讀指南42.2 圖我與模型閱讀指南53 .架構(gòu)設(shè)計目標

2、53.1 關(guān)鍵功能53.2 關(guān)鍵質(zhì)量屬性53.3 業(yè)務(wù)需求和約束因素64 .架構(gòu)設(shè)計原則64.1 架構(gòu)設(shè)計原則64.2 備選架構(gòu)設(shè)計方案及被否原因64.3 架構(gòu)設(shè)計對后續(xù)工作的限制（詳設(shè)，部署等）65 .邏輯架構(gòu)視圖75.1 職賁劃分與職責(zé)確定75.2 接口設(shè)計與協(xié)作機制85.3 重要設(shè)計包106 .開發(fā)架構(gòu)視圖II6.1 Project 劃分116.2 Project 1116.2.1 Project目錄結(jié)構(gòu)指導(dǎo)126.2.2 程序單元組織126.2.3 架與應(yīng)用之間的關(guān)系（可選）126.3 Project 2 136.4 Project n137 .運行架構(gòu)視圖137.1 控制流組織137

3、.2 控制流的創(chuàng)建、銷毀、通信147.3 加鎖設(shè)計148 .物理架構(gòu)視圖148.1 物理拓撲148.2 軟件到硬件的映射158.3 優(yōu)化部署169.1 持久化機制的選擇9.2 持久化存儲方.案9.3 數(shù)據(jù)同步與復(fù)制策略1717171710.關(guān)鍵質(zhì)量屬性的設(shè)計原理1. 文檔簡介幫助讀者對本文檔建立基本印象，并為閱讀后續(xù)內(nèi)容掃清障礙。1.1 文檔目的文檔目的，非項目目的。否則造成同一項目多個文檔之間的內(nèi)容重復(fù)，不利于文檔維護。本小 日應(yīng)指明文檔針對的讀者對象，最好列出各種讀者角色，并說明每種讀者角色應(yīng)該重點閱讀的 章節(jié)。1.2 文檔范圍文檔的Scope,非項目的Scope。否則造成同一項目多個文檔

4、之間的內(nèi)容重復(fù)，不利于文檔維 護。1.3 定義、縮寫詞和縮略語集中列舉文檔中的定義、縮寫詞和縮略語。1.4 參考資料本項目經(jīng)審核的計劃書、合同、上級批文；本項目的其他已發(fā)表文件：本文檔引用的文件資料, 如軟件開發(fā)標準。具體而言，應(yīng)包括參考資料的題目（必須）、編號、版本號（必須）、發(fā)表 日期、發(fā)布方，必要時還可以說明如何使用這些資料。2. 架構(gòu)描述方式為了讓讀者更好地理解架構(gòu)文檔，在本節(jié)應(yīng)當說明文檔涉及的架構(gòu)視圖，并指明為了描述 設(shè)計決策用到了哪些圖表和模型。2.1 架構(gòu)視圖閱讀指南以多視圖的方式來組織架構(gòu)文檔是大勢所趨，推薦的是經(jīng)過優(yōu)化的5視圖方法，如下圖所 示。面向控制流面向節(jié)點面向?qū)ο?或

5、結(jié)構(gòu)化邏輯架構(gòu)運行架構(gòu)G 職責(zé)劃分職責(zé)間協(xié)作控制流組織發(fā)架程序單兀程序單兀組織數(shù)據(jù)架構(gòu)3面向Table或文件5f持久數(shù)據(jù)單元數(shù)據(jù)存儲格式物理節(jié)點2.2圖表與模型閱讀指南對后續(xù)文檔內(nèi)容中所用到的建模語言（例如UML）、表格（例如目標-場景-決策表）等進行說 明，3. 架構(gòu)設(shè)計目標功能、質(zhì)量、約束，一個都不能少。3.1 關(guān)鍵功能對架構(gòu)設(shè)計至關(guān)重要的功能，包括如下4類：核心功能、必做功能、高風(fēng)險功能、獨特功能0 所謂獨特功能，指這個功能覆蓋了上述3類功能沒有涉及到的職責(zé)。3.2 關(guān)鍵質(zhì)量屬性人之所以痛苦，很多時候是因為追求錯誤的東西。下圖是確定關(guān)鍵質(zhì)量的5大原則的整體思路 圖。1分類適合實踐4芍慮矛

6、盾關(guān)系3.3 業(yè)務(wù)需求和約束因素創(chuàng)造性地提出約束需求的4大類型，這是一種極為實用的分類方式。特別是業(yè)務(wù)需求對架構(gòu)設(shè) 汁而言是一種約束的觀點，解決了很多架構(gòu)師的現(xiàn)實困惑。下圖標明了 4類約束在“需求層次- 需求方面矩陣”中的位置，可以幫助我們理解產(chǎn)生約束需求的根源。廣能用戶級 需求業(yè)需求開發(fā)級 需求技術(shù)環(huán)境4. 架構(gòu)設(shè)計原則投標時經(jīng)常講“架構(gòu)設(shè)計原則”，但到了架構(gòu)文檔，這些著眼大局的考慮卻“丟了” 丁推 薦的本文檔模板，認為應(yīng)當把它們“找回來”。4.1 架構(gòu)設(shè)計原則著重描述重大的權(quán)衡取舍考慮。4.2 備選架構(gòu)設(shè)計方案及被否原因在概念架構(gòu)一級，對備選架構(gòu)設(shè)計方案進行描述，并闡述它們未被采用的原因C

7、這有利于團隊 了解當前架構(gòu)設(shè)計方案的來龍去脈，提高團隊對當前架構(gòu)設(shè)計方案的認可度。4.3 架構(gòu)設(shè)計對后續(xù)工作的限制（詳設(shè)，部署等）架構(gòu)設(shè)計不僅應(yīng)該包含“指導(dǎo)”，也應(yīng)該包含重要的“限制”。例如，一份只是說明“性能和 可擴展性都重要”的架構(gòu)文檔，實際上忽視了 “可擴展性和性能之間存在的矛盾關(guān)系” 0 此時，最有效的辦法就是在架構(gòu)文檔中明確說明“任何提升可擴展性的架構(gòu)設(shè)計和詳細設(shè) 計，都應(yīng)通過架構(gòu)團隊的評審才能引入，以確保性能目標不受重大影響”。5. 邏輯架構(gòu)視圖關(guān)注點：此架構(gòu)設(shè)計視圖的關(guān)注點是職責(zé)劃分。注意：邏輯架構(gòu)視圖無疑是最重要的，但同時也應(yīng)避免“架構(gòu)=模塊+接口”等以偏概全的 認識. 參考：

8、任何復(fù)雜系統(tǒng)的架構(gòu)設(shè)計都不是一蹴而就的，所以架構(gòu)師需要理性思維過程的指導(dǎo)。針 對邏輯架構(gòu)設(shè)計這個關(guān)鍵環(huán)行，一線架構(gòu)師實踐指南一書給出了 2條建議：一是“以質(zhì)疑 驅(qū)動的螺旋思維”，二是相對分離地考慮“結(jié)構(gòu)方面的切分”和“行為方面的定義”。下圖所 示即為推薦的邏輯架構(gòu)設(shè)計理性思維過程。5.1 職責(zé)劃分與職責(zé)確定內(nèi)容：將系統(tǒng)說分成更小的單元，并明確這些單元的職責(zé)。具體而言，職責(zé)單元可以是層、子 系統(tǒng)、模塊、關(guān)鍵類等。意義：一句話，職責(zé)劃分不合理，功能和質(zhì)量都會受到影響。也就是說，功能需求和質(zhì)量需求 無一不和職責(zé)劃分相關(guān)：一方而，每個功能都是由一條職責(zé)協(xié)作鏈完成的：另一方面，職責(zé)劃 分方式也影響著質(zhì)量

9、，于是需要職責(zé)模型針對特定質(zhì)量屬性要求做出相應(yīng)調(diào)整和優(yōu)化。很多人 認為架構(gòu)設(shè)計就是職責(zé)劃分的藝術(shù)，雖略顯片而，但足以表明職責(zé)劃分的重要性?！緟⒖迹夯趯I(yè)界大量案例的研究，梳理出了 “模塊劃分的3種必用手段”，如下圖所示，更 多內(nèi)容可參考一線架構(gòu)師實踐指南一書0 人的因素考慮決定性原則< 影響性原則5.2 接口設(shè)計與協(xié)作機制【內(nèi)容：本節(jié)描述接口的定義，以及協(xié)作的方式和規(guī)范。意義：恰恰是因為有了各模塊之間“未來合作的契約”，分頭開發(fā)各模塊才有了基本保證。參考：推薦利用“包-接口”圖，來識別接口 e下圖為一個“包-接口”圖的示例。Fa9ade命令描述進度展現(xiàn)回調(diào)接口援種接口壓縮控制層用布的控

10、制解JK的控制查看Jk縮包內(nèi)容的控有算法接口智能緩沖機制內(nèi)容懾沖達“額定仙1容ir對 相應(yīng)接口進行的調(diào)對超出額定full容境泊 內(nèi)容進行智能保存原文件讀”層壓縮包讀寫層壓縮實現(xiàn)層實睨基J-字符序列的JK縮、解出縮算法 生成不含元信息的壓縮結(jié)果接口壓縮包格式 分卷綾沖以字符流方式讀文件 生成文件饅沖參考：推薦使用序列圖，建議少用、甚至杜絕使用協(xié)作圖。下圖為一個序列圖的示例。5.3內(nèi)容：對重要子系統(tǒng)的設(shè)計進行“灰盒”級描述。意義：“每個子系統(tǒng)在架構(gòu)設(shè)計中都應(yīng)保持黑盒子”的觀點，過于理想化了。對于業(yè)務(wù)層、 用協(xié)作機制而言，經(jīng)常需要在架構(gòu)設(shè)計期間就引入“灰盒”級描述。參考：類圖和灰盒包圖，在本行中較多

11、出現(xiàn)。下圖為一灰盒包圖示例。6. 開發(fā)架構(gòu)視圖關(guān)注點：此架構(gòu)設(shè)計視圖的關(guān)注點是程序單元組織。【注意：此架構(gòu)設(shè)計視圖是必須的、不應(yīng)“剪裁”掉的。但實際情況卻是，很多架構(gòu)師不關(guān)注開 發(fā)架構(gòu)視圖，導(dǎo)致很多程序開發(fā)人員抱怨“架構(gòu)師就知道高興高去，架構(gòu)對編程工作沒什么指 導(dǎo)性”。6.1 Project 劃分內(nèi)容：本行說明整個系統(tǒng)將劃分成哪幾個Project來開發(fā)，其中，Project指開發(fā)環(huán)境所感知到 的“工程”.【意義：基本好處是，有利于開發(fā)的組織：而對一些大型的集成系統(tǒng)而言，由于同時涉及了 Web 應(yīng)用、桌面應(yīng)用、嵌入式應(yīng)用等軟件形態(tài)，所以此時Project劃分其實是不得不做的：最后，我 們推薦核心

12、代碼應(yīng)主動地切分到單獨的Project以進行獨立的軟件配置管理（SCM）,以降低 核心代碼外泄的風(fēng)險。參考：Project劃分必然是屬于“架構(gòu)設(shè)計”的工作，嚴格來講僅靠“需求分析”劃分的業(yè)務(wù)域 （Business Area）直接映射到Project經(jīng)常意味著工作內(nèi)容的遺漏。其實，業(yè)界不少有見地的 專家已經(jīng)認識到WBS （工作分解結(jié)構(gòu)）做得太早太草率危害很大，就與“Project劃分不到位” 不無關(guān)系。6.2 Project 1內(nèi)容：對Project劃分后的每個Project進行目錄結(jié)構(gòu)、程序單元組織、框架與應(yīng)用關(guān)系的說明。6.2.1 Project目錄結(jié)構(gòu)指導(dǎo)內(nèi)容：關(guān)于該Project一級目錄

13、、二級目錄等基本目錄結(jié)構(gòu)的約定。意義：為團隊單行開緩提供必要基礎(chǔ)，讓不同程序小組看到自己應(yīng)該貧責(zé)的程序目錄.參考：不要把所有程序目錄的約定都定義得太細，否則這份架構(gòu)文檔就要天莢更新了!6.2.2 程序單元組織內(nèi)容：源碼、程序庫、框架、目標碼等類型程序單元之間的編譯依賴關(guān)系。意義：或許有人認為這沒什么技術(shù)含量，但架構(gòu)設(shè)計本來就不是只關(guān)心技術(shù)含量最高問題的。 君不見，很多軟件工程師跳槽到新的企業(yè)之后，竟然連一個能正常編譯源碼的開發(fā)環(huán)境都建不 起來一一其實，他們“不知道Project所依賴的Library有哪些”是其中重要原因一一這本應(yīng)在 架構(gòu)文檔中給出明確描述的。6.2.3 框架與應(yīng)用之間的關(guān)系(

14、可選)內(nèi)容：框架(Framework) 0 【意義：既然不適用Framework的開發(fā)越來越少了，既然程序員犯的很多錯誤都和對Framework 理解不到位有關(guān)，架構(gòu)師就有責(zé)任明確說明Framework和待開發(fā)系統(tǒng)之間的關(guān)系. 參考：下圖描述了 JGraph框架和待開發(fā)應(yīng)用的關(guān)系0 參考：下圖描述了 Struts框架和待開發(fā)應(yīng)用的關(guān)系, 6.3 Project 2【內(nèi)容：對Project劃分后的每個Project進行目錄結(jié)構(gòu)、程序單元組織、框架與應(yīng)用關(guān)系的說明"6.4 Project n內(nèi)容：對Project劃分后的每個Project進行目錄結(jié)構(gòu)、程序單元組織、框架與應(yīng)用關(guān)系的說明&

15、quot;7. 運行架構(gòu)視圖關(guān)注點：此架構(gòu)設(shè)計視圖的關(guān)注點是控制流組織。注意：進程和線程是廣為人知的控制流實現(xiàn)技術(shù)，但在架構(gòu)設(shè)計思維當中，對于系統(tǒng)軟件和嵌 入式軟件極為重要的中斷服務(wù)程序也是控制流，這樣利于架構(gòu)師統(tǒng)一利用不同控制流手段設(shè)計 并行和并發(fā)。7.1 控制流組織內(nèi)容：控制流有哪些，每條控制流各是何種形式（例如進程、線程、中斷服務(wù)程序），哪些軟 件單元是控制流的起點，整條控制流中分別調(diào)用了哪些軟件單元?！疽饬x：這是對系統(tǒng)運行時結(jié)構(gòu)的刻畫，主要反映系統(tǒng)的動態(tài)結(jié)構(gòu)。7.2 控制流的創(chuàng)建、銷毀、通信內(nèi)容：描述進程、線程和中斷服務(wù)程序的創(chuàng)建和銷毀，以及多條控制流之間的通信關(guān)系的定義"意

16、義：一旦引入了多條控制流，附加工作就產(chǎn)生了一一此時控制流的創(chuàng)建和銷毀、以及控制流 之間的通信關(guān)系往往是必須考慮的。7.3 加鎖設(shè)計【內(nèi)容：系統(tǒng)中有多條控制流在同時運行的情況下，一個經(jīng)典問題是多于一條控制流可能會同時 修改某些數(shù)據(jù)結(jié)構(gòu)，而造成數(shù)據(jù)的不一致。為此，架構(gòu)師需要關(guān)注加鎖設(shè)計，合理引入臨界區(qū) 或同步機制，意義：加鎖設(shè)計事關(guān)系統(tǒng)的正確性。值得注意的是，忽略加鎖設(shè)計造成的問題往往以“不易重 現(xiàn)的Bug”的形式出現(xiàn)，困惑的程序員會對測試人員說，“你看你報的Bug在我機器上根本就 不存在呀"，8.8.1【參考：對通用組件、通用模塊的設(shè)計而言，加鎖設(shè)計應(yīng)予以專門關(guān)注，思維要點是研究未來通

17、 用模塊的各種可能使用場景。物理架構(gòu)視圖關(guān)注點：此架構(gòu)設(shè)計視圖的關(guān)注點是物理行點(Node)分布，以及軟件到硬件的具體映射關(guān) 系，注意：物理節(jié)點即可以是PC機或服務(wù)器，也可以是單片機、單板機或?qū)Ｓ脵C，從而物理架構(gòu) 視圖既適用于描述企業(yè)信息系統(tǒng)，也適合于描述嵌入式軟件系統(tǒng)。物理拓撲內(nèi)容：一為硬件選型，二為硬件之間的拓撲連接關(guān)系。意義：對于分布式系統(tǒng)的設(shè)計，此行極為重要、而且是必須的。參考：下圖是某嵌入式系統(tǒng)的物理拓撲圖。采集卡1.2 軟件到硬件的映射內(nèi)容：明確每個物理行點上有哪些（一到多個）軟件的目標單元，并說明具體的“映射方式” 是安裝、是部署、還是燒寫、抑或是下載。意義：如果把此節(jié)漏了，就無

18、法表明本文檔的主題一一軟件系統(tǒng)和上述硬件、硬件拓撲的 關(guān)系0 參考：下圖所示為設(shè)備調(diào)試系統(tǒng)中，軟件到硬件的映射關(guān)系。PC機RS232匚n桌面部分tsxtgui.exe1.3 優(yōu)化部署內(nèi)容：為達降低成本、提高性能和可靠性等等目標，應(yīng)特別關(guān)注的部署考慮。意義：物理架構(gòu)設(shè)計的優(yōu)劣，造成的成本差異和質(zhì)量差異，可能是天壤之別。所以必須重視。【參考：下圖展示的，是ADMEMS方法重點推薦的“物理架構(gòu)設(shè)計思維要點”，更多內(nèi)容可參 考一線架構(gòu)師實踐指南一書。最終目標投資與維護成 本合理特定性能目標 的滿足持續(xù)可用性經(jīng)濟性架樹思維思維要點計算和通信開銷小源少計算和通信時 內(nèi)存/硬盤/CPU/ 朗絡(luò)沖突通信開銷網(wǎng)

19、絡(luò)爭用架構(gòu)師設(shè)計內(nèi)容節(jié)點選擇/分布施撲軟件單元和數(shù)據(jù)單 元的職責(zé)與分布增加cacne等設(shè)計技術(shù)可行性易維護性可伸縮性計算開銷內(nèi)存爭用旭盤爭用CPU爭用I數(shù)據(jù)爭用軟件單元數(shù)據(jù)單元物理節(jié)點目標層一 思維層結(jié)果層9. 數(shù)據(jù)架構(gòu)視圖關(guān)注點：此架構(gòu)設(shè)計視圖的關(guān)注點是持久化。具體而言，場景化可以借助扁平文件、關(guān)系數(shù)據(jù) 庫、實時數(shù)據(jù)庫、Flash等方式中的一種或多種完成。注意：本視圖單獨歸檔時，請在此行注明其文檔名稱等信息。9.1 持久化機制的選擇內(nèi)容：如下持久化機制的一種或多種：扁平文件、關(guān)系數(shù)據(jù)庫、實時數(shù)據(jù)庫、Flash0 意義：不要假設(shè)在你的系統(tǒng)中，持久化只需一種機制：隨著如今的系統(tǒng)變得越來越復(fù)雜，我們 經(jīng)常需要綜合利用不同持久化機制。9.2 持久化存儲方案內(nèi)容：持久化數(shù)據(jù)的格式定義。意義：統(tǒng)一定義表、文件格式、Flash數(shù)據(jù)結(jié)構(gòu)等內(nèi)容。9.3 數(shù)據(jù)同步與復(fù)制策略內(nèi)容：由于數(shù)據(jù)分布所引起的，包含數(shù)據(jù)分布、同步、復(fù)制等內(nèi)容的重要設(shè)計決策。意義：在數(shù)據(jù)分布的情況下，此節(jié)為必須。