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

《軟件架構(gòu)設(shè)計(jì)文檔》模板《軟件架構(gòu)設(shè)計(jì)文檔》模板《軟件架構(gòu)設(shè)計(jì)文檔》模板《軟件架構(gòu)設(shè)計(jì)文檔》模板編制僅供參考審核批準(zhǔn)生效日期地址：電話：傳真:郵編:目錄TOC\o"1-3"1. 文檔簡(jiǎn)介 4 文檔目的 4 文檔范圍 4 定義、縮寫詞和縮略語 4 參考資料 42. 架構(gòu)描述方式 4 架構(gòu)視圖閱讀指南 4 圖表與模型閱讀指南 53. 架構(gòu)設(shè)計(jì)目標(biāo) 5 關(guān)鍵功能 5 關(guān)鍵質(zhì)量屬性 5 業(yè)務(wù)需求和約束因素 64. 架構(gòu)設(shè)計(jì)原則 6 架構(gòu)設(shè)計(jì)原則 6 備選架構(gòu)設(shè)計(jì)方案及被否原因 6 架構(gòu)設(shè)計(jì)對(duì)后續(xù)工作的限制（詳設(shè)，部署等） 65. 邏輯架構(gòu)視圖 7 職責(zé)劃分與職責(zé)確定 7 接口設(shè)計(jì)與協(xié)作機(jī)制 8 重要設(shè)計(jì)包 106. 開發(fā)架構(gòu)視圖 11 Project劃分 11 Project1 11 Project目錄結(jié)構(gòu)指導(dǎo) 12 程序單元組織 12 框架與應(yīng)用之間的關(guān)系（可選） 12 Project2…… 13 Projectn…… 137. 運(yùn)行架構(gòu)視圖 13 控制流組織 13 控制流的創(chuàng)建、銷毀、通信 14 加鎖設(shè)計(jì) 148. 物理架構(gòu)視圖 14 物理拓?fù)?14 軟件到硬件的映射 15 優(yōu)化部署 169. 數(shù)據(jù)架構(gòu)視圖 16 持久化機(jī)制的選擇 17 持久化存儲(chǔ)方案 17 數(shù)據(jù)同步與復(fù)制策略 1710. 關(guān)鍵質(zhì)量屬性的設(shè)計(jì)原理 17

文檔簡(jiǎn)介[幫助讀者對(duì)本文檔建立基本印象，并為閱讀后續(xù)內(nèi)容掃清障礙。]文檔目的[文檔目的，非項(xiàng)目目的。否則造成同一項(xiàng)目多個(gè)文檔之間的內(nèi)容重復(fù)，不利于文檔維護(hù)。本小節(jié)應(yīng)指明文檔針對(duì)的讀者對(duì)象，最好列出各種讀者角色，并說明每種讀者角色應(yīng)該重點(diǎn)閱讀的章節(jié)。]文檔范圍[文檔的Scope，非項(xiàng)目的Scope。否則造成同一項(xiàng)目多個(gè)文檔之間的內(nèi)容重復(fù)，不利于文檔維護(hù)。]定義、縮寫詞和縮略語[集中列舉文檔中的定義、縮寫詞和縮略語。]參考資料[本項(xiàng)目經(jīng)審核的計(jì)劃書、合同、上級(jí)批文；本項(xiàng)目的其他已發(fā)表文件；本文檔引用的文件資料，如軟件開發(fā)標(biāo)準(zhǔn)。具體而言，應(yīng)包括參考資料的題目（必須）、編號(hào)、版本號(hào)（必須）、發(fā)表日期、發(fā)布方，必要時(shí)還可以說明如何使用這些資料。]架構(gòu)描述方式[為了讓讀者更好地理解《架構(gòu)文檔》，在本節(jié)應(yīng)當(dāng)說明文檔涉及的架構(gòu)視圖，并指明為了描述設(shè)計(jì)決策用到了哪些圖表和模型。]架構(gòu)視圖閱讀指南[以多視圖的方式來組織《架構(gòu)文檔》是大勢(shì)所趨。ADMEMS推薦的是經(jīng)過優(yōu)化的5視圖方法，如下圖所示。]圖表與模型閱讀指南[對(duì)后續(xù)文檔內(nèi)容中所用到的建模語言（例如UML）、表格（例如目標(biāo)-場(chǎng)景-決策表）等進(jìn)行說明。]架構(gòu)設(shè)計(jì)目標(biāo)[功能、質(zhì)量、約束，一個(gè)都不能少。]關(guān)鍵功能[對(duì)架構(gòu)設(shè)計(jì)至關(guān)重要的功能，包括如下4類：核心功能、必做功能、高風(fēng)險(xiǎn)功能、獨(dú)特功能。所謂獨(dú)特功能，指這個(gè)功能覆蓋了上述3類功能沒有涉及到的職責(zé)。]關(guān)鍵質(zhì)量屬性[人之所以痛苦，很多時(shí)候是因?yàn)樽非箦e(cuò)誤的東西。下圖是ADMEMS方法確定關(guān)鍵質(zhì)量的5大原則的整體思路圖。]業(yè)務(wù)需求和約束因素[ADMEMS方法創(chuàng)造性地提出約束需求的4大類型，這是一種極為實(shí)用的分類方式。特別是業(yè)務(wù)需求對(duì)架構(gòu)設(shè)計(jì)而言是一種約束的觀點(diǎn)，解決了很多架構(gòu)師的現(xiàn)實(shí)困惑。下圖標(biāo)明了4類約束在“需求層次-需求方面矩陣（又稱ADMEMS矩陣）”中的位置，可以幫助我們理解產(chǎn)生約束需求的根源。]架構(gòu)設(shè)計(jì)原則[投標(biāo)時(shí)經(jīng)常講“架構(gòu)設(shè)計(jì)原則”，但到了《架構(gòu)文檔》，這些著眼大局的考慮卻“丟了”。ADMEMS方法推薦的本文檔模板，認(rèn)為應(yīng)當(dāng)把它們“找回來”。]架構(gòu)設(shè)計(jì)原則[著重描述重大的權(quán)衡取舍考慮。]備選架構(gòu)設(shè)計(jì)方案及被否原因[在概念架構(gòu)一級(jí)，對(duì)備選架構(gòu)設(shè)計(jì)方案進(jìn)行描述，并闡述它們未被采用的原因。這有利于團(tuán)隊(duì)了解當(dāng)前架構(gòu)設(shè)計(jì)方案的來龍去脈，提高團(tuán)隊(duì)對(duì)當(dāng)前架構(gòu)設(shè)計(jì)方案的認(rèn)可度。]架構(gòu)設(shè)計(jì)對(duì)后續(xù)工作的限制（詳設(shè)，部署等）[架構(gòu)設(shè)計(jì)不僅應(yīng)該包含“指導(dǎo)”，也應(yīng)該包含重要的“限制”。例如，一份只是說明“性能和可擴(kuò)展性都重要”的《架構(gòu)文檔》，實(shí)際上忽視了“可擴(kuò)展性和性能之間存在的矛盾關(guān)系”。此時(shí)，最有效的辦法就是在《架構(gòu)文檔》中明確說明“任何提升可擴(kuò)展性的架構(gòu)設(shè)計(jì)和詳細(xì)設(shè)計(jì)，都應(yīng)通過架構(gòu)團(tuán)隊(duì)的評(píng)審才能引入，以確保性能目標(biāo)不受重大影響”。]邏輯架構(gòu)視圖[關(guān)注點(diǎn)：此架構(gòu)設(shè)計(jì)視圖的關(guān)注點(diǎn)是職責(zé)劃分。][注意：邏輯架構(gòu)視圖無疑是最重要的，但同時(shí)也應(yīng)避免“架構(gòu)=模塊+接口”等以偏概全的認(rèn)識(shí)。][參考：任何復(fù)雜系統(tǒng)的架構(gòu)設(shè)計(jì)都不是一蹴而就的，所以架構(gòu)師需要理性思維過程的指導(dǎo)。針對(duì)邏輯架構(gòu)設(shè)計(jì)這個(gè)關(guān)鍵環(huán)節(jié)，《一線架構(gòu)師實(shí)踐指南》一書給出了2條建議：一是“以質(zhì)疑驅(qū)動(dòng)的螺旋思維”，二是相對(duì)分離地考慮“結(jié)構(gòu)方面的切分”和“行為方面的定義”。下圖所示即為ADMEMS方法推薦的邏輯架構(gòu)設(shè)計(jì)理性思維過程。]職責(zé)劃分與職責(zé)確定[內(nèi)容：將系統(tǒng)切分成更小的單元，并明確這些單元的職責(zé)。具體而言，職責(zé)單元可以是層、子系統(tǒng)、模塊、關(guān)鍵類等。][意義：一句話，職責(zé)劃分不合理，功能和質(zhì)量都會(huì)受到影響。也就是說，功能需求和質(zhì)量需求無一不和職責(zé)劃分相關(guān)：一方面，每個(gè)功能都是由一條職責(zé)協(xié)作鏈完成的；另一方面，職責(zé)劃分方式也影響著質(zhì)量，于是需要職責(zé)模型針對(duì)特定質(zhì)量屬性要求做出相應(yīng)調(diào)整和優(yōu)化。很多人認(rèn)為架構(gòu)設(shè)計(jì)就是職責(zé)劃分的藝術(shù)，雖略顯片面，但足以表明職責(zé)劃分的重要性。][參考：基于對(duì)業(yè)界大量案例的研究，ADMEMS方法梳理出了“模塊劃分的3種必用手段”，如下圖所示，更多內(nèi)容可參考《一線架構(gòu)師實(shí)踐指南》一書。]接口設(shè)計(jì)與協(xié)作機(jī)制[內(nèi)容：本節(jié)描述接口的定義，以及協(xié)作的方式和規(guī)范。][意義：恰恰是因?yàn)橛辛烁髂K之間“未來合作的契約”，分頭開發(fā)各模塊才有了基本保證。][參考：ADMEMS方法推薦利用“包-接口”圖，來識(shí)別接口。下圖為一個(gè)“包-接口”圖的示例。][參考：ADMEMS方法推薦使用序列圖，建議少用、甚至杜絕使用協(xié)作圖。下圖為一個(gè)序列圖的示例。]重要設(shè)計(jì)包[內(nèi)容：對(duì)重要子系統(tǒng)的設(shè)計(jì)進(jìn)行“灰盒”級(jí)描述。][意義：“每個(gè)子系統(tǒng)在架構(gòu)設(shè)計(jì)中都應(yīng)保持黑盒子”的觀點(diǎn)，過于理想化了。對(duì)于業(yè)務(wù)層、通用協(xié)作機(jī)制而言，經(jīng)常需要在架構(gòu)設(shè)計(jì)期間就引入“灰盒”級(jí)描述。][參考：類圖和灰盒包圖，在本節(jié)中較多出現(xiàn)。下圖為一灰盒包圖示例。]開發(fā)架構(gòu)視圖[關(guān)注點(diǎn)：此架構(gòu)設(shè)計(jì)視圖的關(guān)注點(diǎn)是程序單元組織。][注意：此架構(gòu)設(shè)計(jì)視圖是必須的、不應(yīng)“剪裁”掉的。但實(shí)際情況卻是，很多架構(gòu)師不關(guān)注開發(fā)架構(gòu)視圖，導(dǎo)致很多程序開發(fā)人員抱怨“架構(gòu)師就知道高來高去，架構(gòu)對(duì)編程工作沒什么指導(dǎo)性”。]Project劃分[內(nèi)容：本節(jié)說明整個(gè)系統(tǒng)將劃分成哪幾個(gè)Project來開發(fā)，其中，Project指開發(fā)環(huán)境所感知到的“工程”。][意義：基本好處是，有利于開發(fā)的組織；而對(duì)一些大型的集成系統(tǒng)而言，由于同時(shí)涉及了Web應(yīng)用、桌面應(yīng)用、嵌入式應(yīng)用等軟件形態(tài)，所以此時(shí)Project劃分其實(shí)是不得不做的；最后，我們推薦核心代碼應(yīng)主動(dòng)地切分到單獨(dú)的Project以進(jìn)行獨(dú)立的軟件配置管理（SCM），以降低核心代碼外泄的風(fēng)險(xiǎn)。][參考：Project劃分必然是屬于“架構(gòu)設(shè)計(jì)”的工作，嚴(yán)格來講僅靠“需求分析”劃分的業(yè)務(wù)域（BusinessArea）直接映射到Project經(jīng)常意味著工作內(nèi)容的遺漏。其實(shí)，業(yè)界不少有見地的專家已經(jīng)認(rèn)識(shí)到WBS（工作分解結(jié)構(gòu)）做得太早太草率危害很大，就與“Project劃分不到位”不無關(guān)系。]Project1[內(nèi)容：對(duì)Project劃分后的每個(gè)Project進(jìn)行目錄結(jié)構(gòu)、程序單元組織、框架與應(yīng)用關(guān)系的說明。]Project目錄結(jié)構(gòu)指導(dǎo)[內(nèi)容：關(guān)于該P(yáng)roject一級(jí)目錄、二級(jí)目錄等基本目錄結(jié)構(gòu)的約定。][意義：為團(tuán)隊(duì)并行開發(fā)提供必要基礎(chǔ)，讓不同程序小組看到自己應(yīng)該負(fù)責(zé)的程序目錄。][參考：不要把所有程序目錄的約定都定義得太細(xì)，否則這份《架構(gòu)文檔》就要天天更新了。]程序單元組織[內(nèi)容：源碼、程序庫、框架、目標(biāo)碼等類型程序單元之間的編譯依賴關(guān)系。][意義：或許有人認(rèn)為這沒什么技術(shù)含量，但架構(gòu)設(shè)計(jì)本來就不是只關(guān)心技術(shù)含量最高問題的。君不見，很多軟件工程師跳槽到新的企業(yè)之后，竟然連一個(gè)能正常編譯源碼的開發(fā)環(huán)境都建不起來——其實(shí)，他們“不知道Project所依賴的Library有哪些”是其中重要原因——這本應(yīng)在《架構(gòu)文檔》中給出明確描述的。]框架與應(yīng)用之間的關(guān)系（可選）[內(nèi)容：框架（Framework）。][意義：既然不適用Framework的開發(fā)越來越少了，既然程序員犯的很多錯(cuò)誤都和對(duì)Framework理解不到位有關(guān)，架構(gòu)師就有責(zé)任明確說明Framework和待開發(fā)系統(tǒng)之間的關(guān)系。][參考：下圖描述了JGraph框架和待開發(fā)應(yīng)用的關(guān)系。][參考：下圖描述了Struts框架和待開發(fā)應(yīng)用的關(guān)系。]Project2……[內(nèi)容：對(duì)Project劃分后的每個(gè)Project進(jìn)行目錄結(jié)構(gòu)、程序單元組織、框架與應(yīng)用關(guān)系的說明。]Projectn……[內(nèi)容：對(duì)Project劃分后的每個(gè)Project進(jìn)行目錄結(jié)構(gòu)、程序單元組織、框架與應(yīng)用關(guān)系的說明。]運(yùn)行架構(gòu)視圖[關(guān)注點(diǎn)：此架構(gòu)設(shè)計(jì)視圖的關(guān)注點(diǎn)是控制流組織。][注意：進(jìn)程和線程是廣為人知的控制流實(shí)現(xiàn)技術(shù)，但在架構(gòu)設(shè)計(jì)思維當(dāng)中，對(duì)于系統(tǒng)軟件和嵌入式軟件極為重要的中斷服務(wù)程序也是控制流，這樣利于架構(gòu)師統(tǒng)一利用不同控制流手段設(shè)計(jì)并行和并發(fā)。]控制流組織[內(nèi)容：控制流有哪些，每條控制流各是何種形式（例如進(jìn)程、線程、中斷服務(wù)程序），哪些軟件單元是控制流的起點(diǎn)，整條控制流中分別調(diào)用了哪些軟件單元。][意義：這是對(duì)系統(tǒng)運(yùn)行時(shí)結(jié)構(gòu)的刻畫，主要反映系統(tǒng)的動(dòng)態(tài)結(jié)構(gòu)。]控制流的創(chuàng)建、銷毀、通信[內(nèi)容：描述進(jìn)程、線程和中斷服務(wù)程序的創(chuàng)建和銷毀，以及多條控制流之間的通信關(guān)系的定義。][意義：一旦引入了多條控制流，附加工作就產(chǎn)生了——此時(shí)控制流的創(chuàng)建和銷毀、以及控制流之間的通信關(guān)系往往是必須考慮的。]加鎖設(shè)計(jì)[內(nèi)容：系統(tǒng)中有多條控制流在同時(shí)運(yùn)行的情況下，一個(gè)經(jīng)典問題是多于一條控制流可能會(huì)同時(shí)修改某些數(shù)據(jù)結(jié)構(gòu)，而造成數(shù)據(jù)的不一致。為此，架構(gòu)師需要關(guān)注加鎖設(shè)計(jì)，合理引入臨界區(qū)或同步機(jī)制。][意義：加鎖設(shè)計(jì)事關(guān)系統(tǒng)的正確性。值得注意的是，忽略加鎖設(shè)計(jì)造成的問題往往以“不易重現(xiàn)的Bug”的形式出現(xiàn)，困惑的程序員會(huì)對(duì)測(cè)試人員說，“你看你報(bào)的Bug在我機(jī)器上根本就不存在呀”。][參考：對(duì)通用組件、通用模塊的設(shè)計(jì)而言，加鎖設(shè)計(jì)應(yīng)予以專門關(guān)注，思維要點(diǎn)是研究未來通用模塊的各種可能使用場(chǎng)景。]物理架構(gòu)視圖[關(guān)注點(diǎn)：此架構(gòu)設(shè)計(jì)視圖的關(guān)注點(diǎn)是物理節(jié)點(diǎn)（Node）分布，以及軟件到硬件的具體映射關(guān)系。][注意：物理節(jié)點(diǎn)即可以是PC機(jī)或服務(wù)器，也可以是單片機(jī)、單板機(jī)或?qū)Ｓ脵C(jī)，從而物理架構(gòu)視圖既適用于描述企業(yè)信息系統(tǒng)，也適合于描述嵌入式軟件系統(tǒng)。]物理拓?fù)鋄內(nèi)容：一為硬件選型，二為硬件之間的拓?fù)溥B接關(guān)系。][意義：對(duì)于分布式系統(tǒng)的設(shè)計(jì)，此節(jié)極為重要、而且是必須的。][參考：下圖是某企業(yè)級(jí)系統(tǒng)的物理拓?fù)鋱D。][參考：下圖是某嵌入式系統(tǒng)的物理拓?fù)鋱D。]軟件到硬件的映射[內(nèi)容：明確每個(gè)物理節(jié)點(diǎn)上有哪些（一到多個(gè)）軟件的目標(biāo)單元，并說明具體的“映射方式”是安裝、是部署、還是燒寫、抑或是下載。][意義：如果把此節(jié)漏了，就無法表明本文檔的主題——軟件系統(tǒng)——和上述硬件、硬件拓?fù)涞年P(guān)系。][參考：下圖所示為設(shè)備調(diào)試系統(tǒng)中，軟件到硬件的映射關(guān)系。]優(yōu)化部署[內(nèi)容：為達(dá)降低成本、提高性能和可靠性等等目標(biāo)，應(yīng)特別關(guān)注的部署考慮。][意義：物理架構(gòu)設(shè)計(jì)的優(yōu)劣，造成的成本差異和質(zhì)量差異，可能是天壤之別。所以必須重視。][參考：下圖展示的，是ADMEMS方法重點(diǎn)推薦的“物理架構(gòu)設(shè)計(jì)思維要點(diǎn)”，更多內(nèi)容可參考《一線架構(gòu)師實(shí)踐指南》一書。]數(shù)據(jù)架構(gòu)視圖[關(guān)注點(diǎn)：此架構(gòu)設(shè)計(jì)視圖的關(guān)注點(diǎn)是持久化。具體而言，場(chǎng)景