很多項目交付后出現(xiàn)維護困難,往往不是代碼寫得有多差,而是缺少能讓人看懂系統(tǒng)全貌的文檔。接手的人打開倉庫,找不到啟動方式,不清楚某個字段為什么存在,也不知道改一處會不會影響其他模塊,只能靠猜和試,風(fēng)險極高。對做定制開發(fā)、需要長期維護客戶系統(tǒng)的團隊來說,文檔不是交付時的額外負擔(dān),而是降低售后成本、保證項目能持續(xù)跑下去的關(guān)鍵資產(chǎn)。
一份對維護人員友好的文檔,通??梢苑殖蓭讉€層次:先讓人快速跑起來,再讓人理解業(yè)務(wù),然后讓人知道技術(shù)結(jié)構(gòu),最后讓人知道出問題怎么查、怎么改、怎么上線。
一、項目概覽:先講清楚系統(tǒng)解決什么問題
這部分篇幅不用長,但必須有。要說明系統(tǒng)的目標(biāo)用戶是誰、核心業(yè)務(wù)鏈路是什么、當(dāng)前處于什么階段,是剛上線、穩(wěn)定運行還是準備重構(gòu)。還要寫清楚哪些功能是核心鏈路,哪些是邊緣功能,哪些已經(jīng)廢棄但代碼還留著。
同時列出關(guān)鍵角色和權(quán)限,比如普通用戶、門店員工、店長、運營、管理員分別能做什么,避免接手人誤以為某個權(quán)限是遺漏。如果系統(tǒng)對接了外部服務(wù),也要在這里列一張清單,說明每個外部依賴的用途、聯(lián)系人角色、失效后的影響,方便出問題時快速判斷是不是第三方導(dǎo)致。
二、快速啟動:讓新人半小時內(nèi)把項目跑起來
這是最容易被忽略卻最有價值的一部分。要寫清楚運行環(huán)境版本,包括語言運行時、數(shù)據(jù)庫版本、緩存版本、依賴包管理工具版本,以及為什么必須用這個版本。很多老項目換版本就跑不起來,提前寫明能省大量時間。
還要提供完整的啟動步驟:如何拉代碼、切換分支、安裝依賴、配置環(huán)境變量、初始化數(shù)據(jù)庫、導(dǎo)入基礎(chǔ)數(shù)據(jù)、啟動服務(wù)、訪問前端地址、登錄測試賬號。環(huán)境變量要列出每一項的含義,敏感信息不要直接寫在文檔里,只寫從哪里獲取、由誰管理。
如果本地跑不起來,要記錄常見報錯和解決辦法,比如端口占用、數(shù)據(jù)庫連接失敗、依賴編譯失敗、證書問題、跨域問題。這些坑往往只有踩過的人知道,寫下來就是給后來人省時間。
三、業(yè)務(wù)說明:把規(guī)則和例外寫清楚
維護人員最怕的是改代碼時不知道業(yè)務(wù)規(guī)則。比如訂單多久未支付自動取消,優(yōu)惠券能不能疊加,退款是退余額還是退原路,預(yù)約取消后號源什么時候釋放,會員儲值能不能跨門店使用,這些都必須寫清楚。
建議用流程圖或者分步驟描述核心鏈路,從用戶進入、選擇服務(wù)、提交訂單、支付、到店核銷、完成服務(wù)到售后退款,每一步由哪個模塊處理,觸發(fā)哪些通知,寫入哪些表。
特別要記錄例外情況和歷史原因。有些代碼看起來很冗余,其實是當(dāng)初為了兼容某類特殊客戶或者某個歷史數(shù)據(jù)留下的,如果沒寫清楚,接手人很可能順手刪掉,導(dǎo)致線上出問題。歷史原因不需要寫具體客戶,只要寫清楚場景和不能改動的原因。
四、技術(shù)架構(gòu):讓人知道系統(tǒng)由哪些部分組成
要畫出系統(tǒng)整體結(jié)構(gòu),包括前端、后端服務(wù)、數(shù)據(jù)庫、緩存、文件存儲、消息隊列、定時任務(wù)、第三方接口等。每個部分負責(zé)什么,為什么這么設(shè)計,有沒有替代方案,都可以簡要說明。
目錄結(jié)構(gòu)也要解釋,不要只貼目錄樹,要說明每個目錄放什么,新增功能應(yīng)該放在哪里,哪些目錄不建議手動修改。對于前端項目,要說明路由組織方式、狀態(tài)管理方式、接口封裝位置、公共組件使用規(guī)范。對于后端項目,要說明分層結(jié)構(gòu)、接口規(guī)范、統(tǒng)一返回格式、異常處理方式、日志記錄位置。
如果系統(tǒng)有定時任務(wù),一定要單獨列出執(zhí)行時間、執(zhí)行內(nèi)容、失敗是否重試、重復(fù)執(zhí)行會不會造成數(shù)據(jù)異常。很多線上事故來自定時任務(wù)被誤開或者重復(fù)跑。