原創 無忌 得物技術 2022-06-06 18:29 發表于上海

接手新項目或者階段性切換項目開發再或者翻閱社區項目時，快速run起來的技能方式通常是閱讀項目下的名為 README.md文檔所得。

前面所述僅僅是萬裡長征的第一步，當你想了解項目所使用的技術棧、組件庫、工具庫等等一些開發所需物料時，翻閱依賴管理文件的三方包或者業務代碼模塊時，往往結果也是比較懵圈的，一個穩定運行的項目倉庫伴随着業務的增長以及技術的更新升級換代，有可能其中包含多種相似物料庫，如 element UI、antd-vue、自研組件庫等并存情況下，如何取舍與避坑是未知的。

依據需求開發時項目中所包含的目錄結構是如何劃分的，當前業務模塊應當存放的目錄該不該随意存放；開發中所用到的工具在現有的工具箱内是否具備，新增加會不會存在重複造輪子；該業務闆塊的相關負責人如何查找，各個環境的訪問的域名是哪個，開發提測發布應用名叫什麼，接口權限或菜單的配置又是哪個系統，登錄該系統一直提示尚無權限找誰開通等等這些，不勝枚舉的阻力相信各位讀者都是過來人，皆可産生共鳴。

• 降低初次項目 run 起時遇到問題的幾率，各種權限申請、各個環境下的系統地址訪問、功能開發目錄存放、項目所需物料的詢問、查詢、溝通與聯調時代理配置的成本；
• 提升需求專注度，将精力用在需求解讀與實現，利用一份避坑指南；
• 提升可維護性：保持開發環境配置一緻性。

旨在幫助業務項目文檔書寫指導

項目名稱作為我們認識新項目的首要關注點，對于一些項目倉庫的創建時常遇到隻有幾個字母之差，但業務完全不關聯或非需求涉及的項目，這對于一個新手會造成誤解，因此名稱也更能明确我們在衆多倉庫搜索目标庫的一個較重要的參考。

(1)運行準備

由于一些新老業務項目并存情況及nodejs@version版本更新發布之快，運行不同項目常常出現因默認使用版本差異，導緻切換項目運行後控制台報錯。

依H5前端項目來講、從Git 倉庫 down 下拉後，潛意識中是執行依賴包安裝 npm或者yarn因為那是運行項目的必要前提；因此需注明當前項目所使用的包管理工具類型，避免因慣性思維采用不匹配的管理工具耗費過長時間後驚奇的發現用錯了，此時的心情便是這世間最讓人抓狂的等待，消磨人性的暗黑時刻。

H5前端目前主流及為人所知的分别是 React、Vue、Angular等，必要的技術棧說明能給人一種實現功能思路切換的時間，因為這裡面牽涉到UI組件庫選型是 Antd-*、 Element-ui 或者其他主流組件庫，在開發需求時也能夠為開發前明确是否需要花費時間來做些技術儲備、需求是否需評估額外時間。

通常C端産品是不需要進行菜單&接口路由配置，但對于B端系統，往往需進行菜單配置，為了能夠準确無誤的将所完成的功能進行提測以及發布生産，大多數情況下是需要自己進行菜單、接口路由配置，但新手如何才能快速的了解配置渠道及需配置系統權限的申請，最好可以給配置文檔直達鍊接，遇到權限、配置問題時，明确可尋求支持同學，降低對新手所帶來的損傷。

為了保證代碼風格統一、提前告知開發當前項目需執行哪些配置、關閉IDE什麼插件等，避免出現使用IDE 格式化插件與項目 ESLint 風格沖突，導緻運行時出現一堆讓人抓狂的爆紅提示。

(2)項目啟動

針對于需通過 SSO 權限身份驗證的場景，大多數是通過驗證根域名的合法性進行授權，此種情形需在本地 hosts 文件綁定 localhost 到指定域名下，以便在開發時正常獲取驗證身份。

通常是通過 yarn dev / npm run dev 方式進行默認的本地開發，但不同業務系統所要求存在差異，因需配合後端以及不同項目的要求有所區分，明确的說明可降低啟動時的多環境重試或詢問的成本。

對于一個新項目或新業務，再需求prd 或評審時講到參照哪哪模塊，對于此時的新手是盲目的，不知該如何查看該模塊現狀是，因此對于産品的直達鍊接顯得尤為重要，因為這是一個可快速訪問的入口。

大多數情況下開發時都多多少少的因環境不穩定、環境被緊急占用或涉及到其他域的訪問，是有必要進行接口代理配置的，一個清晰明了便捷的配置姿勢以及目錄顯得格外的迫切。

(3)目錄劃分

展現形式：Markdown 樹狀結構，借助工具 tree 生成。

對于項目業務模塊的劃分說明也是不可或缺的重要組成部分，因為當要進行相應的業務模塊功能開發時，是需要知道是該相關模塊否存在、以及存放的位置，可使得後人快速定位；對對應模塊進行相應操作或疊代。

基于不斷的版本升級疊代，符合具體業務的場景的公共部分被逐漸的抽離，作為項目的公共資源 e.g. 各種組件、工具庫、網絡庫等部分，明确的标注避免新手重複造輪子。

(4)SDK文檔

對于一些非社區主流資源的引入，比如組内或小衆的二方、三方資源的采用，建議給文檔進行貼入文檔内，以便開發或排查問題時能夠快速的去翻閱文檔，避免在一些非科學上網的情況下出現無迹可尋。

(5)避坑指南

大多數人較少經曆開發時皆為全新架構、版本的新啟動項目，因此對于所涉及的項目所采用的資源包存在曆史原因等特殊場景，期間解決問題的思路、踩過的坑等寶貴的曆程與經驗的記錄，能幫助後人避免類似的情況發生；

(6)項目部署

持續集成比較重要的一環是将功能進行部署，而此時懷揣着激動的小手準備發布時，發現不知是那扇門，所以一個清晰明了的應用名與直達發布系統的鍊接顯得讓人格外的期待。

(7)監控告警

軟件工程發展至今已進入打磨階段，一個軟件産品還處于裸奔的時代已基本一去不複返，因此對于在測試驗收時的有限場景下問題修複完畢的情況下，便是進行生産真實用戶場景下運行健康狀态的觀察、此時可明确該項目已接入的監控；

業務域：清楚講述項目所屬業務域、幫助快速樹立業務印象，結合該業務下各版本功能說明文檔，将有助開發同學對于業務的背後的業務價值有初步的理解；

疊代方式：依據不同的業務采用的需求疊代方式存在一些差異，有項目制的、敏捷開發方式，對于不同的疊代方式所采用的節奏也有所不同；推動項目落實的方式有産品驅動或PMO方式，目前大多數為後者，在得物采用更為高效的系統RDC，其具備從MRD、PRD、評審、排期、任務分配、風險把控、人力資源等等精細化運作方式，将需求落地以流水線式的完成及把控等能力；

相關人員：将項目所涉及人員進行維護在項目内、不定時更新，在有需求或排查問題時能夠幫助快速找到相關同學進行支持，至少大多數時也能讓你幫你找到對應功能點當時有參與或了解的同學，提升溝通效率等好處。

項目文檔是對于項目一個快速了解的一個最好方式，能從中獲取到其是所服務的業務，參與開發所具備的知識體系，開發前所需做哪些準備，遇到問題時能聯系到對應的同學，不僅能幫助新手快速上手，同時也有助于多個項目并行時，相互之間進行切換起到溫故的效果；總之一個優秀項目文檔不僅僅要讓團隊組員看得懂、用得順手，也需要讓其他成員看得懂、做得出才方可發揮其潛在價值。

*文/無忌

關注得物技術，每周一三五晚18:30更新技術幹貨要是覺得文章對你有幫助的話，歡迎評論轉發點贊～