1瓦侮、背景

隨著公司的不斷發(fā)展，業(yè)務(wù)對(duì)技術(shù)的要求也比原來更高佣谐，項(xiàng)目的數(shù)量越來越多肚吏、團(tuán)隊(duì)人數(shù)也越來越多、項(xiàng)目的質(zhì)量要求也越來越高狭魂。隨著項(xiàng)目的不斷立項(xiàng)罚攀，對(duì)項(xiàng)目在前期的設(shè)計(jì)要求也逐步確立下來。于是雌澄，項(xiàng)目中技術(shù)設(shè)計(jì)文檔的設(shè)計(jì)也需要留存下來坞生。

目前，技術(shù)項(xiàng)目目前沒有統(tǒng)一的規(guī)范掷伙，當(dāng)前技術(shù)設(shè)計(jì)的文檔也層次不齊。另外一方面又兵，更為重要任柜，我們目前的項(xiàng)目設(shè)計(jì)到底是一個(gè)什么樣的標(biāo)準(zhǔn)？是否經(jīng)得起考驗(yàn)沛厨？

如果你要寫一個(gè)技術(shù)技術(shù)設(shè)計(jì)文檔宙地，本文將介紹如何寫好。

1.1逆皮、為什么要寫技術(shù)設(shè)計(jì)

如同解釋為什么要做計(jì)劃一樣宅粥，我們寫技術(shù)設(shè)計(jì)文檔，主要有如下目的：

1电谣、便于溝通秽梅。所謂“一圖勝前言”抹蚀，有文檔的存在，將幫助大家了解要解決的問題企垦、實(shí)現(xiàn)的方法、當(dāng)前方案的局限、未來的擴(kuò)展和升級(jí)肛度、維護(hù)和運(yùn)維等夕春，用途上可以用于方案review、技術(shù)“遺產(chǎn)”等

2荧降、技術(shù)的延續(xù)與傳承接箫。技術(shù)的資料幫助后續(xù)開發(fā)者可以延續(xù)之前的技術(shù)，而不是在不清楚的情況下朵诫，進(jìn)行重構(gòu)

3辛友、完善思考。幫助負(fù)責(zé)人設(shè)計(jì)出技術(shù)方案更合理拗窃、有效瞎领，降低項(xiàng)目失敗的概率

1.2、本文適合哪些人閱讀

項(xiàng)目負(fù)責(zé)人随夸、架構(gòu)師九默、工程師，以及其他感興趣的同學(xué)宾毒。

2驼修、開始設(shè)計(jì)

編寫技術(shù)設(shè)計(jì)文檔，如同整體思路的完整表達(dá)一樣诈铛，需要有一定的邏輯性（思路）乙各，這就是我們所謂的輪廓。

2.1幢竹、文檔結(jié)構(gòu)

背景介紹 → 設(shè)計(jì)思路 → 詳細(xì)方案 → 補(bǔ)充材料

換句話說耳峦，上面的邏輯可以描述為：

1. 為什么要做這個(gè)技術(shù)方案
2. 我們打算用什么方案做
3. 這個(gè)方案的實(shí)現(xiàn)細(xì)節(jié)是什么樣子
4. 我參考了哪些資料（幫助背書）

2.1.1、萬事開始：背景介紹

背景介紹主要描述了焕毫，為什么要做這個(gè)項(xiàng)目蹲坷。一般這部分可以分為三部分：

1、背景邑飒，重點(diǎn)描述“為什么要做”循签。一般是兩種情況：解決問題和獲取收益。（當(dāng)然疙咸，有種情況是县匠，產(chǎn)品經(jīng)理或者老板要這個(gè)功能，屬于業(yè)務(wù)需求，這個(gè)一般也算在收益類）乞旦，比如：

最近一個(gè)月出現(xiàn)了7起因網(wǎng)絡(luò)原因?qū)е碌耐对V贼穆，目前已有的方案處理時(shí)間太長(zhǎng)（4-24）小時(shí)，導(dǎo)致客服與技術(shù)這邊非常被動(dòng)杆查。因此扮惦，我們發(fā)起這個(gè)項(xiàng)目，來解決類似的問題亲桦。

2崖蜜、范圍，對(duì)本文描述的話題設(shè)定一個(gè)邊界客峭，即：在有限的范圍內(nèi)討論豫领，以避免話題一發(fā)不可收拾。這里可以說明一下舔琅，這次設(shè)計(jì)方案的適用場(chǎng)景等恐，要解決的問題的邊界在哪里（要準(zhǔn)確，不要詳細(xì)）备蚓，比如：

本文僅描述在APP網(wǎng)絡(luò)條件下课蔬，基于HTTP協(xié)議網(wǎng)絡(luò)不可達(dá)的場(chǎng)景

3、定義（可省略）郊尝，比如：專有名詞二跋，文內(nèi)涉及到的自創(chuàng)名詞，公司內(nèi)名詞的解釋等流昏，這部分可以省略扎即；比如：

DNS：DeDao Name Service，服務(wù)注冊(cè)與發(fā)現(xiàn)（命名服務(wù)）

GW： DeDao Gateway况凉，網(wǎng)關(guān)

4谚鄙、現(xiàn)狀，描述了我們目前存在的問題刁绒，帶來的影響面等闷营，比如：

出現(xiàn)網(wǎng)絡(luò)問題后，我們解決的時(shí)間太長(zhǎng)：目前用戶出現(xiàn)網(wǎng)絡(luò)相關(guān)的問題知市，我們只能寄希望于CDN服務(wù)廠商來解決傻盟，這個(gè)周期在4-24小時(shí)。

5初狰、目標(biāo)，描述了這次方案要達(dá)成的效果互例，可以獲得的好處奢入，比如：

當(dāng)網(wǎng)絡(luò)問題出現(xiàn)后，可以在10分鐘內(nèi)完成處理（總體的好處，與現(xiàn)狀中描述的問題相呼應(yīng)）

至于目標(biāo)中涉及到的一些其他限制腥光，可以放在附錄里面（比如：基礎(chǔ)的QPS限制等）关顷。

2.1.2、打算怎么做：設(shè)計(jì)思路

有了問題武福，有了目標(biāo)议双，接下來就是：怎么做了。

首先捉片，我們要看看問題出現(xiàn)的原因是什么（定位問題）平痰，這一步非常關(guān)鍵，因?yàn)檎覝?zhǔn)敵人是我們能不能提供有效方案的前提伍纫。

比如宗雇，網(wǎng)絡(luò)連通性問題，造成用戶連不上服務(wù)的原因莹规，歸結(jié)為兩類：

1赔蒲、DNS將用戶調(diào)度到了錯(cuò)誤的節(jié)點(diǎn)，導(dǎo)致這個(gè)節(jié)點(diǎn)無法連通

2良漱、DNS將用戶調(diào)度到了正確的節(jié)點(diǎn)舞虱，但是這個(gè)節(jié)點(diǎn)故障了（無法提供正常的服務(wù)）

那么針對(duì)上面的兩個(gè)原因，我們就得有針對(duì)性的提供解決方案：

1母市、DNS的問題矾兜，使用IP訪問的方案，或者 httpDNS的方案（兩個(gè)都是可行的方案）

2窒篱、節(jié)點(diǎn)故障的問題焕刮，目前通知CDN合作方來調(diào)整節(jié)點(diǎn)，另外也可以提供多個(gè)節(jié)點(diǎn)做災(zāi)備

有些時(shí)候墙杯，我們需要多方案對(duì)比配并。針對(duì)一個(gè)問題，理論有無數(shù)的解高镐，那么這個(gè)時(shí)候一般需要思考：哪一種核心思路是最合適的（當(dāng)下）溉旋。一般情況下，我們會(huì)列至少兩種可行的解決思路嫉髓，來做對(duì)比观腊。

比如：

針對(duì)節(jié)點(diǎn)故障的問題，有如下解決方案：

1算行、人工容錯(cuò)梧油，通知CDN合作商進(jìn)行節(jié)點(diǎn)調(diào)整（修復(fù)），周期4-24小時(shí)

2州邢、提供多個(gè)CDN節(jié)點(diǎn)做災(zāi)備儡陨，由客戶端調(diào)度

針對(duì)上面兩個(gè)方案，方案1，成本小骗村，但是周期長(zhǎng)（SLA達(dá)不到）嫌褪；方案2，實(shí)現(xiàn)成本大胚股，但是SLA效果好笼痛，另外還能帶來CDN成本降低的好處（雖然跟目標(biāo)不符，但是也是一個(gè)好處）

這個(gè)時(shí)候琅拌，得開始描述缨伊，用了方案2，打算怎么做了财忽。

2.1.3倘核、說說怎么做：技術(shù)設(shè)計(jì)

有了基本的設(shè)計(jì)思路，那么如何通過設(shè)計(jì)把思路實(shí)現(xiàn)即彪。這里重點(diǎn)描述怎么做紧唱，以及在一些技術(shù)的選型上如何取舍。

2.1.3.1隶校、設(shè)計(jì)的準(zhǔn)則

我們做設(shè)計(jì)漏益，都會(huì)有一個(gè)好壞的標(biāo)準(zhǔn)（比如做技術(shù)設(shè)計(jì)評(píng)審，也會(huì)有一個(gè)是否通過的標(biāo)準(zhǔn)）深胳，那么設(shè)計(jì)什么樣的設(shè)計(jì)是好的設(shè)計(jì)绰疤？從我接觸到的一些人（P8P9大神）對(duì)這個(gè)問題的理解（這部分可以參考：極客時(shí)間里李運(yùn)華的《從0開始學(xué)架構(gòu)》），我整理總結(jié)了一下：

1. 合適即可舞终，少做過渡設(shè)計(jì)轻庆，不做勉強(qiáng)實(shí)現(xiàn)。這里有個(gè)度敛劝，即：什么程度合適余爆，這個(gè)就需要拿捏了（經(jīng)驗(yàn)的區(qū)別就出來了）
2. 簡(jiǎn)單即可，如果可以有更簡(jiǎn)單的辦法實(shí)現(xiàn)夸盟，那么用簡(jiǎn)單會(huì)比復(fù)雜的好
3. 演化改進(jìn)蛾方，“演化優(yōu)于一步到位”

（上面三個(gè)我就不解釋了，純是觀念問題上陕，理解即可）

另外桩砰，我們對(duì)設(shè)計(jì)上有一些基本的描述，這些會(huì)有兩個(gè)方面：設(shè)計(jì)原則和設(shè)計(jì)特性释簿。

所謂的設(shè)計(jì)原則亚隅，一般情況下我們講的是六大設(shè)計(jì)原則：單一職責(zé)（SRP）、開閉原則（OCP）庶溶、里式替換（LSP）煮纵、依賴導(dǎo)致（DIP）沉删、接口隔離（ISP）、迪米特法則（LoD）醉途。這部分這里不做贅述，各位可以自行Google（紅色加粗表示重要）砖茸。

設(shè)計(jì)特性上隘擎，我整理了一份常見的特性：穩(wěn)定性（魯棒性）、可測(cè)試性凉夯、高可用性货葬、可擴(kuò)展性、最小復(fù)雜度劲够、可維護(hù)性震桶、松散耦合、可重用性征绎、可移植性蹲姐、層次性。

一般情況下人柿，遵守上面的設(shè)計(jì)原則的設(shè)計(jì)總是比較好的（目前我沒有找到反例）柴墩，滿足實(shí)現(xiàn)原則的設(shè)計(jì)，在系統(tǒng)特性上凫岖，一般也具備比較多的特性江咳。比如：

滿足OCP和SRP的設(shè)計(jì)，一般都松散耦合和可擴(kuò)展的哥放，做得好的歼指，還可以滿足：可維護(hù)、最小復(fù)雜度甥雕、可重用踩身、可移植和層次性。

以上的原則和特性犀农，需要慢慢練習(xí)惰赋，至于它的好處，也是慢慢會(huì)體現(xiàn)出來呵哨。

2.1.3.2赁濒、概要設(shè)計(jì)

一般情況下，我們會(huì)使用“總-分”的思路來寫內(nèi)容孟害，即：先寫整體框架（架構(gòu)）是怎么樣的拒炎，然后再分別寫每個(gè)模塊是怎么做的。概要設(shè)計(jì)挨务，就是描述技術(shù)的整體怎么做击你。

總體設(shè)計(jì)中玉组，可以分為以下幾種場(chǎng)景：

1、整體設(shè)計(jì)里面包含各子系統(tǒng)或子模塊丁侄，那么需要做整體的架構(gòu)圖（可以是框圖惯雳、也可以部署圖），來區(qū)分彼此的定義

2鸿摇、如果是業(yè)務(wù)類型的設(shè)計(jì)（如實(shí)現(xiàn)某個(gè)業(yè)務(wù)的接口石景、過程等），可以有流程圖來描述拙吉。

上面說的需要使用圖標(biāo)來描述潮孽，這里是個(gè)建議，不是必須的筷黔；如果覺得文字能夠說明白往史，那么可以省略畫圖。

概要設(shè)計(jì)中佛舱，描述了多個(gè)子系統(tǒng)或者多模塊的“定位”椎例，即滿足系統(tǒng)三要素：要素（命名）、關(guān)系请祖、定位粟矿。

命名（要素）：這個(gè)模塊叫什么，比如：接口層损拢、調(diào)度器等

關(guān)系：模塊和模塊之間的關(guān)系陌粹，這里一般講的是：越往上越貼近業(yè)務(wù)，越往下越貼近實(shí)現(xiàn)

定位：也可以叫功能福压、作用掏秩，它被設(shè)立的目的是什么，這部分需要滿足單一職責(zé)荆姆，即：一個(gè)模塊干一件事

2.1.3.3蒙幻、業(yè)務(wù)設(shè)計(jì)/模塊設(shè)計(jì)

這部分可以有多個(gè)，主要描述各個(gè)模塊的具體實(shí)現(xiàn)胆筒。這部分一般有兩類：

1. 業(yè)務(wù)類邮破，比如：業(yè)務(wù)接口
2. 模塊類，比如：存儲(chǔ)模塊仆救、算法模塊

這里抒和，如果是業(yè)務(wù)類，需要寫清楚業(yè)務(wù)的流程彤蔽，即：業(yè)務(wù)實(shí)現(xiàn)的各種可能性摧莽，輸入是什么、輸出是什么顿痪，實(shí)現(xiàn)什么feature镊辕，實(shí)現(xiàn)的邏輯油够。注意：這部分需要滿足：接口的單一職責(zé)和接口隔離，即：一個(gè)接口干一件事征懈。

模塊類石咬，一般根據(jù)模塊的定位來描述，比如：這個(gè)模塊主要是做算法的卖哎，那么重點(diǎn)寫清楚這個(gè)算法實(shí)現(xiàn)碌补；如果這個(gè)模塊是做存儲(chǔ)的，可以寫清楚存儲(chǔ)的數(shù)據(jù)結(jié)構(gòu)棉饶；除此之外，有時(shí)候也必要提供對(duì)外的接口镇匀。

2.1.3.4照藻、存儲(chǔ)設(shè)計(jì)

曾經(jīng)有位大哥講：計(jì)算機(jī)系統(tǒng)=數(shù)據(jù)結(jié)構(gòu)+算法。那么這部分就是我們所謂的數(shù)據(jù)結(jié)構(gòu)汗侵。在目前的分布式系統(tǒng)中幸缕，大部分的存儲(chǔ)分為：

1. 緩存（Redis、Memcache等）
2. 業(yè)務(wù)數(shù)據(jù)（Mysql晰韵、MongoDB发乔、Redis等）
3. 基礎(chǔ)數(shù)據(jù)（Mysql、MongoDB雪猪、HBase等）
4. 文件存儲(chǔ)（OSS栏尚、S3、其它文件存儲(chǔ)）

這里存儲(chǔ)主要在數(shù)據(jù)庫上面（這部分根據(jù)重點(diǎn)只恨，有的項(xiàng)目重點(diǎn)在緩存上译仗，有些在文件上），數(shù)據(jù)庫建議這里寫清楚：數(shù)據(jù)庫的建表語句和核心查詢SQL官觅。

2.1.3.5纵菌、降級(jí)與預(yù)案

這部分主要描述，當(dāng)我們的正常業(yè)務(wù)不可用休涤、使用超出系統(tǒng)限制的時(shí)候咱圆，會(huì)如何反應(yīng)。這部分可以分場(chǎng)景（分情況）來描述功氨，講清楚即可序苏。

2.1.3.6、運(yùn)維與部署

一般情況下可以省略捷凄。如果涉及到跨系統(tǒng)調(diào)用杠览、中間件，這里建議有一個(gè)部署圖纵势，并描述清楚踱阿，哪些是水平擴(kuò)容管钳、哪些是主備方式。

2.1.4软舌、補(bǔ)充材料

補(bǔ)充材料可以描述才漆，我們?cè)谧稣{(diào)研的過程中，涉及到的一些參考資料（可以是書佛点、文章醇滥、論文）；另外超营，有一些不方便在前面描寫的鸳玩，也可以在這里寫一寫，比如：錯(cuò)誤編號(hào)等演闭。

2.2不跟、如何做得更好

說完了基本結(jié)構(gòu)，表示我們可以先簡(jiǎn)單寫一個(gè)文檔了米碰。那么如何將文檔寫得更好一些窝革，可以讓他人讀起來更準(zhǔn)確、高效理解設(shè)計(jì)的內(nèi)容吕座？

2.2.1虐译、方案是完整的

方案設(shè)計(jì)是完整的，一個(gè)設(shè)計(jì)一般會(huì)考慮：

1. 業(yè)務(wù)上滿足產(chǎn)品需求
2. 測(cè)試上滿足質(zhì)量需求
3. 時(shí)間上滿足項(xiàng)目需求
4. 運(yùn)維上滿足部署需求

（上面的話也不是我說的吴趴，是某知名架構(gòu)師說的）

2.2.2漆诽、方案是有條理的

好的設(shè)計(jì)就像講故事一樣，有前因后果锣枝，邏輯清晰拴泌，能從一處引出到另外一處。

2.2.3惊橱、方案是易讀的

并不是晦澀難懂的方式是牛逼的方案蚪腐，深入淺出的東西容易讓他人一目了然（當(dāng)然也不反對(duì)有些人為了寫的爽）。那么我們也會(huì)有一些技巧可以讓方案更容易被讀懂税朴。

2.2.3.1回季、使用結(jié)構(gòu)化表達(dá)代替完整的段落

如果某些內(nèi)容可以用：1、2正林、3來表達(dá)泡一，那么盡量用它來描述，比如：

這個(gè)設(shè)計(jì)講了如何使用CDN觅廓，也講了CDN的限制鼻忠，說明的CDN的價(jià)格，最后還解釋了哪些場(chǎng)景不能使用CDN杈绸。

可以修改為：

1. 如何使用CDN
2. CDN的限制
3. CDN的價(jià)格
4. 哪些場(chǎng)景不適合

2.2.3.2帖蔓、使用表格來描述二維數(shù)據(jù)

如果可以用表格描述的矮瘟，盡量用表格，方便一目了然塑娇。

2.2.3.3澈侠、使用圖

一圖勝千言，也是這個(gè)意思埋酬。關(guān)于技術(shù)設(shè)計(jì)的五個(gè)圖哨啃，參考：軟件工程常用的五種圖

這里，其實(shí)還少了一張圖（這個(gè)圖在某些場(chǎng)景下也非常有效）写妥，叫：用例圖拳球，這種圖可以更好的描述用戶的功能（需求）。

2.2.3.4珍特、合適的粒度祝峻，可以幫助表達(dá)得更準(zhǔn)

當(dāng)我們?cè)诿枋鲆粋€(gè)概要設(shè)計(jì)的時(shí)候，這個(gè)時(shí)候更關(guān)注整體系統(tǒng)有多少個(gè)子系統(tǒng)次坡，分為了多少層，那么在這個(gè)設(shè)計(jì)里面画畅，類圖就是不合適的砸琅。如果我們的設(shè)計(jì)是關(guān)于某個(gè)算法的，那么在這里花大量時(shí)間描述為什么要做這個(gè)算法也不合適轴踱。

合適的粒度可以幫助設(shè)計(jì)更有主次症脂，更容易讓表達(dá)不跑偏，從而實(shí)現(xiàn)準(zhǔn)確淫僻。

2.2.3.5诱篷、標(biāo)題有層次有序號(hào)

如同本文一樣，有不同級(jí)別的標(biāo)題雳灵、有序號(hào)棕所，是不是更清晰一些？

3悯辙、附錄

3.1琳省、參考資料

1. 《軟件開發(fā)過程中的浪費(fèi)--詳細(xì)設(shè)計(jì)》http://www.cnblogs.com/stephen-wang/archive/2012/11/12/2767021.html
2. 《軟件質(zhì)量模型的6大特性》https://blog.csdn.net/u012841352/article/details/54237654
3. 《軟件的6大特性》https://blog.csdn.net/wyl836662856/article/details/51860732
4. 《代碼大全》第二版
5. 《設(shè)計(jì)模式之六大原則》http://www.cnblogs.com/dolphin0520/p/3919839.html
6. 《架構(gòu)設(shè)計(jì)的三原則》 李運(yùn)華，極客時(shí)間《從0開始學(xué)架構(gòu)》
7. 《UML用例圖》https://blog.csdn.net/wrs120/article/details/52612107

3.2躲撰、參考樣例

下面這些參考樣例针贬，來自于不同公司的不同風(fēng)格，供大家參考拢蛋。

1. bilibili 高并發(fā)實(shí)時(shí)彈幕系統(tǒng)的實(shí)戰(zhàn)之路 桦他，來自劉丁，重點(diǎn)看文章的邏輯性

3.3谆棱、模板