版本	日期	修訂人	描述
V1.0	2024/12/6	nick huang	創建文檔

背景

CSDN在發起“如何做好一份技術文檔”的活動。
想起我最近在寫一份詳細設計，有一些感受：

一份考慮較周全的“詳細設計文檔模板”能起到質量保底的作用。
當一名初級技術人員需要編寫詳細設計文檔，如果有一份較全面的詳細設計文檔模板能夠擔當指引：
1、有助于幫忙技術人員考慮到一些容易遺漏的點
2、有助于幫忙技術人員編寫出可讀性較高的文檔

詳細設計文檔的一些重要因素（我認為的）

需求背景（必需）

文檔的開始，要闡述這份設計對應的需求。

至少闡述這幾個問題：
1、幫用戶解決什么問題（用戶痛點）

最好能闡述這幾個問題：
1、我們將打算如何修改
2、修改這幾個點對應哪幾個系統的哪幾個功能（最好能用功能菜單來描述，避免大家理解不一致）

如果需求背景比較簡單，可以自己直接闡述；
如果比較復雜，可以制作“文檔鏈接”，確保在“評審時”能一鍵跳轉到《需求文檔》中繼續介紹，觀眾無須過多等待。

需求細節快鏈（建議）

Tips
除了上述的宏觀的“需求背景”。
在詳細設計評審會議上講述具體某個細節的實現方式時，為了幫助觀眾能快速地回顧該需求細節。
我通常會在描述實現細節的下文，放一張“需求文檔針對該需求的縮小版截圖”。
講解時，快速放大截圖幫助觀眾快速地回顧該需求細節。

方案描述（必需）

詳細介紹如何實現需求文檔的各個需求點（建議拆分功能點描述）。
有邏輯性地描述我們的方案如何最終實現用戶需求。

比如：有一個需求，在Apple頁面上新增Boy字段，默認為Cat值，支持更新，更新時給Dog用戶發送一封通知郵件。
那么，我們可以如何描述。

1、修改/createApple接口
修改邏輯：
1）新增Boy字段以及關聯的ORM
2）新建邏輯中，設置Boy字段默認值為Cat

2、修改/updateApple接口
1）入參添加Boy字段
2）添加Boy字段的更新邏輯
3）更新時給Dog用戶發送一封通知郵件的實現邏輯

3、修改/getApple接口
1）接口出參添加Boy字段

上述，是通過“ 如何寫數 → 如何使用數據 ”的邏輯闡述如何逐步實現用戶功能。

過程中有一些細節問題，可能產品未提及，可主動跟產品確認，比如：
1、新增Boy字段，默認為Cat值。可跟產品了解：Cat值后續改動的概率，如概率大，做成熱配置，降低修改成本
2、Boy字段的更新邏輯。跟產品溝通：是否需支持多用戶并行更新同一行記錄？如需，則詳述我們如何處理
3、發送一封通知郵件。跟產品溝通：如果郵件發送失敗，是否影響更新數據落庫？如不應影響，我們闡述如何實現異步，以及如何實現發送失敗的補償發送

Tips
復雜的寫數邏輯或算法可通過下述途徑，讓觀眾更容易理解：
1）偽代碼、偽SQL代碼
2）時序圖
3）流程圖

通過合適的技術手段講解實現方式

通過合適的技術手段講解實現方式，有哪些典型的場景呢？

接口涉及多組件或多應用，可用“時序圖”可視化地表達（如涉及，必需）

用戶訪問/apple接口訪問boy應用，然后boy應用通過訪問/cat接口訪問dog應用，dog應用將數據保持在MySQL的fish表，再將數據寫入Redis，最后調用郵件平臺發送一封郵件，再將fish表的id字段沿著請求的各節點返回給用戶。

上面一大段文檔，枯燥可讀性差、容易造成理解不一致。
如果用時序圖表達，情況將有所改善：

Tips
上面的時序圖，畢竟要畫圖，你可能覺得很麻煩，工作量較大。
這里推薦一個工具——PlantUML。
通過寫代碼的方式畫時序圖。
比如上圖，它的畫圖代碼如下，你可以用PlantUML Web Server試下：

@startuml
用戶 -> boy應用 : /apple
boy應用 -> dog應用 : /catdog應用 -> MySQL : fish表
MySQL --> dog應用 : fish.id=xdog應用 -> Redis
Redis --> dog應用dog應用 -> 郵件平臺: 發送郵件
郵件平臺 --> dog應用: 成功/失敗dog應用 --> boy應用 : fish.id=x
boy應用 --> 用戶 : fish.id=x@enduml

數據庫表設計與寫數規則（如涉及，必需）

如果實現涉及數據庫表結構的新增或字段變更，請務必描述出來。

數據庫單表設計點描述的一些重點：
1、常規的元素要設計好，比如：字段名、字段注釋、主鍵、表注釋
2、字段類型要考慮長度、精度
3、如新增字段涉及枚舉，各枚舉值（或數據字典）要羅列好，后續開發人員可拿到即用
4、如果寫數規則較復雜，可以用表格（如Excel）的形式來描述各字段的寫數示例，大家更容易理解

數據庫表關系描述的一些重點：
1、使用“ER圖”表示表與表之間的關系（至于ER圖的繪制，我會用DRAW.IO或EZDML，目前沒有特別傾向的繪圖工具，歡迎推薦）

涉及接口要羅列出來（如涉及，必需）

修改某個功能，涉及需要修改或新增的接口，都要羅列出來。

1、如果新增接口，描述接口的信息要齊全：
1）URL
2）Method
3）入參
4）出參
5）權限要求（這點容易遺漏哦！）
6）接口描述
可以借助Swagger等組件描述，但要注意能一鍵鏈接到位。

2、如果修改接口，要高亮出其中修改點或分點結構化文字描述。
如果修改接口，建議：
1、高亮出其中修改點
2、或者，分點文字描述其中的修改點

避免閱讀人員需通篇閱讀接口文檔，加之各種對比手段，才能獲知我們的修改點（還可能識別遺漏）。

Checklist 檢查清單

針對不同的需求，需要設計的重點可能不同，以下Checklist的點可能可以參考：

維度	解析
接口性能	接口的響應時間是否達到要求
業務吞吐量	需支持單位時間的接口訪問量
權限校驗	接口權限校驗、數據權限校驗
數據校驗	入參校驗、業務規則校驗、狀態校驗
冪等校驗	接口支持相同數據重復調用，不會產生錯誤數據
數據一致性	設計多個數據庫寫數動作或多個遠程調用，考慮使用本地事務或分布式事務
同一數據的強一致性	多人對同一筆數據同時操作，使用樂觀鎖或悲觀鎖確保符合用戶的操作預期
異步處理	哪些業務動作需異步處理（要注意失敗通知、失敗補償等場景），以達到：1）故障時不影響主流程；2）處理時間長無須用戶現場等待
異常情況告警	影響業務的關鍵功能運行不正常或數據不正常，是否需要告警通知（短信通知、消息通知、電話通知）
異常情況降級	影響業務的關鍵功能運行不正常時，我們是否需做熱下線或服務降級
審計	是否需要關鍵業務操作的審計日志，以便回溯、舉證

隨時補充，歡迎關注（你也可在評論區補充哦！）

最后

小弟不才，學識有限，如有錯漏，歡迎指正哈。
如果本文對你有幫助，記得“一鍵三連”（“點贊”、“評論”、“收藏”）哦！