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

1、 Software Architecture DocumentVersion DateVersionRevision HistoryDescriptionAuthorSoftwareArchitectureDocumentVersion: Date: 目 錄 HYPERLINK l “_TOC_250007“ 文檔簡(jiǎn)介4文檔目的4文檔范圍4定義、縮寫(xiě)詞和縮略語(yǔ)4參考資料4 HYPERLINK l “_TOC_250006“ 架構(gòu)描述方式4架構(gòu)視圖閱讀指南4圖表與模型閱讀指南5 HYPERLINK l “_TOC_250005“ 架構(gòu)設(shè)計(jì)目標(biāo)5關(guān)鍵功能5關(guān)鍵質(zhì)量屬性5業(yè)務(wù)需求和約束因素6 HYP

2、ERLINK l “_TOC_250004“ 架構(gòu)設(shè)計(jì)原則6架構(gòu)設(shè)計(jì)原則6備選架構(gòu)設(shè)計(jì)方案及被否緣由6架構(gòu)設(shè)計(jì)對(duì)后續(xù)工作的限制詳設(shè)，部署等6 HYPERLINK l “_TOC_250003“ 規(guī)律架構(gòu)視圖7職責(zé)劃分與職責(zé)確定7接口設(shè)計(jì)與協(xié)作機(jī)制8重要設(shè)計(jì)包10 HYPERLINK l “_TOC_250002“ 開(kāi)發(fā)架構(gòu)視圖11Project劃分11Project111Project名目構(gòu)造指導(dǎo)12程序單元組織12框架與應(yīng)用之間的關(guān)系可選12Project213Projectn13 HYPERLINK l “_TOC_250001“ 運(yùn)行架構(gòu)視圖13把握流組織13把握流的創(chuàng)立、銷(xiāo)毀、通信14

3、加鎖設(shè)計(jì)14 HYPERLINK l “_TOC_250000“ 物理架構(gòu)視圖14物理拓?fù)?4軟件到硬件的映射15優(yōu)化部署162of18SoftwareArchitectureDocument數(shù)據(jù)架構(gòu)視圖Version: Date: 169.19.29.3長(zhǎng)久化存儲(chǔ)方案數(shù)據(jù)同步與復(fù)制策略 171717173of18SoftwareArchitectureDocumentVersion: Date: 文檔簡(jiǎn)介幫助讀者對(duì)本文檔建立根本印象，并為閱讀后續(xù)內(nèi)容掃清障礙。文檔目的文檔目的，非工程目的。否則造成同一工程多個(gè)文檔之間的內(nèi)容重復(fù)，不利于文檔維護(hù)。本 小節(jié)應(yīng)指明文檔針對(duì)的讀者對(duì)象，最好列出各種讀

4、者角色，并說(shuō)明每種讀者角色應(yīng)當(dāng)重點(diǎn)閱讀的章節(jié)。文檔范圍文檔的Scope，非工程的Scope。否則造成同一工程多個(gè)文檔之間的內(nèi)容重復(fù)，不利于文檔 維護(hù)。定義、縮寫(xiě)詞和縮略語(yǔ)集中列舉文檔中的定義、縮寫(xiě)詞和縮略語(yǔ)。參考資料本工程經(jīng)審核的打算書(shū)、合同、上級(jí)批文；本工程的其他已發(fā)表文件；本文檔引用的文件資 料，如軟件開(kāi)發(fā)標(biāo)準(zhǔn)。具體而言，應(yīng)包括參考資料的題目必需、編號(hào)、版本號(hào)必需、發(fā)表日期、公布方，必要時(shí)還可以說(shuō)明如何使用這些資料。架構(gòu)描述方式為了讓讀者更好地理解架構(gòu)文檔，在本節(jié)應(yīng)當(dāng)說(shuō)明文檔涉及的架構(gòu)視圖，并指明為了描述設(shè)計(jì)決策用到了哪些圖表和模型。架構(gòu)視圖閱讀指南以多視圖的方式來(lái)組織架構(gòu)文檔是大勢(shì)所趨。

5、ADMEMS 推舉的是經(jīng)過(guò)優(yōu)化的 5 視圖方法，如以下圖所示。4of18SoftwareArchitectureDocumentVersion: Date: 圖表與模型閱讀指南對(duì)后續(xù)文檔內(nèi)容中所用到的建模語(yǔ)言例如UML、表格例如目標(biāo)-場(chǎng)景-決策表等進(jìn)展 說(shuō)明。架構(gòu)設(shè)計(jì)目標(biāo)功能、質(zhì)量、約束，一個(gè)都不能少。關(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é)。關(guān)鍵質(zhì)量屬性人之所以苦痛，很多時(shí)候是由于追求錯(cuò)誤的東西。以下圖是ADMEMS 5大原則的整體思路圖。5of18SoftwareArchitect

6、ureDocumentVersion: Date: 業(yè)務(wù)需求和約束因素ADMEMS 方法制造性地提出約束需求的 4 大類(lèi)型，這是一種極為有用的分類(lèi)方式。特別是業(yè)務(wù)需求對(duì)架構(gòu)設(shè)計(jì)而言是一種約束的觀點(diǎn)，解決了很多架構(gòu)師的現(xiàn)實(shí)困惑。以下圖標(biāo)明白4 類(lèi)約束在“需求層次-需求方面矩陣又稱(chēng)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)把它們“找回來(lái)”。架構(gòu)設(shè)計(jì)原則著重描述重大的權(quán)衡取舍考慮。備選架構(gòu)設(shè)計(jì)方案及被否緣由在概念架構(gòu)一級(jí)，對(duì)備選架構(gòu)設(shè)計(jì)方案進(jìn)展描

7、述，并闡述它們未被承受的緣由。這有利于團(tuán)架構(gòu)設(shè)計(jì)對(duì)后續(xù)工作的限制詳設(shè)，部署等架構(gòu)設(shè)計(jì)不僅應(yīng)當(dāng)包含“指導(dǎo)”，也應(yīng)當(dāng)包含重要的“限制”。例如，一份只是說(shuō)明“性能和可擴(kuò)展性都重要”的架構(gòu)文檔，實(shí)際上無(wú)視了“可擴(kuò)展性和性能之間存在的沖突關(guān)系”。此時(shí)，最有效的方法就是在架構(gòu)文檔中明確說(shuō)明“任何提升可擴(kuò)展性的架構(gòu)設(shè)計(jì)和6of18SoftwareArchitectureDocument規(guī)律架構(gòu)視圖關(guān)注點(diǎn)：此架構(gòu)設(shè)計(jì)視圖的關(guān)注點(diǎn)是職責(zé)劃分。Version: Date: 留意：規(guī)律架構(gòu)視圖無(wú)疑是最重要的，但同時(shí)也應(yīng)避開(kāi)“架構(gòu)= 模塊 + 接口”等以偏概全的生疏。參考：任何簡(jiǎn)單系統(tǒng)的架構(gòu)設(shè)計(jì)都不是一蹴而就的，所以

8、架構(gòu)師需要理性思維過(guò)程的指導(dǎo)。 針對(duì)規(guī)律架構(gòu)設(shè)計(jì)這個(gè)關(guān)鍵環(huán)節(jié)，一線架構(gòu)師實(shí)踐指南一書(shū)給出了2 條建議：一是“以質(zhì)疑驅(qū)動(dòng)的螺旋思維”，二是相對(duì)分別地考慮“構(gòu)造方面的切分”和“行為方面的定義”。以下圖所示即為ADMEMS方法推舉的規(guī)律架構(gòu)設(shè)計(jì)理性思維過(guò)程。職責(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ì)量屬性要求做出

9、相應(yīng)調(diào)整和優(yōu)化。很多參考：基于對(duì)業(yè)界大量案例的爭(zhēng)辯，ADMEMS 方法梳理出了“模塊劃分的 3 種必用手段”，如以下圖所示，更多內(nèi)容可參考一線架構(gòu)師實(shí)踐指南一書(shū)。7of18SoftwareArchitectureDocumentVersion: Date: 接口設(shè)計(jì)與協(xié)作機(jī)制參考：ADMEMS 方法推舉利用“包-接口”圖，來(lái)識(shí)別接口。以下圖為一個(gè)“包-接口”圖的例如。8of18SoftwareArchitectureDocumentVersion: Date: 參考：ADMEMS 方法推舉使用序列圖，建議少用、甚至杜絕使用協(xié)作圖。以下圖為一個(gè)序列圖的例如。9of18SoftwareArchit

10、ectureDocumentVersion: Date: 重要設(shè)計(jì)包內(nèi)容：對(duì)重要子系統(tǒng)的設(shè)計(jì)進(jìn)展“灰盒”級(jí)描述。意義：“每個(gè)子系統(tǒng)在架構(gòu)設(shè)計(jì)中都應(yīng)保持黑盒子”的觀點(diǎn)，過(guò)于抱負(fù)化了。對(duì)于業(yè)務(wù)層、通用協(xié)作機(jī)制而言，經(jīng)常需要在架構(gòu)設(shè)計(jì)期間就引入“灰盒”級(jí)描述。參考：類(lèi)圖和灰盒包圖，在本節(jié)中較多消滅。以下圖為一灰盒包圖例如。10of18SoftwareArchitectureDocumentVersion: Date: 開(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)

11、師就知道高來(lái)高去，架構(gòu)對(duì)編程工作沒(méi)什么指導(dǎo)性”。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直接映射到P

12、roject 經(jīng)常意味著工作內(nèi)容的遺漏。其實(shí)，業(yè)界不少有見(jiàn)地的專(zhuān)家已經(jīng)生疏到WBS工作分解構(gòu)造做得太早太草率危害很大，就與“Project 劃分不到位”不無(wú)關(guān)系。Project 1內(nèi)容：對(duì)Project 劃分后的每個(gè)Project 進(jìn)展名目構(gòu)造、程序單元組織、框架與應(yīng)用關(guān)系的說(shuō)11of18SoftwareArchitectureDocumentVersion: Date: 明。Project名目構(gòu)造指導(dǎo)內(nèi)容：關(guān)于該P(yáng)roject 一級(jí)名目、二級(jí)名目等根本名目構(gòu)造的商定。程序單元組織內(nèi)容：源碼、程序庫(kù)、框架、目標(biāo)碼等類(lèi)型程序單元之間的編譯依靠關(guān)系。意義：或許有人認(rèn)為這沒(méi)什么技術(shù)含量，但架構(gòu)設(shè)計(jì)原

13、來(lái)就不是只關(guān)心技術(shù)含量最高問(wèn)題的。君不見(jiàn)，很多軟件工程師跳槽到的企業(yè)之后，竟然連一個(gè)能正常編譯源碼的開(kāi)發(fā)環(huán)境都建不起來(lái)其實(shí)，他們“不知道Project 所依靠的Library 有哪些”是其中重要緣由這本應(yīng)在架構(gòu)文檔中給出明確描述的?？蚣芘c應(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)系。12of18Sof

14、twareArchitectureDocumentVersion: Date: Project2內(nèi)容：對(duì)Project 劃分后的每個(gè)Project 進(jìn)展名目構(gòu)造、程序單元組織、框架與應(yīng)用關(guān)系的說(shuō)明。Projectn內(nèi)容：對(duì)Project 劃分后的每個(gè)Project 進(jìn)展名目構(gòu)造、程序單元組織、框架與應(yīng)用關(guān)系的說(shuō)明。運(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)軟件和 嵌入式軟件極為重要的中斷效勞程序也是把握流，這樣利于架構(gòu)師統(tǒng)一利用不同把握流手段設(shè)計(jì)并行和并發(fā)。把握流組織內(nèi)容：把握流有哪些，每條把握流各是何種形

15、式例如進(jìn)程、線程、中斷效勞程序，哪些軟件單元是把握流的起點(diǎn)，整條把握流中分別調(diào)用了哪些軟件單元。意義：這是對(duì)系統(tǒng)運(yùn)行時(shí)構(gòu)造的刻畫(huà)，主要反映系統(tǒng)的動(dòng)態(tài)構(gòu)造。13of18SoftwareArchitectureDocumentVersion: Date: 把握流的創(chuàng)立、銷(xiāo)毀、通信內(nèi)容：描述進(jìn)程、線程和中斷效勞程序的創(chuàng)立和銷(xiāo)毀，以及多條把握流之間的通信關(guān)系的定義。意義：一旦引入了多條把握流，附加工作就產(chǎn)生了此時(shí)把握流的創(chuàng)立和銷(xiāo)毀、以及把握流之間的通信關(guān)系往往是必需考慮的。加鎖設(shè)計(jì)內(nèi)容：系統(tǒng)中有多條把握流在同時(shí)運(yùn)行的狀況下，一個(gè)經(jīng)典問(wèn)題是多于一條把握流可能會(huì)同 時(shí)修改某些數(shù)據(jù)構(gòu)造，而造成數(shù)據(jù)的不全都。

16、為此，架構(gòu)師需要關(guān)注加鎖設(shè)計(jì)，合理引入臨界區(qū)或同步機(jī)制。意義：加鎖設(shè)計(jì)事關(guān)系統(tǒng)的正確性。值得留意的是，無(wú)視加鎖設(shè)計(jì)造成的問(wèn)題往往以“不易重現(xiàn)的Bug”的形式消滅，困惑的程序員會(huì)對(duì)測(cè)試人員說(shuō)，“你看你報(bào)的Bug 在我機(jī)器上根本就不存在呀”。參考：對(duì)通用組件、通用模塊的設(shè)計(jì)而言，加鎖設(shè)計(jì)應(yīng)予以特地關(guān)注，思維要點(diǎn)是爭(zhēng)辯將來(lái)通用模塊的各種可能使用場(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ī)或效勞器，也可以是單片機(jī)、單板機(jī)或?qū)Ｓ脵C(jī)，從而物理架構(gòu)視圖既適用于描述企業(yè)信息系統(tǒng)，也適合于描述嵌入式軟件系統(tǒng)。物理拓?fù)鋬?nèi)容：一

17、為硬件選型，二為硬件之間的拓?fù)溥B接關(guān)系。意義：對(duì)于分布式系統(tǒng)的設(shè)計(jì)，此節(jié)極為重要、而且是必需的。 參考：以下圖是某企業(yè)級(jí)系統(tǒng)的物理拓?fù)鋱D。14of18SoftwareArchitectureDocumentVersion: Date: 參考：以下圖是某嵌入式系統(tǒng)的物理拓?fù)鋱D。軟件到硬件的映射內(nèi)容：明確每個(gè)物理節(jié)點(diǎn)上有哪些一到多個(gè)軟件的目標(biāo)單元，并說(shuō)明具體的“映射方式”是安裝、是部署、還是燒寫(xiě)、抑或是下載。15of18SoftwareArchitectureDocumentVersion: Date: 意義：假設(shè)把此節(jié)漏了，就無(wú)法說(shuō)明本文檔的主題軟件系統(tǒng)和上述硬件、硬件拓?fù)涞年P(guān)系。參考：以下圖所

18、示為設(shè)備調(diào)試系統(tǒng)中，軟件到硬件的映射關(guān)系。優(yōu)化部署意義：物理架構(gòu)設(shè)計(jì)的優(yōu)劣，造成的本錢(qián)差異和質(zhì)量差異，可能是天壤之別。所以必需重視。參考：以下圖呈現(xiàn)的，是ADMEMS 方法重點(diǎn)推舉的“物理架構(gòu)設(shè)計(jì)思維要點(diǎn)”，更多內(nèi)容可參考一線架構(gòu)師實(shí)踐指南一書(shū)。數(shù)據(jù)架構(gòu)視圖關(guān)注點(diǎn)：此架構(gòu)設(shè)計(jì)視圖的關(guān)注點(diǎn)是長(zhǎng)久化。具體而言，場(chǎng)景化可以借助扁平文件、關(guān)系數(shù)據(jù)庫(kù)、實(shí)時(shí)數(shù)據(jù)庫(kù)、Flash等方式中的一種或多種完成。16of18SoftwareArchitectureDocumentVersion: Date: 留意：本視圖單獨(dú)歸檔時(shí)，請(qǐng)?jiān)诖斯?jié)注明其文檔名稱(chēng)等信息。長(zhǎng)久化機(jī)制的選擇Flash。意義：不要假設(shè)在你的系統(tǒng)中，長(zhǎng)久化只需一種機(jī)制；隨著如今的系統(tǒng)變得越來(lái)越簡(jiǎn)單，我們經(jīng)常需要綜合利用不同長(zhǎng)久化機(jī)制。長(zhǎng)久化存儲(chǔ)方案內(nèi)容：長(zhǎng)久化數(shù)據(jù)的格式定義。數(shù)據(jù)同步與復(fù)制策略 意義：在數(shù)據(jù)分布的狀況下，此節(jié)為必需。參考：在實(shí)際中，數(shù)據(jù)分布的策略絕大多數(shù)狀況下不會(huì)超越以下圖所示的6 種手段，更多內(nèi)容可參考一線架構(gòu)師實(shí)踐指南一書(shū)。關(guān)鍵質(zhì)量屬性的設(shè)計(jì)原理內(nèi)容：因軟件系統(tǒng)的不同，性能、安全性、可