模块说明模板
前言：
最近在做團隊項目的架構改造時，從改造之初的評估，如是否有這樣的必要，改造價值，當前的問題等；到項目該怎么架構、功能劃分，任務分配；模塊的評估設計、評審。切切收獲很多。
現在是都是團隊一起來開發一個項目，會遇到以下問題：
? ? ? ?1. 如果整個項目架構模塊不清晰，就很難劃分責任、任務到人；
? ? ? ?2. 同時開發，互相干擾的可能變大，出現問題的可能性變大。
? ? ? ?3.代碼糾結在一起，會出現互相干擾理解的狀況，維護成本增加。
? ? ? ?4. 功能擴展難，易引起其它問題。
這時就需要模塊化我們的項目，以解決這些問題。如有以下這些優點。
? ? ? 1. 沉淀穩定化的功能模塊，可供其它項目使用。也會減少其它項目的干擾。
? ? ? 2. 模塊化，形成規范化的文檔，為交接、維護、任務責任劃分打下基礎。
? ? ? 3. 模塊化測試，能更快的保證某一塊的穩定性、性能提升。
下面內容是模塊說明的模塊，以便大家參考。
XXX模塊說明
【中括號中的內容是提示性說明，具體模塊說明書的正式文檔中應該刪除。】
【模塊說明書是寫給別人看的，理應盡量詳實和表述清楚。】
【模塊處在不斷改進的過程中，模塊說明書也應及時更新】
【每個模塊都有自己的特征、特質，模塊請根據自身的特點來增加或刪除某一些小點，使得模塊說明書更加的詳實。】
?
變更記錄
【主旨是：誰在什么時間更新了什么內容。以便備注查找跟蹤。】
| 序號 | 更新內容 | 負責人 | 更新時間 |
| 1 | XXX | XXX | XXX |
| 2 | ? | XXX | XXX |
| 3 | ? | XXX | XXX |
1 需求分析
【主旨：明確模塊的需求和目標，這樣才能確定模塊是否有存在的必要。這是模塊設計、開發的前提。】
1.1????問題
【主旨：分析問題，明確模塊是否有必要封裝，進而選擇模塊的封裝形式】
【目前模塊的三種封裝形式：
1.???????封裝，不提供源碼給第三方使用。
在主體基本無變化的情況下使用。
2.???????不封裝，僅有演示demo,演示某一功能塊怎么樣使用，簡化學習成本。
已有方案已經封裝較好，沒有多余的封裝，通過demo演示方案所有的調用方式，避免文檔不足、不詳實導致實施人員到處查找資料的耗時，提高學習效率，降低學習成本。
3.???????封裝主體，提供源碼給實施團隊。
涉及到界面的的封裝，在不同的業務場景可能會有定制需求。封裝主體流程并提供源碼給實施團隊。實施團隊直接使用，或根據需求修改定制源碼。
】
?
【下列問題1、問題2是必須思考的問題，這決定了模塊的封裝形式的選擇。】
【問題1：需不需要，重要性是多大？
模塊在哪些場景下使用，是必要場景，還是可有可無的使用。通過查看，明確模塊的重要性。】
【問題2：是否有必要封裝？
模塊在未封裝前會遇到哪些問題或特殊需求，是否是到了必須解決的地步，封裝后是否可以解決或避免這些問題，或帶來哪些明顯的好處、優勢。】
【其它問題：關于模塊的其它問題。
根據模塊自身特點，選擇一些重要的問題進行回答。如：模塊有哪些第三方的解決方案；為什么使用第三方解決方案；該怎么選擇等。】
1.2????調研
【主旨：尋找模塊的解決方案、設計思路和設計方案】
【理應避免閉門造車，通過多看、多問、多思等途徑來尋找模塊的解決方案、設計思路和設計方案。】
?
【內容一：模塊重要的基礎概念、基礎知識
模塊重要的基礎概念、基礎知識是每個維護者必須知道的知識。簡單介紹或指引學習資料，普及進一步學習的基礎。】
【內容二；解決方案的基本思路和理念
了解并總結一些其它人的解決方案的思路，優缺點等，開闊認知和思路。】
【內容三：同類產品是怎么操作的
查看同類產品是怎么選擇的，理由是什么。】
?
【如網絡模塊：通過代理發現，招商等銀行的網絡請求的安全是通過雙向驗證完成的。雙向驗證、單向驗證、不驗證的http優劣勢，最終模塊會選擇什么樣的解決方案。】
【如網絡模塊：因為銀行的安全等級要求，要求使用Ynet平臺的項目都必須做雙向驗證，以保證安全性。】
1.3????結論
【主旨：給出模塊需求分析的結果】
?
【模塊概述：用一句話對模塊進行概述或定義，給出清晰的界定。
封裝方式：采用哪種封裝方式。
使用方案：說明模塊選擇的實施方案或核心。如使用哪個第三方解決方案。
選擇理由：說明選擇相關方案的理由
模塊目標：通過模塊封裝能達到的目標
模塊構成：整個模塊構成的部分有哪些？必有的是演示demo和模塊文檔說明。
使用場景：說明模塊可在哪些場景下得到使用。
】
2 ?模塊設計
【主旨：這是模塊開發的基礎。
軟件的迭代過程是：先有設計思路、架構設計，再具體開發；在開發過程中再不斷完善初始的設計和架構。清楚了設計思路、架構設計，在模塊開發中才不會混亂。】
2.1????設計思路
【主旨：簡述模塊的設計思路、思想或設計原理。可無】
【如安全鍵盤模塊的設計思路描述為：上層業務使用過程中無法接觸到第三方安全鍵盤的sdk，所使用的類或接口都是杭州銀行安全鍵盤模塊自定義的。解耦第三方安全鍵盤的sdk與業務層。】
?
2.2????架構圖
【主旨：以UML圖加文字說明模塊的內部關系
使用類圖、時序圖、生命周期圖等UML圖形來表達模塊的架構。輔以文字說明以增加理解。】
?
2.3????流程圖
【主旨：用流程圖表示模塊內部主要的邏輯流程、數據流程等。可無】
【如果模塊僅有一個入口，可以從該入口開始畫自己的流程圖，涵蓋整個模塊大體的邏輯處理跳轉過程，直到從模塊出去。】
?
2.4????交互示意圖
【主旨：用示意圖來說明模塊與業務怎么交互的】
【如：業務從哪些途徑進入模塊，模塊怎么處理，然后是否返回結果。】
3 模塊說明
【主旨：這是模塊開發過程定義好的，供模塊使用者學習了解的。盡量少的改變。】
3.1 使用說明
3.1.1 集成說明
【主旨：說明模塊的集成過程，有截圖演示。】
3.1.2 使用注意
【主旨：如果模塊在使用前有前置條件或要求，在此說明。
是否需要提前做初始化，該怎么做初始化，初始化的步驟是。
是否需要其它模塊前置先做初始化，
或模塊在運行使用中有什么要特別注意的地方，如內存、配置等】
?
3.2 ?API說明
?【主旨：模塊對外的類，需要說明其提供的API接口有哪些，參數含義、作用】
?
3.2.1 XXX.java
【主旨：說明XXX.java提供了哪些api】
?
1.??設置隨機數
| 方法名稱 | void setCipherKey(String key) |
| 參數 | String key |
| 備注 | 設置32位隨機字符串。此串用于AES/SM4等的加密。 |
| 返回值 | 無 |
?
4 測試
【主旨：模塊必須得到完整的測試，保證其穩定性、正確性。然后才可提供給別人使用】
【思維導圖的測試：用于對demo、頁面的測試。完善測試步驟。】
【自動化的測試：用于對Api的接口測試。完善測試用例。】
【測試要求：說明對測試的技術要求、輸入數據、預期結果、進度安排、人員職責、設備條件、驅動程序及樁模塊等的規定。】
總結
- 上一篇： 数据分析学习总结笔记04：异常值处理
- 下一篇： 训练集与测试集数据分布不一致