1. 項(xiàng)目概述為什么我們需要開(kāi)放的代碼審查先說(shuō)結(jié)論open-code-review 不是什么高深莫測(cè)的框架它是一套把 code review 從走流程變成沉淀技術(shù)資產(chǎn)的工程實(shí)踐方案。我把它理解成三件事的組合一套開(kāi)放的審查規(guī)則模板、一套能落地的工具鏈配置、一種讓團(tuán)隊(duì)愿意持續(xù)執(zhí)行的協(xié)作文化。三樣缺一不可——規(guī)則寫(xiě)得再漂亮工具不配合成員不買(mǎi)賬最終還是會(huì)回到review 就是點(diǎn)個(gè) approve的老路上。最早意識(shí)到這個(gè)問(wèn)題是在一個(gè)十二人左右的后端團(tuán)隊(duì)。當(dāng)時(shí)我們每個(gè) PR 都有至少兩個(gè) reviewer看起來(lái)流程很完備但版本發(fā)出去之后 bug 率并沒(méi)有明顯下降。我抽了幾個(gè)典型事故反向追蹤發(fā)現(xiàn)這些 bug 所在代碼在 review 階段全都被看過(guò)而且都被Approved了。問(wèn)題出在哪reviewer 根本沒(méi)看懂改動(dòng)意圖或者說(shuō)沒(méi)意識(shí)到自己應(yīng)該對(duì)什么負(fù)責(zé)。大家只是機(jī)械地打開(kāi) diff掃一眼有沒(méi)有明顯的語(yǔ)法錯(cuò)誤、有沒(méi)有和現(xiàn)有風(fēng)格沖突就點(diǎn)了通過(guò)。這不是某個(gè)人的問(wèn)題是整個(gè)團(tuán)隊(duì)的 review 價(jià)值觀出了問(wèn)題。后來(lái)我們花了大概兩個(gè)迭代的周期把 code review 從審批動(dòng)作改成了協(xié)作過(guò)程查閱了大量公開(kāi)的最佳實(shí)踐資料也結(jié)合我們自己的業(yè)務(wù)特點(diǎn)逐步整理出了一套我們內(nèi)部稱為open-code-review的方案。這套方案最核心的變化是兩個(gè)第一把 review 的標(biāo)準(zhǔn)從代碼能不能跑提升到代碼該不該這么寫(xiě)第二把 review 這個(gè)動(dòng)作從 PR 提出后的階段前移到了開(kāi)發(fā)過(guò)程中的每個(gè)關(guān)鍵決策點(diǎn)。為什么要強(qiáng)調(diào)開(kāi)放因?yàn)橛行У?code review 本質(zhì)上是一種知識(shí)共享和風(fēng)險(xiǎn)共擔(dān)機(jī)制如果審查過(guò)程封閉、標(biāo)準(zhǔn)藏在某幾個(gè)資深成員腦子里、結(jié)論靠拍腦袋那它就不可能穩(wěn)定地發(fā)揮作用。開(kāi)放的審查標(biāo)準(zhǔn)、開(kāi)放的流程模板、開(kāi)放的自動(dòng)檢查規(guī)則才能讓新成員快速進(jìn)入角色讓資深成員把精力放在真正需要人類判斷的地方。這套方案適合誰(shuí)適合所有正在用 GitHub、GitLab 這類平臺(tái)做協(xié)作開(kāi)發(fā)的團(tuán)隊(duì)尤其是那種幾十人規(guī)模、正在從能干活往干得穩(wěn)轉(zhuǎn)變的中小型團(tuán)隊(duì)。也適合那些一個(gè)人維護(hù)多個(gè)開(kāi)源倉(cāng)庫(kù)的獨(dú)立開(kāi)發(fā)者——你同樣需要一套標(biāo)準(zhǔn)來(lái)控制外人提交進(jìn)來(lái)的代碼質(zhì)量。如果你剛帶團(tuán)隊(duì)可以從這套方案的流程部分直接抄如果你本身是團(tuán)隊(duì)成員想讓 review 不再流于形式這篇文章里的檢查清單和模板也能幫你在下一次 review 時(shí)立刻用上。2. 整體設(shè)計(jì)與核心思路從審批轉(zhuǎn)向協(xié)作2.1 傳統(tǒng) code review 為什么失靈在深入講 open-code-review 的設(shè)計(jì)之前先花點(diǎn)時(shí)間搞清楚一個(gè)根本問(wèn)題為什么很多團(tuán)隊(duì)的 review 像走過(guò)場(chǎng)我觀察到的第一個(gè)原因是 review 的定位錯(cuò)了。很多團(tuán)隊(duì)把 Code Review 當(dāng)成質(zhì)量門(mén)禁PR 不經(jīng)過(guò) reviewer 的 approve 就不能合入這導(dǎo)致雙方的心態(tài)都扭曲了。提交方想的不是我需要你的意見(jiàn)而是我要說(shuō)服你放行審查方想的也不是我?guī)湍惆言O(shè)計(jì)弄扎實(shí)而是我要找茬找不出茬來(lái)顯得我沒(méi)水平。這種對(duì)抗性關(guān)系下review 變成了辯論賽而不是設(shè)計(jì)討論會(huì)。第二個(gè)原因是審查的時(shí)間點(diǎn)太晚了。絕大多數(shù)團(tuán)隊(duì)是在代碼寫(xiě)完之后才開(kāi)始 review這時(shí)候大的設(shè)計(jì)問(wèn)題已經(jīng)定型了。一個(gè)人悶頭寫(xiě)了五天起了個(gè)不太合理的抽象層第五天晚上發(fā)了個(gè)八百行的 PRreviewer 就算看出來(lái)抽象層設(shè)計(jì)有問(wèn)題面對(duì)已寫(xiě)完的代碼心想的也是改起來(lái)成本太高算了算了最后只提點(diǎn)小意見(jiàn)放行。結(jié)果就是結(jié)構(gòu)性的缺陷永遠(yuǎn)帶著先發(fā)優(yōu)勢(shì)混進(jìn)主干。第三個(gè)原因是審查標(biāo)準(zhǔn)模糊。我問(wèn)過(guò)我們團(tuán)隊(duì)的人你 review 的時(shí)候到底在看什么答案五花八門(mén)。有人看命名、有人看性能、有人只關(guān)心有沒(méi)有 TODO 沒(méi)刪干凈。不是他們不負(fù)責(zé)是沒(méi)有人告訴過(guò)他們什么樣的 code review 才算到位。在沒(méi)有統(tǒng)一標(biāo)準(zhǔn)的情況下review 質(zhì)量完全依賴個(gè)人經(jīng)驗(yàn)和直覺(jué)而個(gè)人經(jīng)驗(yàn)和直覺(jué)是最難復(fù)制、最不可靠的東西。2.2 開(kāi)放式的三層審查模型所以 open-code-review 的設(shè)計(jì)基點(diǎn)是把 review 拆成三個(gè)層次每個(gè)層次有明確的目標(biāo)、時(shí)間點(diǎn)和參與人。第一層叫設(shè)計(jì)評(píng)審發(fā)生在寫(xiě)代碼之前。哪怕只是變更一個(gè)內(nèi)部服務(wù)接口也應(yīng)該先說(shuō)清楚這次的改動(dòng)邊界。怎么實(shí)現(xiàn)不需要正式會(huì)議只需要在 PR 描述里寫(xiě)一段設(shè)計(jì)背景 方案選擇 為什么這么選然后丟一兩句給相關(guān)同事看一眼。這個(gè)動(dòng)作成本極低但能避免大量寫(xiě)到一半發(fā)現(xiàn)方向錯(cuò)了的情況。我們最開(kāi)始做的時(shí)候也覺(jué)得麻煩后來(lái)慢慢養(yǎng)成了習(xí)慣形成了一種共識(shí)如果一段改動(dòng)涉及跨服務(wù)調(diào)用或者數(shù)據(jù)模型變化必須先把方案說(shuō)清楚再動(dòng)手寫(xiě)。第二層是差異審查就是大多數(shù)人理解的 code review發(fā)生在 PR 提出之后。這個(gè)層級(jí)的核心不是放大鏡逐行看而是帶著問(wèn)題清單去看。問(wèn)題清單不是我自己拍腦袋想的而是收集了團(tuán)隊(duì)里幾乎所有歷史事故和低質(zhì)量代碼的共性問(wèn)題總結(jié)成了一份結(jié)構(gòu)化的 checklist后面我會(huì)有專門(mén)的章節(jié)講這份清單的細(xì)節(jié)。簡(jiǎn)單說(shuō)它覆蓋了正確性、可維護(hù)性、性能、安全、測(cè)試五個(gè)維度每個(gè)維度下有具體可回答的問(wèn)題reviewer 只需要對(duì)照著過(guò)一遍。第三層是持續(xù)改進(jìn)發(fā)生在合入之后。每個(gè)迭代末我們會(huì)把這一期間通過(guò) review 合入的代碼中后來(lái)出問(wèn)題的部分拉出來(lái)復(fù)盤(pán)看是 review 過(guò)程中漏掉了還是當(dāng)時(shí)根本沒(méi)有相關(guān)標(biāo)準(zhǔn)。如果是后者就補(bǔ)充進(jìn)入清單讓下一輪 review 的標(biāo)準(zhǔn)更強(qiáng)。這聽(tīng)起來(lái)很玄但我可以負(fù)責(zé)任地說(shuō)這個(gè)循環(huán)跑三輪之后團(tuán)隊(duì)整體的代碼質(zhì)量就會(huì)有肉眼可見(jiàn)的提升。這個(gè)三層模型最大的好處是把 code review 從一個(gè)人人都能敷衍了事的質(zhì)量檢查動(dòng)作變成了一套有節(jié)奏、有工具、有反饋的質(zhì)量協(xié)作流程。它不是某個(gè)人聰明而是系統(tǒng)性地讓每個(gè)參與者都更容易做對(duì)事。2.3 工具的定位人機(jī)分工的邊界工具在 open-code-review 里承擔(dān)的角色不是替代人的判斷而是把人從重復(fù)勞動(dòng)里解放出來(lái)。我在設(shè)計(jì)工具鏈時(shí)有一個(gè)原則所有不需要人類判斷力就能發(fā)現(xiàn)的問(wèn)題一律交給自動(dòng)檢查所有需要設(shè)計(jì)權(quán)衡、業(yè)務(wù)上下文、長(zhǎng)期演進(jìn)視角的問(wèn)題才值得人類 review。這里有個(gè)很重要的邊界問(wèn)題。比如代碼風(fēng)格這完全是機(jī)械判斷eslint、gofmt 這類工具看一眼就知道合不合規(guī)為什么要浪費(fèi) reviewer 的精力再比如 API 兼容性檢查、已知漏洞依賴掃描這明顯超出普通成員的知識(shí)范圍也應(yīng)該由機(jī)器人來(lái)做。真正需要人類 review 的是什么是這段改動(dòng)的抽象是否合理、接口設(shè)計(jì)是否穩(wěn)健、異常處理是否考慮到了業(yè)務(wù)邊界、測(cè)試是否覆蓋了真正有風(fēng)險(xiǎn)的路徑。這個(gè)邊界的劃分還直接影響一個(gè)數(shù)字一個(gè) PR 平均需要多少分鐘的人工 review 時(shí)間。我們團(tuán)隊(duì)在沒(méi)有自動(dòng)化工具時(shí)平均每個(gè) PR 的 review 耗時(shí)大約是 28 分鐘其中大概有一半時(shí)間花在了風(fēng)格討論和明顯可以自動(dòng)判斷的問(wèn)題上。接入工具鏈之后每個(gè) PR 的 review 時(shí)間降到了 15 分鐘左右而且剩余時(shí)間里討論的內(nèi)容質(zhì)量明顯更高了。2.4 為什么開(kāi)放兩個(gè)字這么重要我反復(fù)強(qiáng)調(diào)開(kāi)放不是概念包裝而是有實(shí)際原因的。把審查標(biāo)準(zhǔn)、清單、模板、工具配置全部放在團(tuán)隊(duì)的文檔庫(kù)里任何成員都能打開(kāi)看都會(huì)知道我的代碼提交后會(huì)按照什么標(biāo)準(zhǔn)被評(píng)審這在心理層面就已經(jīng)改變了成員的編碼方式。我見(jiàn)過(guò)太多團(tuán)隊(duì)成員在提交代碼前根本不知道會(huì)被怎么評(píng)價(jià)于是提交的時(shí)候只憑自己的直覺(jué)猜測(cè)什么算好代碼結(jié)果 review 的時(shí)候被批得體無(wú)完膚時(shí)間長(zhǎng)了要么擺爛要么逆反。開(kāi)放還有一個(gè)更實(shí)際的價(jià)值降低新成員的上手成本。我們團(tuán)隊(duì)曾經(jīng)加入過(guò)一個(gè)剛從學(xué)校畢業(yè)的工程師第一個(gè)月寫(xiě)的代碼平均每個(gè) PR 打回三到四次不是因?yàn)樗讲疃且驗(yàn)闆](méi)有人告訴過(guò)她什么算過(guò)得了 review 的代碼。后來(lái)我們把 checklist 直接發(fā)給她讓她在提交之前自己先過(guò)一遍打回率馬上從四次降到了不足一次。這不是什么玄學(xué)純粹是標(biāo)準(zhǔn)透明了人的行為就會(huì)自動(dòng)往標(biāo)準(zhǔn)上靠。所以open-code-review 里的open指的既不是某個(gè)開(kāi)源軟件的名字也不是說(shuō)所有倉(cāng)庫(kù)都要公開(kāi)而是說(shuō)審查的規(guī)則、流程、標(biāo)準(zhǔn)、工具對(duì)每個(gè)參與者透明可見(jiàn)。你可以把這個(gè)理解為團(tuán)隊(duì)里的每一次 code review都是在按照一份所有人都看得見(jiàn)的公開(kāi)契約進(jìn)行。3. 核心細(xì)節(jié)與實(shí)操要點(diǎn)一份能直接用的 Review 清單3.1 五個(gè)審查維度的設(shè)計(jì)邏輯接下來(lái)是整篇博客里最值得抄作業(yè)的部分一份我在實(shí)際團(tuán)隊(duì)里打磨過(guò)的 code review 檢查清單。它分成五個(gè)維度每個(gè)維度下有一組可以直接回答是/否的問(wèn)題。正確性維度上的核心是狀態(tài)變更的完整性。讀了代碼之后我會(huì)問(wèn)自己幾個(gè)問(wèn)題這個(gè)改動(dòng)改變了哪些狀態(tài)所有狀態(tài)都有對(duì)應(yīng)的更新路徑嗎有沒(méi)有可能走到中間狀態(tài)舉個(gè)典型例子更新用戶密碼的功能只改了數(shù)據(jù)庫(kù)字段卻沒(méi)有清理緩存里的舊密碼這就是典型的狀態(tài)更新遺漏。這類 bug 靠編譯器發(fā)現(xiàn)不了靠測(cè)試可能也發(fā)現(xiàn)不了如果測(cè)試直接查庫(kù)而不是走緩存只能靠 review 時(shí)對(duì)狀態(tài)流轉(zhuǎn)的推演?？删S護(hù)性關(guān)注的不是今天能不能用而是三個(gè)月后別人能不能改。我會(huì)看新增的抽象是讓代碼更簡(jiǎn)單了還是引入了一層不必要的間接改動(dòng)是遵循了文件里已有的模式還是為了滿足某個(gè)個(gè)性化偏好另起爐灶方法長(zhǎng)度和職責(zé)劃分合理嗎命名是否名副其實(shí)還是起了個(gè)managerutil這種含混的名字強(qiáng)行糊弄過(guò)去性能審查不是讓你去摳每個(gè)循環(huán)的微優(yōu)化而是關(guān)注有沒(méi)有明顯的數(shù)量級(jí)問(wèn)題。比如這段邏輯有沒(méi)有把原本 O(n) 的操作寫(xiě)成 O(n2)有沒(méi)有在循環(huán)里發(fā) SQL 查詢有沒(méi)有對(duì)熱點(diǎn)路徑增加無(wú)謂的開(kāi)銷如果改動(dòng)涉及接口響應(yīng)體是不是比原來(lái)大了很多這些才是 review 階段值得關(guān)注的問(wèn)題至于臨時(shí)變量的分配方式、字符串拼接的細(xì)節(jié)交給 profiler 去管。安全審查要看的不是滲透測(cè)試那種攻防對(duì)抗而是常見(jiàn)的低級(jí)漏洞模式用戶輸入有沒(méi)有被校驗(yàn)就拼進(jìn) SQL 或 HTML權(quán)限檢查是放在了前端還是后端敏感信息有沒(méi)有被打進(jìn)日志有沒(méi)有新增的外部依賴存在已知漏洞這些問(wèn)題的答案在很大程度上決定了代碼合入后會(huì)不會(huì)變成事故的導(dǎo)火索。測(cè)試維度的核心是風(fēng)險(xiǎn)覆蓋和有效性的平衡。有沒(méi)有為核心邏輯補(bǔ)充單測(cè)新增的測(cè)試是在驗(yàn)證真實(shí)行為還是在為了覆蓋率數(shù)字而寫(xiě)斷言失敗路徑有沒(méi)有被測(cè)試到異常分支是否被覆蓋我要重點(diǎn)說(shuō)明的是我見(jiàn)過(guò)太多團(tuán)隊(duì)測(cè)試覆蓋率 80% 以上、能跑的業(yè)務(wù)測(cè)試占比卻很低的情況。寫(xiě)測(cè)試的時(shí)候如果用make sure it works的心態(tài)出來(lái)的測(cè)試就是典型的無(wú)效資產(chǎn)。3.2 關(guān)于 PR 規(guī)模的量化經(jīng)驗(yàn)還有一個(gè)經(jīng)常被忽視、但實(shí)際影響體驗(yàn)和質(zhì)量的參數(shù)PR 的大小。我個(gè)人的經(jīng)驗(yàn)供參考一次性合入的 PR去掉鎖文件、生成文件之后代碼變更應(yīng)該控制在 200 到 400 行之間寧可拆分成多個(gè)小 PR也別壓成一個(gè)巨型 PR。這個(gè)觀察有研究數(shù)據(jù)佐證——有研究者分析過(guò)大量 pull request 數(shù)據(jù)后發(fā)現(xiàn)超過(guò) 400 行的 PRreview 效果會(huì)明顯下降而 200 行左右的 PR 最容易獲得高質(zhì)量反饋。如果你做了一個(gè)超過(guò) 800 行的改動(dòng)最需要做的不是硬著頭皮發(fā) PR而是先自己?jiǎn)栆痪溥@個(gè)改動(dòng)真的只能一次做完嗎90% 的情況下答案是可以拆的?？梢园凑者壿嫴襟E拆成先引入抽象接口再遷移舊調(diào)用方最后刪除舊實(shí)現(xiàn)三個(gè)順序 PR每個(gè) PR 單獨(dú)可合入、可回滾review 起來(lái)也更輕松。我還在團(tuán)隊(duì)里定了兩個(gè)死規(guī)矩一個(gè)是鎖文件或構(gòu)建生成物單獨(dú)提交不混進(jìn)功能主改動(dòng)里另一個(gè)是格式化、重命名這類純重構(gòu)操作要么單獨(dú)一個(gè) PR要么在描述里顯著標(biāo)注本 PR 不含邏輯變更否則 reviewer 會(huì)花好幾輪去辨別哪些是真正有業(yè)務(wù)影響的改動(dòng)。3.3 好 PR 描述長(zhǎng)什么樣PR 描述是整個(gè) review 環(huán)節(jié)里被低估得最厲害的部分。一個(gè)好的 PR 描述相當(dāng)于把上下文直接塞進(jìn) reviewer 腦子里讓 ta 不用從零開(kāi)始猜你為什么要這么改。我習(xí)慣的模板是固定的背景業(yè)務(wù)上為什么要做這個(gè)改動(dòng)有沒(méi)有對(duì)應(yīng)的 issue 或需求單方案技術(shù)上的實(shí)現(xiàn)思路是什么為什么選這個(gè)方案不選另一個(gè)影響面改了哪些模塊有沒(méi)有可能影響其他功能測(cè)試計(jì)劃自己測(cè)過(guò)什么測(cè)試覆蓋率有沒(méi)有變化驗(yàn)證截圖或日志如果涉及 UI 或接口行為提供退出證據(jù)。這個(gè)模板不是我從網(wǎng)上抄的而是我們從幾個(gè)月的實(shí)踐里總結(jié)出來(lái)的。填過(guò)幾次之后你就會(huì)發(fā)現(xiàn)寫(xiě)清楚這五部分的 PRreviewer 的回復(fù)質(zhì)量和速度都會(huì)上一個(gè)臺(tái)階。因?yàn)?ta 能快速聚焦到你的方案對(duì)不對(duì)而不是花時(shí)間理解你要解決什么問(wèn)題。下面是一個(gè)簡(jiǎn)化的、可直接復(fù)制使用的 PR 描述模板## 背景 這里寫(xiě)業(yè)務(wù)需求和背景附上相關(guān) issue 鏈接 ## 方案 這里寫(xiě)技術(shù)實(shí)現(xiàn)思路如果有多方案對(duì)比也寫(xiě)出來(lái) ## 影響面 - 影響的服務(wù)/模塊 - 依賴是否存在破壞性變更 - 需要重點(diǎn)回歸的功能 ## 測(cè)試 - 單元測(cè)試覆蓋了 XX 場(chǎng)景覆蓋率從 XX% 變?yōu)?XX% - 手工測(cè)試在本地/測(cè)試環(huán)境驗(yàn)證了 XX 流程 - 風(fēng)險(xiǎn)點(diǎn)XX 場(chǎng)景暫時(shí)沒(méi)有覆蓋原因 XX ## 驗(yàn)證證據(jù) 截圖或日志粘貼區(qū)3.4 開(kāi)源協(xié)議與合規(guī)檢查當(dāng)你的團(tuán)隊(duì)在代碼庫(kù)里使用了第三方開(kāi)源組件code review 清單里還應(yīng)該增加一個(gè)容易被忽略的維度開(kāi)源協(xié)議合規(guī)。我們團(tuán)隊(duì)曾經(jīng)在一個(gè) SDK 的依賴樹(shù)里發(fā)現(xiàn)了一個(gè) MPL-2.0 協(xié)議的庫(kù)而我們當(dāng)時(shí)的產(chǎn)品閉源交付如果不做規(guī)避處理會(huì)帶來(lái)不必要的協(xié)議風(fēng)險(xiǎn)。后來(lái)我們就把新增第三方依賴時(shí)必須檢查其開(kāi)源協(xié)議寫(xiě)進(jìn)了 review 清單并且在 CI 里加入了一個(gè)基礎(chǔ)的 license-check 步驟凡是新增依賴但協(xié)議不明或與公司分發(fā)方式?jīng)_突的直接通報(bào)提醒。這個(gè)細(xì)節(jié)看起來(lái)跟日常業(yè)務(wù)功能開(kāi)發(fā)無(wú)關(guān)但它真實(shí)存在于所有工程師的協(xié)作現(xiàn)場(chǎng)而且是不開(kāi)放就給大爺們埋雷的典型例子——如果審查標(biāo)準(zhǔn)不透明new grad 根本不會(huì)知道自己在不知情的情況下引入了一個(gè)協(xié)議風(fēng)險(xiǎn)。4. 實(shí)操過(guò)程工具鏈配置與自動(dòng)化落地4.1 檢查工具的最小可用組合如果說(shuō)清單是 open-code-review 的軟件那一組趁手工具就是它的硬件。我強(qiáng)烈建議團(tuán)隊(duì)至少配置三類工具代碼風(fēng)格檢查工具、靜態(tài)分析工具和測(cè)試覆蓋報(bào)告工具。代碼風(fēng)格檢查工具的選擇取決于技術(shù)棧前端用 eslint prettierPython 用 ruffGo 用 gofmt golangci-lintJava 用 Checkstyle 加 SpotBugs。這類工具不需要人工判斷就應(yīng)該作為 CI 的第一道門(mén)卡住。我在團(tuán)隊(duì)里的做法是把 eslint 和 prettier 的檢查直接掛到 pre-commit hook 上問(wèn)題在本地就能改掉不用等 CI 跑掛了再回來(lái)看一眼 diff。靜態(tài)分析工具的選擇就要稍微講究一些因?yàn)樗恼`報(bào)率比風(fēng)格工具要高。我傾向于先開(kāi)一個(gè)保守的規(guī)則集跑一兩個(gè)迭代之后根據(jù)誤報(bào)情況逐步放寬或收緊。不要第一天就開(kāi)到最嚴(yán)格模式不然團(tuán)隊(duì)成員一天到晚都在應(yīng)付誤報(bào)對(duì)工具本身的信任感會(huì)下降。測(cè)試覆蓋報(bào)告工具的核心不是覆蓋率數(shù)字本身而是新增代碼覆蓋率這個(gè)指標(biāo)。GitHub 有一款 free 的 coverage report 插件可以在 PR 上自動(dòng)評(píng)論新增代碼的覆蓋率變化。我使用它的經(jīng)驗(yàn)是覆蓋率的硬性閾值設(shè)為 80% 比較合理但真正要緊的不是全局覆蓋率而是新代碼的覆蓋不能比原有代碼低太多。4.2 在 GitHub Actions 里搭一個(gè)自動(dòng)化評(píng)審工作流工具鏈的落地最直觀的方式是在 GitHub Actions 里編排。我分享一個(gè)我實(shí)際用過(guò)的、可復(fù)用的 workflow 片段邏輯是提交 PR 后至少跑四道自動(dòng)檢查——語(yǔ)法、lint、測(cè)試、構(gòu)建。如果基礎(chǔ)檢查全過(guò)了再跑靜態(tài)分析和服務(wù)級(jí)別的冒煙測(cè)試。這個(gè) workflow 不是讓機(jī)器人真的代替人做 review而是把重復(fù)勞動(dòng)前置讓人把時(shí)間花在更重要的事上。name: ci on: pull_request: types: [opened, synchronize, reopened] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Run lint run: npm run lint test: runs-on: ubuntu-latest needs: lint steps: - uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Run unit tests run: npm run test:coverage build: runs-on: ubuntu-latest needs: test steps: - uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Build run: npm run build這套流程的價(jià)值在于任何一個(gè) PR 在進(jìn)入人工 review 之前先經(jīng)過(guò)一個(gè)完全確定性的自動(dòng)檢查階段。這臺(tái)機(jī)器上能過(guò)這種扯皮問(wèn)題在 CI 檢查面前徹底消失reviewer 拿到手的就是一個(gè)已經(jīng)能用、只是還沒(méi)討論設(shè)計(jì)好壞的 PR。實(shí)測(cè)下來(lái)這套流程把無(wú)效討論時(shí)間壓縮了至少三分之一剩下的都是真正需要人類見(jiàn)解的決策。如果你是 GitLab 用戶原理一樣只是在.gitlab-ci.yml里寫(xiě)成 stages 結(jié)構(gòu)。工具不同但設(shè)計(jì)思想完全是一套。4.3 用機(jī)器人處理人類不該看的噪音除了基礎(chǔ) CI我還引入了另一類工具review 機(jī)器人。這類工具的核心作用是把大量重復(fù)性、機(jī)械性的審查結(jié)論自動(dòng)貼在 PR 評(píng)論里節(jié)省人類的注意力。我當(dāng)時(shí)選了 danger.js 這類方案它的好處是用 JavaScript 就可以寫(xiě)檢查規(guī)則團(tuán)隊(duì)成員學(xué)習(xí)成本極低。我們給它布了幾條規(guī)則PR 描述缺失時(shí)自動(dòng)提醒提交者補(bǔ)充鎖文件和依賴文件有變更時(shí)注明需要人工復(fù)核超過(guò) 400 行的 PR自動(dòng)打上建議拆分為更小 PR的提示。這些規(guī)則都極其簡(jiǎn)單但很實(shí)際因?yàn)樗鼈兇_保的人類的注意力不會(huì)被瑣碎檢查消耗掉。下面是 danger.js 的一個(gè)示例配置片段// dangerfile.js import { danger, fail, markdown, warn } from danger; import { readFileSync } from fs; const pr danger.github.pr; const additions pr.additions; const changes pr.changed_files; // 1. 描述是否為空白或過(guò)于簡(jiǎn)短 if (!pr.body || pr.body.length 30) { fail(請(qǐng)補(bǔ)充 PR 描述至少說(shuō)明背景和測(cè)試計(jì)劃); } // 2. 大 PR 預(yù)警 if (additions 400) { warn(這個(gè) PR 新增了 ${additions} 行代碼超過(guò) 400 行建議拆分成更小的子 PR。); } else if (additions 800) { fail(新增代碼超過(guò) 800 行請(qǐng)拆分后再提交。); } // 3. 鎖文件變更和依賴變化提醒 const packageFiles new Set([ package-lock.json, yarn.lock, pnpm-lock.yaml, requirements.txt, go.mod, go.sum ]); const changedPackageFiles danger.git.modified_files.filter((f) packageFiles.has(f) ); if (changedPackageFiles.length 0) { markdown(檢測(cè)到依賴文件變更請(qǐng)人工確認(rèn)沒(méi)有引入新的安全風(fēng)險(xiǎn)。); } // 4. 檢查新增代碼是否附帶測(cè)試文件 const addedCodeFiles danger.git.created_files.filter((f) /\.(ts|js|go|py)$/.test(f) !/\.test\.|\.spec\./.test(f) ); const addedTestFiles danger.git.created_files.filter((f) /\.test\.|\.spec\./.test(f) ); if (addedCodeFiles.length 0 addedTestFiles.length 0) { warn(新增代碼文件沒(méi)有配套的新增測(cè)試文件。); }這套機(jī)器人規(guī)則我們跑了半年最大的收益不是省下了多少時(shí)間而是讓提交一個(gè)體面的 PR變成了一個(gè)自動(dòng)被檢查的顯式要求而不是靠某個(gè)人反復(fù)在群里苦口婆心地提醒。4.4 人機(jī)分工的邊界怎么定才算合理工具鏈配好了還有一個(gè)新問(wèn)題自動(dòng)檢查和人肉 review 之間邊界到底劃在哪里我的經(jīng)驗(yàn)是把握一個(gè)原則低風(fēng)險(xiǎn)、高確定性的檢查交給機(jī)器高風(fēng)險(xiǎn)、需要上下文理解的判斷留給人。比如某個(gè)函數(shù)是否多了不必要的抽象機(jī)器很難判斷因?yàn)樗枰肋@個(gè)模塊未來(lái)的演進(jìn)方向但某個(gè)錯(cuò)誤信息是不是包含敏感信息、某個(gè)循環(huán)里是不是查了 N 次數(shù)據(jù)庫(kù)機(jī)器可以檢查出模式也可以把人引到正確的位置上。我們?cè)谶@個(gè)原則下調(diào)整過(guò)好多次機(jī)器人規(guī)則最終穩(wěn)定下來(lái)的一套規(guī)則就只做提醒不做攔截因?yàn)樾问竭^(guò)強(qiáng)的攔截會(huì)破壞團(tuán)隊(duì)對(duì)工具的信任。另外自動(dòng)化檢查在一個(gè) PR 的人工 review結(jié)束后可以再跑一輪差分檢查比如確認(rèn)上一輪 reviewer 提的必須改的注釋是否真的對(duì)應(yīng)修改了——但我們沒(méi)有做那么強(qiáng)的自動(dòng)化因?yàn)楝F(xiàn)在的工具要做到這點(diǎn)還比較笨重我們的做法是依賴 reviewer 自己 revisit 一遍。4.5 把 checklist 做成自動(dòng)化的記憶前面提到的人工 checklist其實(shí)也可以沉淀到工具鏈里。GitHub 的 PR 模板天然支持 checkbox 列表你可以把 checklist 放在 PR 描述模板里讓每個(gè)提交者先勾選自檢再請(qǐng)求 review。這一步成本極低但效果極好。我們的做法是把 checklist 做成 PR 模板的一部分而且嚴(yán)格控制問(wèn)題的數(shù)量——不要超過(guò) 10 個(gè)核心問(wèn)題否則提交者會(huì)機(jī)械性全勾上反而失去自檢的意義。我把我們團(tuán)隊(duì)現(xiàn)用的 PR 模板中最重要的列表寫(xiě)出來(lái)供參考我是否在本地跑通了所有相關(guān)測(cè)試我是否檢查過(guò)新增代碼可能引入的狀態(tài)不一致我是否確認(rèn)新增依賴的開(kāi)源協(xié)議與當(dāng)前分發(fā)方式兼容我是否更新了相關(guān)文檔或注釋我是否在測(cè)試計(jì)劃里覆蓋了失敗路徑我是否檢查過(guò)日志里不會(huì)出現(xiàn)敏感信息5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 PR 太久沒(méi)人 review怎么辦幾乎每個(gè)團(tuán)隊(duì)都會(huì)遇到?jīng)]人在 PR 上及時(shí)反饋的問(wèn)題。這不一定是誰(shuí)不負(fù)責(zé)而是 review 作為異步協(xié)作任務(wù)天然排在各自的開(kāi)發(fā)任務(wù)后面。但也正是因?yàn)樘烊慌旁诤竺嫠驼娴呐诺较轮苋チ?。我的處理?jīng)驗(yàn)是兩條腿走路。第一條是讓沒(méi)人 review這件事變得讓所有人可見(jiàn)。我們?cè)O(shè)了一個(gè)自動(dòng)化規(guī)則PR 發(fā)出 4 小時(shí)后仍沒(méi)有 review 時(shí)機(jī)器人會(huì)把 PR 鏈接轉(zhuǎn)發(fā)到對(duì)應(yīng)的 channel12 小時(shí)后仍沒(méi)有任何 review 動(dòng)態(tài)它會(huì)自動(dòng)提到倉(cāng)庫(kù)的 maintainer。不要小看這個(gè)簡(jiǎn)單的機(jī)制——公開(kāi)可見(jiàn)本身就能帶來(lái)很大的行動(dòng)壓力。第二條是給 review 設(shè)定明確的 SLA 承諾。比如我們約定工作時(shí)間內(nèi) 4 小時(shí)內(nèi)給出首個(gè) response24 小時(shí)內(nèi)完成 review。這里的 response 不一定是完整的 approve也可以是一句我今晚沒(méi)空看明天早上給你看或者我已開(kāi)始看預(yù)計(jì)下午給完整意見(jiàn)。先動(dòng)起來(lái)遠(yuǎn)比徹底看完重要。5.2 reviewer 意見(jiàn)和提交者想法不一致怎么辦review 過(guò)程中最消耗情緒的就是設(shè)計(jì)路線之爭(zhēng)。我見(jiàn)過(guò)一個(gè)典型的 case一個(gè)資深的 reviewer 認(rèn)為某段邏輯應(yīng)該抽成一個(gè) service而提交者認(rèn)為直接寫(xiě)在調(diào)用方更直觀簡(jiǎn)單。兩個(gè)人在 PR 下面來(lái)回刷了十幾條評(píng)論誰(shuí)也沒(méi)說(shuō)服誰(shuí)最后首席工程師介入才平息。我的經(jīng)驗(yàn)是review 意見(jiàn)里涉及風(fēng)格和偏好層面的內(nèi)容應(yīng)該明確標(biāo)注為個(gè)人傾向而不是必須修改。這也意味著在團(tuán)隊(duì)層面要有爭(zhēng)議升級(jí)的機(jī)制——比如當(dāng)某一類的意見(jiàn)反復(fù)出現(xiàn)、且雙方無(wú)法達(dá)成一致時(shí)需要盡快讓更多有相關(guān)經(jīng)驗(yàn)的人參與進(jìn)來(lái)做集體決策。同時(shí)在 review 意見(jiàn)的表述上我要求團(tuán)隊(duì)成員用提議而不是命令式句式例如把這里改成只讀會(huì)不會(huì)更安全而不是你這里必須用 final。同樣是表達(dá)意見(jiàn)前者更容易被當(dāng)作建議理解后者容易產(chǎn)生壓力特別是兩個(gè)字容易在表格和 diff 的上下文里顯得異常刺耳。5.3 新人每次 PR 都被打回很多次感覺(jué)挫敗怎么辦這是個(gè)很真實(shí)的管理挑戰(zhàn)。新人提交代碼被打回太多次會(huì)越來(lái)越不自信甚至開(kāi)始過(guò)度依賴 reviewer 的口頭指導(dǎo)來(lái)寫(xiě)代碼。我們的解法就是把標(biāo)準(zhǔn)完全拆開(kāi)了給 ta。第一步是給新人解釋清楚整個(gè) review 的評(píng)判標(biāo)準(zhǔn)把我們那份 checklist 發(fā)過(guò)去讓 ta 在每次提交前先自評(píng)一遍。第二步是為新成員安排一個(gè)固定的review 伙伴而不是讓 ta 每次面對(duì)不同的 reviewer。這個(gè)伙伴的重要性在于幾次 review 之后 ta 能夠了解這位新人的常見(jiàn)錯(cuò)誤模式給出的反饋會(huì)更有針對(duì)性新人也不會(huì)每次都是從頭面對(duì)一個(gè)陌生人的緊張感。第三步是明確告訴新人review 意見(jiàn)里標(biāo)注了 nitnitpick 瑣碎小建議的內(nèi)容只是錦上添花可以不改不是必須服從。這套組合拳打下來(lái)團(tuán)隊(duì)里新人在第二個(gè)月的 PR 打回率就明顯下降三個(gè)月后基本和資深成員持平。5.4 自動(dòng)化檢查總在報(bào)毫無(wú)意義的誤報(bào)吵得人煩誤報(bào)是引入自動(dòng)化工具之后幾乎必然會(huì)碰上的問(wèn)題處理不好會(huì)讓團(tuán)隊(duì)對(duì)工具失去信任。我的建議非常務(wù)實(shí)寧可少報(bào)不要亂報(bào)。一個(gè) lint 規(guī)則如果誤報(bào)率超過(guò) 20%那就該考慮關(guān)掉或者改成 warn 級(jí)別而不是讓每個(gè)開(kāi)發(fā)都學(xué)會(huì)如何繞過(guò)這條規(guī)則。具體到配置層面靜態(tài)分析工具的規(guī)則集采用漸進(jìn)式開(kāi)規(guī)則的策略。上線一個(gè)新規(guī)則前先在倉(cāng)庫(kù)里跑一遍看歷史代碼會(huì)被報(bào)出多少條。如果歷史積壓?jiǎn)栴}超過(guò)兩位數(shù)這條規(guī)則要么先不開(kāi)要么開(kāi)了也僅提示不攔截等團(tuán)隊(duì)消化完存量再嚴(yán)格化。我在這上面踩過(guò)幾次坑之后發(fā)現(xiàn)的規(guī)律是——工具信任一旦崩塌再想讓團(tuán)隊(duì)好好看自動(dòng)檢查結(jié)果要花數(shù)倍的時(shí)間去重建。5.5 代碼合入后才發(fā)現(xiàn) review 漏掉了關(guān)鍵 bug該問(wèn)責(zé)嗎這條我特別想聊因?yàn)楹芏鄨F(tuán)隊(duì)在這個(gè)問(wèn)題上的處理爛透了。一旦出線上故障第一反應(yīng)就是查 blame、查是誰(shuí)第一時(shí)間放行。但高效能的團(tuán)隊(duì)不會(huì)把 review 失誤當(dāng)個(gè)人錯(cuò)誤來(lái)追責(zé)而是當(dāng)系統(tǒng)設(shè)計(jì)缺陷來(lái)分析。我們要問(wèn)的不是這個(gè) reviewer 為什么沒(méi)看出來(lái)而是為什么我們的 check 機(jī)制允許這類 bug 未被攔截然后改進(jìn)系統(tǒng)讓下一次同樣的錯(cuò)誤變得更難發(fā)生。我們團(tuán)隊(duì)在復(fù)盤(pán)會(huì)上有個(gè)不成文的規(guī)矩不點(diǎn)名只說(shuō)機(jī)制。每次復(fù)盤(pán)某個(gè) review 漏掉的高風(fēng)險(xiǎn)缺陷我們都會(huì)問(wèn)兩個(gè)問(wèn)題當(dāng)時(shí)那類風(fēng)險(xiǎn)是不是在 checklist 覆蓋范圍內(nèi)如果不在這次的事故正好證明需要補(bǔ)上它如果在那說(shuō)明是執(zhí)行問(wèn)題就要去看是不是流程壓力過(guò)大、是不是 PR 太大、是不是 reviewer 同時(shí)要看的 PR 太多——這些問(wèn)題仍然指向系統(tǒng)改進(jìn)而不是個(gè)人懲罰。6. 如何從零開(kāi)始在你的團(tuán)隊(duì)落地 open-code-review6.1 第一步先定極小規(guī)則集別貪多求全我知道很多團(tuán)隊(duì)的負(fù)責(zé)人看完這類文章之后第一反應(yīng)是想把所有建議一次性落地。但我必須潑一盆冷水一次引入太多規(guī)則團(tuán)隊(duì)會(huì)像應(yīng)對(duì)一個(gè)食之無(wú)味棄之可惜的新系統(tǒng)一樣迅速把它變成又一個(gè)效率負(fù)擔(dān)。最穩(wěn)妥的做法是選擇一個(gè)正在活躍迭代的倉(cāng)庫(kù)先只引入三個(gè)東西PR 模板、一個(gè)基礎(chǔ) lint 配置和一條 CI 檢查。等這兩三樣跑順了再逐步加入 review 機(jī)器人、覆蓋率檢查、協(xié)議檢查等。第一批規(guī)則數(shù)量控制在 5 到 10 條之內(nèi)。比如定義 PR 描述必須包含哪些字段、PR 超過(guò)多少行需要拆、哪些枚舉必須用共享常量而不是硬編碼。這些規(guī)則要符合該倉(cāng)庫(kù)的實(shí)際技術(shù)棧和團(tuán)隊(duì)當(dāng)下的痛點(diǎn)。我的經(jīng)驗(yàn)是第一批規(guī)則最好只解決你們最近三個(gè)月內(nèi)實(shí)際踩過(guò)的坑而不是去預(yù)防那些也許永遠(yuǎn)不發(fā)生的風(fēng)險(xiǎn)——預(yù)防永遠(yuǎn)是第二順位的事。6.2 第二步讓 review 的正確姿勢(shì)變成公共知識(shí)規(guī)則定好之后還需要讓團(tuán)隊(duì)的每個(gè)成員都明確知道我應(yīng)該怎樣做一次 review。我會(huì)組織一場(chǎng)一小時(shí)的分享會(huì)但講的不是 PPT 里的抽象理論而是拿一個(gè)真實(shí)的歷史 PR 當(dāng)案例演示一個(gè)合格的 reviewer 會(huì)怎么讀一個(gè) diff。我第一次做這個(gè)演示時(shí)現(xiàn)場(chǎng)拆了一個(gè)三百行的 PR按我們清單的五個(gè)維度逐條說(shuō)明哪些地方會(huì)觸發(fā)我的疑問(wèn)哪些地方值得深入看哪些地方可以直接跳過(guò)。分享結(jié)束后有同事跑來(lái)跟我說(shuō)原來(lái) review 不是從頭到尾讀一遍而是帶著一堆問(wèn)題去代碼里找答案。這個(gè)細(xì)節(jié)我特別想強(qiáng)調(diào)——code review 的正確姿勢(shì)不是從第一個(gè) diff 看到最后一個(gè) diff而是先讀 PR 描述搞清楚這次改動(dòng)的意圖和范圍再帶著問(wèn)題跳讀關(guān)鍵的改動(dòng)點(diǎn)。這樣既快又能抓住重點(diǎn)。很多低質(zhì)量的 review 是因?yàn)?reviewer 從頭到尾機(jī)械地讀反而漏掉了真正要關(guān)注的核心。6.3 第三步按迭代復(fù)盤(pán)持續(xù)校準(zhǔn)規(guī)則規(guī)則和工具落地后最關(guān)鍵的就是按迭代做復(fù)盤(pán)。這個(gè)復(fù)盤(pán)不需要多頻繁一次迭代結(jié)束的最后一天拿出來(lái) 30 分鐘就夠了。打開(kāi)這段時(shí)間合入的 PR挑出質(zhì)量最高的一個(gè)和質(zhì)量最低的一個(gè)分別討論一下高質(zhì)量 PR 為什么好是描述寫(xiě)得好還是拆得好還是測(cè)試補(bǔ)充得扎實(shí)低質(zhì)量 PR 暴露了哪條規(guī)則沒(méi)有起到作用我們團(tuán)隊(duì)就是通過(guò)這個(gè)方式持續(xù)調(diào)整規(guī)則的。曾經(jīng)有一條PR 內(nèi)不要出現(xiàn)不必要的注釋掉的代碼規(guī)則執(zhí)行了幾輪后我們發(fā)現(xiàn)這條規(guī)則過(guò)于瑣碎而且容易誤判就把它收回了。又比如新增了改動(dòng)涉及配置時(shí)必須在 PR 描述中注明目標(biāo)環(huán)境這條規(guī)則是因?yàn)橛幸淮闻渲米兏堑搅松?jí)流程才暴露出來(lái)問(wèn)題。這種持續(xù)校準(zhǔn)的過(guò)程正是 open-code-review 的核心精神——規(guī)則不是鐵板一塊地壓下來(lái)的而是在團(tuán)隊(duì)協(xié)作中被持續(xù)打磨和完善。6.4 第四步為愿意把 review 做好的成員留出空間最后聊一個(gè)可能跟前三步都不太一樣但我認(rèn)為同樣重要的點(diǎn)。很多團(tuán)隊(duì)的激勵(lì)體系里code review 是不被看見(jiàn)的幕后工作成員主動(dòng)好好 review 了沒(méi)有直接的回報(bào)和反饋。這導(dǎo)致認(rèn)真做 review 的人逐漸被搭便車(chē)心態(tài)消耗掉。我的經(jīng)驗(yàn)是一方面要在團(tuán)隊(duì)里公開(kāi)肯定 review 做得好的成員——不只是夸 ta 發(fā)現(xiàn)了 bug更要點(diǎn)名謝謝 ta 提出的建設(shè)性建議讓設(shè)計(jì)更簡(jiǎn)潔。另一方面在評(píng)估績(jī)效和成長(zhǎng)時(shí)要把 review 質(zhì)量納入考量的范疇。如果一個(gè)成員這半年做了大量高價(jià)值的 review 反饋那這一點(diǎn)應(yīng)該被記錄和認(rèn)可即便 ta 自己交付的代碼量不算最大。不然的話open-code-review 再怎么強(qiáng)調(diào)參與感最終也會(huì)輸給真實(shí)的激勵(lì)機(jī)制。激勵(lì)機(jī)制不跟上任何協(xié)作流程都走不遠(yuǎn)。寫(xiě)在后面我在實(shí)際推動(dòng)這套方案之前也懷疑過(guò)是不是把簡(jiǎn)單的事情搞復(fù)雜了。但跑了幾個(gè)迭代之后我最大的感受是好的 code review 不是靠幾個(gè)認(rèn)真的人撐起來(lái)的而是靠一套清晰、開(kāi)放、可迭代的規(guī)則讓所有人都能在同一個(gè)水位線上參與。這個(gè)水位線才是團(tuán)隊(duì)整體代碼質(zhì)量真正的下限。把下限抬起來(lái)比期待每個(gè)人都成為頂尖寫(xiě)手要現(xiàn)實(shí)得多也穩(wěn)定得多。