1.概要

大部分的工程師都不重視設計文件的書寫，對於一個需求，都是經過一些簡單的討論，寫一個簡單的方案甚至就是自己簡單的想想就開始進行編碼的工作。

往往這種開發方式會導致開發人員對細節考慮不周，開發過程中會帶來許多的坑，在今後採坑或者補坑的路上耗費大量的人力，輕則影響上線時間，重則上線了出現case，影響業務。

寫設計文件和是能夠幫助開發人員完成 是什麼->做什麼->怎麼做 的思路梳理過程。比如，你可能對一個技術或者概念很熟悉了，但是你在要說出來或者寫出來給別人看的時候，或許就會發現有些技術的細節你沒有考慮清楚。

當你在寫一個設計文件的時候，會逼迫你自己去把每一個細節都弄清楚，想明白。這樣，在實際的開發過程中才會少踩坑，不踩坑。

2.好的設計文件需要哪些內容

對於一個設計文件的書寫，應該滿足STAR原則，同時一個好的設計文件需要考慮業內的各種實現方案，不能閉門造車。

基於此我認為主要會分為8個部分。分別為 專案背景，專案目標，需求分析，方案對比，概要設計，詳細設計（儲存模型設計，介面設計），開發以及上線計劃，方案排期。

對於詳細設計中，需要儲存應該有儲存模型的設計，需要互動應該有相應介面的設計。下面詳細說下每個部分的書寫要點。

2.1專案背景

主要是梳理下目前系統中的主要問題和痛點，主要問題和痛點的範圍覆蓋面很廣，可以主要從 穩定性、業務、 運營的角度去分析。

• 對於穩定性，具體的問題可以給出相應的資料指標，比如相關呼叫時間多少，TP90時間，客訴率，下單成功率等等。
• 對於業務，具體可以從業務發展，業內痛點來進行分析
• 運營，具體的問題也可以給出相應的資料指標，比如運維成本高大於XXpd等。

2.2目標

即自己做的這個方案上線後需要達到什麼成果，具體目標需要結合專案背景來定。

• 比如對於穩定性而言，需要降低一半的客訴率，將下單成功率提高到4個9等等。
• 對於運維角度而言，需要將運維成本降低為0等等。

同樣，具體的問題需要具體分析，定目標時可以參考目前業內或者公司內部的相關係統的指標

2.3需求分析

理論上來說，需求分析是PM來做的事情，但是通過需求分析，開發人員能夠更加清晰的瞭解和明確相應使用者的需求，也可以通過需求分析瞭解PM有時的需求是否是“偽需求”。

相關功能的優化以及系統的演進目的都是為了給使用者提供更好的服務，在進行需求分析時，開發人員應該儘量的使用下自己的系統，以便能夠真正的瞭解自己的系統。需求分析的要求是需要畫出一個 用例圖，用來描述使用者的所有用例。

2.4方案對比

在進行方案設計時，其實也是一個方案調研的階段，需要調研業內或者一些開源系統的相關功能實現。並與自身業務相結合，評估出一套最適合自己的業務。

方案對比主要是為了選擇出一個適合於自己業務的，有時候不要為了技術而技術，簡單合適反而是最佳的選擇。

方案對比中可羅列出每個方案的開發流程以及需要注意事項，最後給出方案對比表格以及結論即可

2.5概要設計

在選擇好了方案後，需要給出方案的概要設計，在概要設計中，用以描述整個方案的全景設計，一般來說需要包含方案全景設計圖、流程圖以及時序圖。

• 全景設計圖：如果設計方案是對於系統維度，那麼設計圖中需要體現出當前系統在整個鏈路中的呼叫關係，以及當前服務中相關的領域設計，相應領域中應該列出具體的相關功能；如果設計方案是系統內部的優化或者改造方案，那麼需要畫出內部的呼叫層級關係圖，在圖中應該需要標識出系統間的模組關係以及當前方案上線後的呼叫關係。
• 流程圖：流程圖用於描述中方案的詳細執行過程，如果方案是系統維度的則沒有不用畫出。
• 時序圖：時序圖的維度可以是針對於服務與服務之間，顯示出服務之間的呼叫，具體的介面可以列出相關服務的內部功能。

2.6詳細設計

詳細設計中包含方案的對比，儲存，介面等詳細設計。

儲存模型設計

儲存模型設計中需要給出相關儲存模型圖和相關表的DDL設計：

相關儲存模型圖為相關表的一對一，一對多對映關係，以及當前設計表的相關重要欄位
DDL中需要給出相關的建表SQL，建表SQL中每個欄位都需要強制給出預設值以及欄位詳細含義，最後需要給出相應的表索引

介面設計

介面設計中需要給出相應介面的定義，請求和響應物件的定義，如果是rpc介面，比如thrift還需要定義出相關的idl。另外還需要定義介面的超時時間等

• 介面定義時，可採用swagger來自動生成文件
• 介面只能新增和適配，沒有100%的把握，不能輕易的刪除來介面

2.7開發及上線計劃

分為開發計劃和上線過程

• 開發計劃：主要是列下主體的開發流程，具體可以列出一些方案里程碑的完成時間
• 上線計劃主要包括：
  
  • 如何進行灰度
  • 如何釋出，釋出後的check人
  • 如何進行驗證
  • 回滾策略

2.8專案排期

給出專案的排期表格，表格中除各計劃的相關內容外，還應該包括 預計估時，目前進度，是否delay，delay原因等等。

3.總結

設計文件不僅僅是寫出來給別人看的，而且是一次深入思考的過程，寫作的過程就是逼迫自己思考的過程，一篇好的設計文件不僅能使得閱讀人員對於所要開發的功能一目瞭然，還避免了今後的採坑過程。

當然，這篇文章也並沒有涵蓋所有設計文件的寫作，比如也可以通過MindManager畫思維導圖，或者使用其他的工作，只需要表現的清晰即可。

有設計文件寫作建議或者有工具推薦的小夥伴歡迎留言討論~