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

Software Architecture DocumentVersion Revision HistoryDateVersionDescriptionAuthor歡迎下載目 錄1.文檔簡(jiǎn)介41.1文檔目的41.2文檔范圍41.3定義、縮寫(xiě)詞和縮略語(yǔ)41.4參考資料42.架構(gòu)描述方式42.1架構(gòu)視圖閱讀指南42.2圖表與模型閱讀指南53.架構(gòu)設(shè)計(jì)目標(biāo)53.1關(guān)鍵功能53.2關(guān)鍵質(zhì)量屬性53.3業(yè)務(wù)需求和約束因素64.架構(gòu)設(shè)計(jì)原則64.1架構(gòu)設(shè)計(jì)原則64.2備選架構(gòu)設(shè)計(jì)方案及被否原因64.3架構(gòu)設(shè)計(jì)對(duì)后續(xù)工作的限制（詳設(shè)，部署等）65.邏輯架構(gòu)視圖75.1職責(zé)劃分與職責(zé)確定75.2接口設(shè)計(jì)與協(xié)作機(jī)制85.3重要設(shè)計(jì)包106.開(kāi)發(fā)架構(gòu)視圖116.1Project劃分116.2Project 1116.2.1Project目錄結(jié)構(gòu)指導(dǎo)126.2.2程序單元組織126.2.3框架與應(yīng)用之間的關(guān)系（可選）126.3Project 2136.4Project n137.運(yùn)行架構(gòu)視圖137.1控制流組織137.2控制流的創(chuàng)建、銷(xiāo)毀、通信147.3加鎖設(shè)計(jì)148.物理架構(gòu)視圖148.1物理拓?fù)?48.2軟件到硬件的映射158.3優(yōu)化部署169.數(shù)據(jù)架構(gòu)視圖169.1持久化機(jī)制的選擇179.2持久化存儲(chǔ)方案179.3數(shù)據(jù)同步與復(fù)制策略1710.關(guān)鍵質(zhì)量屬性的設(shè)計(jì)原理17 1. 文檔簡(jiǎn)介幫助讀者對(duì)本文檔建立基本印象，并為閱讀后續(xù)內(nèi)容掃清障礙。1.1 文檔目的文檔目的，非項(xiàng)目目的。否則造成同一項(xiàng)目多個(gè)文檔之間的內(nèi)容重復(fù)，不利于文檔維護(hù)。本小節(jié)應(yīng)指明文檔針對(duì)的讀者對(duì)象，最好列出各種讀者角色，并說(shuō)明每種讀者角色應(yīng)該重點(diǎn)閱讀的章節(jié)。1.2 文檔范圍文檔的Scope，非項(xiàng)目的Scope。否則造成同一項(xiàng)目多個(gè)文檔之間的內(nèi)容重復(fù)，不利于文檔維護(hù)。1.3 定義、縮寫(xiě)詞和縮略語(yǔ)集中列舉文檔中的定義、縮寫(xiě)詞和縮略語(yǔ)。1.4 參考資料本項(xiàng)目經(jīng)審核的計(jì)劃書(shū)、合同、上級(jí)批文；本項(xiàng)目的其他已發(fā)表文件；本文檔引用的文件資料，如軟件開(kāi)發(fā)標(biāo)準(zhǔn)。具體而言，應(yīng)包括參考資料的題目（必須）、編號(hào)、版本號(hào)（必須）、發(fā)表日期、發(fā)布方，必要時(shí)還可以說(shuō)明如何使用這些資料。2. 架構(gòu)描述方式 為了讓讀者更好地理解架構(gòu)文檔，在本節(jié)應(yīng)當(dāng)說(shuō)明文檔涉及的架構(gòu)視圖，并指明為了描述設(shè)計(jì)決策用到了哪些圖表和模型。2.1 架構(gòu)視圖閱讀指南以多視圖的方式來(lái)組織架構(gòu)文檔是大勢(shì)所趨。推薦的是經(jīng)過(guò)優(yōu)化的5視圖方法，如下圖所示。2.2 圖表與模型閱讀指南對(duì)后續(xù)文檔內(nèi)容中所用到的建模語(yǔ)言（例如UML）、表格（例如目標(biāo)-場(chǎng)景-決策表）等進(jìn)行說(shuō)明。3. 架構(gòu)設(shè)計(jì)目標(biāo)功能、質(zhì)量、約束，一個(gè)都不能少。3.1 關(guān)鍵功能對(duì)架構(gòu)設(shè)計(jì)至關(guān)重要的功能，包括如下4類(lèi)：核心功能、必做功能、高風(fēng)險(xiǎn)功能、獨(dú)特功能。所謂獨(dú)特功能，指這個(gè)功能覆蓋了上述3類(lèi)功能沒(méi)有涉及到的職責(zé)。3.2 關(guān)鍵質(zhì)量屬性人之所以痛苦，很多時(shí)候是因?yàn)樽非箦e(cuò)誤的東西。下圖是確定關(guān)鍵質(zhì)量的5大原則的整體思路圖。3.3 業(yè)務(wù)需求和約束因素創(chuàng)造性地提出約束需求的4大類(lèi)型，這是一種極為實(shí)用的分類(lèi)方式。特別是業(yè)務(wù)需求對(duì)架構(gòu)設(shè)計(jì)而言是一種約束的觀點(diǎn)，解決了很多架構(gòu)師的現(xiàn)實(shí)困惑。下圖標(biāo)明了4類(lèi)約束在“需求層次-需求方面矩陣”中的位置，可以幫助我們理解產(chǎn)生約束需求的根源。4. 架構(gòu)設(shè)計(jì)原則投標(biāo)時(shí)經(jīng)常講“架構(gòu)設(shè)計(jì)原則”，但到了架構(gòu)文檔，這些著眼大局的考慮卻“丟了”。推薦的本文檔模板，認(rèn)為應(yīng)當(dāng)把它們“找回來(lái)”。4.1 架構(gòu)設(shè)計(jì)原則著重描述重大的權(quán)衡取舍考慮。4.2 備選架構(gòu)設(shè)計(jì)方案及被否原因在概念架構(gòu)一級(jí)，對(duì)備選架構(gòu)設(shè)計(jì)方案進(jìn)行描述，并闡述它們未被采用的原因。這有利于團(tuán)隊(duì)了解當(dāng)前架構(gòu)設(shè)計(jì)方案的來(lái)龍去脈，提高團(tuán)隊(duì)對(duì)當(dāng)前架構(gòu)設(shè)計(jì)方案的認(rèn)可度。4.3 架構(gòu)設(shè)計(jì)對(duì)后續(xù)工作的限制（詳設(shè)，部署等）架構(gòu)設(shè)計(jì)不僅應(yīng)該包含“指導(dǎo)”，也應(yīng)該包含重要的“限制”。例如，一份只是說(shuō)明“性能和可擴(kuò)展性都重要”的架構(gòu)文檔，實(shí)際上忽視了“可擴(kuò)展性和性能之間存在的矛盾關(guān)系”。此時(shí)，最有效的辦法就是在架構(gòu)文檔中明確說(shuō)明“任何提升可擴(kuò)展性的架構(gòu)設(shè)計(jì)和詳細(xì)設(shè)計(jì)，都應(yīng)通過(guò)架構(gòu)團(tuán)隊(duì)的評(píng)審才能引入，以確保性能目標(biāo)不受重大影響”。5. 邏輯架構(gòu)視圖 關(guān)注點(diǎn)：此架構(gòu)設(shè)計(jì)視圖的關(guān)注點(diǎn)是職責(zé)劃分。注意：邏輯架構(gòu)視圖無(wú)疑是最重要的，但同時(shí)也應(yīng)避免“架構(gòu) = 模塊 + 接口”等以偏概全的認(rèn)識(shí)。參考：任何復(fù)雜系統(tǒng)的架構(gòu)設(shè)計(jì)都不是一蹴而就的，所以架構(gòu)師需要理性思維過(guò)程的指導(dǎo)。針對(duì)邏輯架構(gòu)設(shè)計(jì)這個(gè)關(guān)鍵環(huán)節(jié)，一線架構(gòu)師實(shí)踐指南一書(shū)給出了2條建議：一是“以質(zhì)疑驅(qū)動(dòng)的螺旋思維”，二是相對(duì)分離地考慮“結(jié)構(gòu)方面的切分”和“行為方面的定義”。下圖所示即為推薦的邏輯架構(gòu)設(shè)計(jì)理性思維過(guò)程。 5.1 職責(zé)劃分與職責(zé)確定內(nèi)容：將系統(tǒng)切分成更小的單元，并明確這些單元的職責(zé)。具體而言，職責(zé)單元可以是層、子系統(tǒng)、模塊、關(guān)鍵類(lèi)等。意義：一句話，職責(zé)劃分不合理，功能和質(zhì)量都會(huì)受到影響。也就是說(shuō)，功能需求和質(zhì)量需求無(wú)一不和職責(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è)界大量案例的研究，梳理出了“模塊劃分的3種必用手段”，如下圖所示，更多內(nèi)容可參考一線架構(gòu)師實(shí)踐指南一書(shū)。 5.2 接口設(shè)計(jì)與協(xié)作機(jī)制內(nèi)容：本節(jié)描述接口的定義，以及協(xié)作的方式和規(guī)范。意義：恰恰是因?yàn)橛辛烁髂K之間“未來(lái)合作的契約”，分頭開(kāi)發(fā)各模塊才有了基本保證。參考：推薦利用“包-接口”圖，來(lái)識(shí)別接口。下圖為一個(gè)“包-接口”圖的示例。 參考：推薦使用序列圖，建議少用、甚至杜絕使用協(xié)作圖。下圖為一個(gè)序列圖的示例。 5.3 重要設(shè)計(jì)包內(nèi)容：對(duì)重要子系統(tǒng)的設(shè)計(jì)進(jìn)行“灰盒”級(jí)描述。意義：“每個(gè)子系統(tǒng)在架構(gòu)設(shè)計(jì)中都應(yīng)保持黑盒子”的觀點(diǎn)，過(guò)于理想化了。對(duì)于業(yè)務(wù)層、通用協(xié)作機(jī)制而言，經(jīng)常需要在架構(gòu)設(shè)計(jì)期間就引入“灰盒”級(jí)描述。參考：類(lèi)圖和灰盒包圖，在本節(jié)中較多出現(xiàn)。下圖為一灰盒包圖示例。 6. 開(kāi)發(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)注開(kāi)發(fā)架構(gòu)視圖，導(dǎo)致很多程序開(kāi)發(fā)人員抱怨“架構(gòu)師就知道高來(lái)高去，架構(gòu)對(duì)編程工作沒(méi)什么指導(dǎo)性”。6.1 Project劃分內(nèi)容：本節(jié)說(shuō)明整個(gè)系統(tǒng)將劃分成哪幾個(gè)Project來(lái)開(kāi)發(fā)，其中，Project指開(kāi)發(fā)環(huán)境所感知到的“工程”。意義：基本好處是，有利于開(kāi)發(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)格來(lái)講僅靠“需求分析”劃分的業(yè)務(wù)域（Business Area）直接映射到Project經(jīng)常意味著工作內(nèi)容的遺漏。其實(shí)，業(yè)界不少有見(jiàn)地的專(zhuān)家已經(jīng)認(rèn)識(shí)到WBS（工作分解結(jié)構(gòu)）做得太早太草率危害很大，就與“Project劃分不到位”不無(wú)關(guān)系。 6.2 Project 1內(nèi)容：對(duì)Project劃分后的每個(gè)Project進(jìn)行目錄結(jié)構(gòu)、程序單元組織、框架與應(yīng)用關(guān)系的說(shuō)明。6.2.1 Project目錄結(jié)構(gòu)指導(dǎo)內(nèi)容：關(guān)于該P(yáng)roject一級(jí)目錄、二級(jí)目錄等基本目錄結(jié)構(gòu)的約定。意義：為團(tuán)隊(duì)并行開(kāi)發(fā)提供必要基礎(chǔ)，讓不同程序小組看到自己應(yīng)該負(fù)責(zé)的程序目錄。參考：不要把所有程序目錄的約定都定義得太細(xì)，否則這份架構(gòu)文檔就要天天更新了。 6.2.2 程序單元組織內(nèi)容：源碼、程序庫(kù)、框架、目標(biāo)碼等類(lèi)型程序單元之間的編譯依賴(lài)關(guān)系。意義：或許有人認(rèn)為這沒(méi)什么技術(shù)含量，但架構(gòu)設(shè)計(jì)本來(lái)就不是只關(guān)心技術(shù)含量最高問(wèn)題的。君不見(jiàn)，很多軟件工程師跳槽到新的企業(yè)之后，竟然連一個(gè)能正常編譯源碼的開(kāi)發(fā)環(huán)境都建不起來(lái)其實(shí)，他們“不知道Project所依賴(lài)的Library有哪些”是其中重要原因這本應(yīng)在架構(gòu)文檔中給出明確描述的。 6.2.3 框架與應(yīng)用之間的關(guān)系（可選）內(nèi)容：框架（Framework）。意義：既然不適用Framework的開(kāi)發(fā)越來(lái)越少了，既然程序員犯的很多錯(cuò)誤都和對(duì)Framework理解不到位有關(guān)，架構(gòu)師就有責(zé)任明確說(shuō)明Framework和待開(kāi)發(fā)系統(tǒng)之間的關(guān)系。 參考：下圖描述了JGraph框架和待開(kāi)發(fā)應(yīng)用的關(guān)系。 參考：下圖描述了Struts框架和待開(kāi)發(fā)應(yīng)用的關(guān)系。 6.3 Project 2內(nèi)容：對(duì)Project劃分后的每個(gè)Project進(jìn)行目錄結(jié)構(gòu)、程序單元組織、框架與應(yīng)用關(guān)系的說(shuō)明。6.4 Project n內(nèi)容：對(duì)Project劃分后的每個(gè)Project進(jìn)行目錄結(jié)構(gòu)、程序單元組織、框架與應(yīng)用關(guān)系的說(shuō)明。7. 運(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ā)。7.1 控制流組織內(nèi)容：控制流有哪些，每條控制流各是何種形式（例如進(jìn)程、線程、中斷服務(wù)程序），哪些軟件單元是控制流的起點(diǎn)，整條控制流中分別調(diào)用了哪些軟件單元。意義：這是對(duì)系統(tǒng)運(yùn)行時(shí)結(jié)構(gòu)的刻畫(huà)，主要反映系統(tǒng)的動(dòng)態(tài)結(jié)構(gòu)。7.2 控制流的創(chuàng)建、銷(xiāo)毀、通信內(nèi)容：描述進(jìn)程、線程和中斷服務(wù)程序的創(chuàng)建和銷(xiāo)毀，以及多條控制流之間的通信關(guān)系的定義。意義：一旦引入了多條控制流，附加工作就產(chǎn)生了此時(shí)控制流的創(chuàng)建和銷(xiāo)毀、以及控制流之間的通信關(guān)系往往是必須考慮的。7.3 加鎖設(shè)計(jì)內(nèi)容：系統(tǒng)中有多條控制流在同時(shí)運(yùn)行的情況下，一個(gè)經(jīng)典問(wèn)題是多于一條控制流可能會(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ì)造成的問(wèn)題往往以“不易重現(xiàn)的Bug”的形式出現(xiàn)，困惑的程序員會(huì)對(duì)測(cè)試人員說(shuō)，“你看你報(bào)的Bug在我機(jī)器上根本就不存在呀”。參考：對(duì)通用組件、通用模塊的設(shè)計(jì)而言，加鎖設(shè)計(jì)應(yīng)予以專(zhuān)門(mén)關(guān)注，思維要點(diǎn)是研究未來(lái)通用模塊的各種可能使用場(chǎng)景。8. 物理架構(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)。8.1 物理拓?fù)鋬?nèi)容：一為硬件選型，二為硬件之間的拓?fù)溥B接關(guān)系。意義：對(duì)于分布式系統(tǒng)的設(shè)計(jì)，此節(jié)極為重要、而且是必須的。參考：下圖是某企業(yè)級(jí)系統(tǒng)的物理拓?fù)鋱D。參考：下圖是某嵌入式系統(tǒng)的物理拓?fù)鋱D。8.2 軟件到硬件的映射內(nèi)容：明確每個(gè)物理節(jié)點(diǎn)上有哪些（一到多個(gè)）軟件的目標(biāo)單元，并說(shuō)明具體的“映射方式”是安裝、是部署、還是燒寫(xiě)、抑或是下載。意義：如果把此節(jié)漏了，就無(wú)法表明本文檔的主題軟件系統(tǒng)和上述硬件、硬件拓?fù)涞年P(guān)系。參考：下圖所示為設(shè)備調(diào)試系統(tǒng)中，軟件到硬件的映射關(guān)系。8.3 優(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ū)。9. 數(shù)據(jù)架構(gòu)視圖關(guān)注點(diǎn)：此架構(gòu)設(shè)計(jì)視圖的關(guān)注點(diǎn)是持久化。具體而言，場(chǎng)景化可以借助扁平文件、關(guān)系數(shù)據(jù)庫(kù)、實(shí)時(shí)數(shù)據(jù)庫(kù)、Flash等方式中的一種或多種完成。注意：本視圖單獨(dú)歸檔時(shí)，請(qǐng)?jiān)诖斯?jié)注明其文檔名稱(chēng)等信息。9.1 持久化機(jī)制的選擇內(nèi)容：如下持久化機(jī)制的一種或多種：扁平文件、關(guān)系數(shù)據(jù)庫(kù)、實(shí)時(shí)數(shù)據(jù)庫(kù)、Flash。意義：不要假設(shè)在你的系統(tǒng)中，持久化只需一種機(jī)制；隨著如今的系統(tǒng)變得越來(lái)越復(fù)雜，我們經(jīng)常需要綜合利用不同持久化機(jī)制。9.2 持久化存儲(chǔ)方案內(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è)計(jì)決策。意義：在數(shù)據(jù)分布的情況下，此節(jié)為必須。參考：在實(shí)際中，數(shù)據(jù)分布的策略絕大多數(shù)情況下不會(huì)超越下圖所示的6種手段，更多內(nèi)容可參考一線架構(gòu)師實(shí)踐指南一書(shū)。10.