做代碼審查這件事我前前后后折騰了快六年。從大廠里逐 commit 走查的嚴(yán)格流程到小團(tuán)隊(duì)里 MR 發(fā)出去一周沒(méi)人理的松散狀態(tài)全都經(jīng)歷過(guò)。今天想聊的這套 open-code-review不是哪個(gè)商業(yè)平臺(tái)的新功能而是我這幾年踩坑之后沉淀下來(lái)的一套純開(kāi)源代碼審查落地實(shí)踐。它解決的問(wèn)題很直接讓代碼審查不再是有沒(méi)有都行的過(guò)場(chǎng)而是變成一套機(jī)器主動(dòng)盯細(xì)節(jié)、清單兜住盲區(qū)、統(tǒng)計(jì)結(jié)果反過(guò)來(lái)改進(jìn)流程的機(jī)制。open-code-review 適合誰(shuí)一句話凡是正被提交了沒(méi)人審審了也說(shuō)不出所以然審查全靠 leader 一個(gè)人扛困擾的團(tuán)隊(duì)都可以直接參考。整套方案完全基于開(kāi)源組件搭建不需要采購(gòu)任何商業(yè)產(chǎn)品只要團(tuán)隊(duì)在用 Git 托管平臺(tái)GitHub、GitLab、Gitea 都可以就能把流程在倉(cāng)庫(kù)層面固化下來(lái)。整體設(shè)計(jì)原則就一條機(jī)械的、可枚舉的規(guī)則交給機(jī)器需要經(jīng)驗(yàn)判斷的內(nèi)容留給人類(lèi)。這也是它跟那些動(dòng)輒上百頁(yè)的審查規(guī)范文檔之間最本質(zhì)的區(qū)別。如果你最近也在關(guān)注 open code review 這個(gè)方向或者正糾結(jié)開(kāi)源的代碼審查方案到底能不能用、算不算真正開(kāi)源這篇實(shí)踐記錄應(yīng)該能幫上忙。接下來(lái)我會(huì)把整套方案的設(shè)計(jì)思路、關(guān)鍵配置、真實(shí)踩坑過(guò)程以及推行半年后的數(shù)據(jù)變化全部攤開(kāi)講你照著抄就能用。1. 方案選型與整體設(shè)計(jì)代碼審查為什么總流于形式1.1 從反復(fù)失敗中總結(jié)出的四個(gè)典型困境先說(shuō)結(jié)論大多數(shù)團(tuán)隊(duì)的代碼審查做不起來(lái)真不是成員態(tài)度問(wèn)題而是流程設(shè)計(jì)本身有缺陷。我拆過(guò)好幾個(gè)團(tuán)隊(duì)的 Review 數(shù)據(jù)反復(fù)出現(xiàn)的基本就這四類(lèi)問(wèn)題。第一是審查不及時(shí)。PR 掛在倉(cāng)庫(kù)里三天沒(méi)人理開(kāi)發(fā)者手上的上下文早就切換到下一個(gè)需求了等 review 意見(jiàn)回來(lái)光重新回憶上下文就要花半天。審查者看一個(gè)陌生模塊也要重新讀代碼兩邊的時(shí)間成本都極高最后只能草草 approve 了事。第二是關(guān)注點(diǎn)錯(cuò)位。我見(jiàn)過(guò)太多 review 評(píng)論糾結(jié)在縮進(jìn)、命名、單行長(zhǎng)度這些格式問(wèn)題上真正高風(fēng)險(xiǎn)的點(diǎn)——接口兼容性、并發(fā)邊界、數(shù)據(jù)一致性、事務(wù)嵌套——反而沒(méi)人提。為什么因?yàn)楦袷絾?wèn)題一眼就能看到而邏輯風(fēng)險(xiǎn)需要主動(dòng)分析才能發(fā)現(xiàn)人的注意力天然會(huì)被最容易感知的東西帶走。第三是知識(shí)分布不均勻。一個(gè)項(xiàng)目里能真正把核心模塊看明白的可能只有一兩個(gè)人其他人在 Review 的時(shí)候根本不敢出聲久而久之形成了事實(shí)上的單人審查。這個(gè)問(wèn)題的可怕之處在于它會(huì)讓團(tuán)隊(duì)產(chǎn)生虛假的安全感人人都點(diǎn)了 approve但沒(méi)有人在認(rèn)真看。第四是沒(méi)有反饋閉環(huán)。審查完就結(jié)束了不統(tǒng)計(jì)、不復(fù)盤(pán)同樣的坑隔幾周再踩一次。團(tuán)隊(duì)根本不知道自己的 review 平均要花多久、哪類(lèi)問(wèn)題最常被漏掉、哪個(gè)模塊是事故高發(fā)區(qū)。沒(méi)有數(shù)據(jù)支撐改進(jìn)就永遠(yuǎn)停留在口號(hào)層面。這四個(gè)困境是我設(shè)計(jì) open-code-review 的第一性起點(diǎn)。方案里的每一塊配置都是為了針對(duì)性地解決其中一個(gè)或多個(gè)問(wèn)題。1.2 為什么堅(jiān)持全開(kāi)源工具鏈而不是商業(yè)產(chǎn)品嚴(yán)格來(lái)說(shuō)商業(yè)代碼審查產(chǎn)品在某些場(chǎng)景下確實(shí)做得不錯(cuò)比如可視化報(bào)表很漂亮、權(quán)限體系很完整。但我在落地的時(shí)候發(fā)現(xiàn)大多數(shù)中小團(tuán)隊(duì)真正需要的不是一整套復(fù)雜平臺(tái)而是審查這件事能穩(wěn)定發(fā)生、不被繞過(guò)的底線機(jī)制。商業(yè)工具往往意味著額外的部署成本和用戶培訓(xùn)成本團(tuán)隊(duì)為了用工具而用工具反而會(huì)更抗拒流程。所以 open-code-review 的選型原則非常明確全部使用開(kāi)源組件優(yōu)先選團(tuán)隊(duì)已經(jīng)在用、或者托管平臺(tái)原生支持的能力。Git 倉(cāng)庫(kù)用 GitHub/GitLab 這些主流平臺(tái)提交規(guī)范用 commitlintPR 靜態(tài)檢查結(jié)果用 reviewdog 自動(dòng)貼評(píng)論文件負(fù)責(zé)人機(jī)制用 CODEOWNERS自動(dòng)化流程用 GitHub Actions 或 GitLab CI。這一套下來(lái)既有商業(yè)工具的體驗(yàn)自動(dòng)檢查、自動(dòng)指派、趨勢(shì)統(tǒng)計(jì)又沒(méi)有一分錢(qián)額外采購(gòu)成本所有配置都以文本文件形式存放在倉(cāng)庫(kù)里可以隨倉(cāng)庫(kù)一起版本化管理。這里要專(zhuān)門(mén)回應(yīng)用一下熱詞里那個(gè)問(wèn)題open code review 開(kāi)源了嗎。這套方案從底層到上層沒(méi)有任何閉源組件——每個(gè)工具都有自己的開(kāi)源倉(cāng)庫(kù)整個(gè)模板配置也完全可以公開(kāi)共享。你甚至不需要信任某個(gè)第三方服務(wù)因?yàn)槿繖z查動(dòng)作都在自己的 CI 環(huán)境里跑token 和日志都是自己控制的。對(duì)很多有合規(guī)要求的團(tuán)隊(duì)來(lái)說(shuō)全開(kāi)源、自托管、可審計(jì)本身就是選它的一個(gè)重要理由。另外一個(gè)很實(shí)際的考量是可復(fù)制性。方案里所有配置都收斂在一個(gè).github目錄里新倉(cāng)庫(kù)只要把整個(gè)目錄復(fù)制過(guò)去再改兩三個(gè)環(huán)境變量就能直接獲得一致的審查流程。團(tuán)隊(duì)里有十個(gè)服務(wù)倉(cāng)庫(kù)這套機(jī)制拷十份規(guī)則完全一致不會(huì)出現(xiàn)這個(gè)倉(cāng)庫(kù)審查嚴(yán)、那個(gè)倉(cāng)庫(kù)走過(guò)場(chǎng)的割裂狀態(tài)。2. 核心機(jī)制拆分機(jī)器干機(jī)器的活人干人的活2.1 審查清單給人工審查提供最小可用上下文open-code-review 最核心的一個(gè)設(shè)計(jì)是把人工審查從打開(kāi) PR 從頭看到尾變成對(duì)照清單逐項(xiàng)確認(rèn)。PR 描述里自動(dòng)生成一份自查清單開(kāi)發(fā)者提交時(shí)必須逐項(xiàng)勾選審查者打開(kāi) PR 就能看到一個(gè)明確的檢查框架。這份清單的設(shè)計(jì)原則是只寫(xiě)人類(lèi)才能判斷的問(wèn)題機(jī)器能查的格式問(wèn)題一個(gè)不寫(xiě)。我目前的模板長(zhǎng)這樣## 變更說(shuō)明 ## 影響范圍涉及哪些模塊、接口、數(shù)據(jù) ## 測(cè)試情況新增/修改了哪些測(cè)試手工驗(yàn)證了哪些場(chǎng)景 ## 自查清單 - [ ] 功能行為與需求描述一致 - [ ] 關(guān)鍵分支、邊界條件、異常路徑已覆蓋 - [ ] 對(duì)外接口與數(shù)據(jù)結(jié)構(gòu)變更已評(píng)估兼容性 - [ ] 并發(fā)訪問(wèn)與事務(wù)邊界已檢查 - [ ] 無(wú)明顯可以預(yù)見(jiàn)的性能退化 - [ ] 日志輸出不包含敏感信息很多團(tuán)隊(duì)會(huì)覺(jué)得清單太簡(jiǎn)單其實(shí)這里有個(gè)很容易犯的錯(cuò)誤把清單做得又長(zhǎng)又細(xì)恨不得把編碼規(guī)范全寫(xiě)進(jìn)去。清單一旦超過(guò)十項(xiàng)開(kāi)發(fā)者就會(huì)條件反射式地全部勾選審查者也不會(huì)真的逐項(xiàng)確認(rèn)它就從檢查工具退化成心理安慰。真正有效的清單必須控制在六到八項(xiàng)而且每一條都對(duì)應(yīng)人類(lèi)特有的判斷力比如邊界條件、兼容性、并發(fā)問(wèn)題。這些條目數(shù)量少、分量重反而能讓審查者快速進(jìn)入狀態(tài)。2.2 提交階段卡口把錯(cuò)誤攔截在離開(kāi)發(fā)者最近的地方代碼審查不應(yīng)該從 PR 才起步而是要從 git commit 那一刻就開(kāi)始介入。open-code-review 在本地提交階段配置了兩道卡口commitlint 規(guī)范提交信息lint-staged 對(duì)暫存區(qū)文件做快速靜態(tài)檢查。commitlint 強(qiáng)制提交信息遵循 Conventional Commits 規(guī)范格式是type(scope): subject比如fix(login): correct token expiry check。為什么要管提交信息因?yàn)樗苯記Q定后續(xù)的 changelog 自動(dòng)生成、關(guān)聯(lián) issue 追蹤、以及 git bisect 定位效率。我的 commitlint 配置是這樣的module.exports { extends: [commitlint/config-conventional], rules: { type-enum: [2, always, [feat, fix, docs, style, refactor, perf, test, chore, revert]], subject-max-length: [2, always, 72], subject-empty: [2, never] } };配合 husky 注冊(cè) pre-commit 和 commit-msg 鉤子開(kāi)發(fā)者提交的那一刻就能得到反饋不需要等 CI 跑完才發(fā)現(xiàn)提交信息寫(xiě)錯(cuò)了。lint-staged 的作用類(lèi)似它只檢查暫存區(qū)里那些即將提交的文件保證不會(huì)因?yàn)閭}(cāng)庫(kù)里歷史遺留的問(wèn)題阻塞當(dāng)前提交。這兩道卡口放在本地是因?yàn)榉答佀俣缺韧七h(yuǎn)端再跑 CI 快了一個(gè)數(shù)量級(jí)人在寫(xiě)代碼的當(dāng)下拿到報(bào)錯(cuò)修改成本幾乎為零。這里有一個(gè)我特別想強(qiáng)調(diào)的實(shí)戰(zhàn)經(jīng)驗(yàn)這兩道卡口只對(duì)新增和修改的代碼生效絕對(duì)不要放在全量代碼庫(kù)上做強(qiáng)制檢查。很多團(tuán)隊(duì)本地跑全量 lint結(jié)果倉(cāng)庫(kù)里有一堆歷史技術(shù)債新人也跑不過(guò)第一反應(yīng)就是--no-verify跳過(guò)鉤子?？谝坏┠鼙惠p易繞過(guò)整個(gè)機(jī)制就失去了意義。寧可先只檢查 diff 范圍等團(tuán)隊(duì)對(duì)規(guī)則適應(yīng)了再逐步擴(kuò)大檢查面。2.3 MR 階段自動(dòng)化讓 lint 結(jié)果出現(xiàn)在該出現(xiàn)的位置本地卡口只能攔截低級(jí)錯(cuò)誤真正能讓審查效率產(chǎn)生質(zhì)變的是 MR 階段的自動(dòng)化檢查在正確的位置輸出正確的結(jié)果。這里我最推薦的組合是 reviewdog 加托管平臺(tái)的 CI。reviewdog 的核心能力是把各種 linter 的輸出解析成 diff 行級(jí)評(píng)論貼在對(duì)應(yīng)的代碼行下面而不是在 CI 日志里刷一屏 summary。審查者打開(kāi) PR點(diǎn)開(kāi) Conversation 標(biāo)簽頁(yè)就能看到類(lèi)似這里有一處空指針風(fēng)險(xiǎn)這樣的評(píng)論錨定在具體代碼行上。這種體驗(yàn)跟在 GitHub/GitLab 網(wǎng)頁(yè)上人工評(píng)論幾乎一樣但內(nèi)容是機(jī)器自動(dòng)生成的。我用的 reviewdog 配置大致如下runner: eslint: cmd: npx eslint --format checkstyle ${reviewdog_flags} errorformat: - %f:%l:%c: %m level: error reporter: github-pr-review這里有個(gè)細(xì)節(jié)level: error表示只有 error 級(jí)別的 lint 問(wèn)題才會(huì)被貼到 PR 評(píng)論里warning 級(jí)別只進(jìn) summary。為什么因?yàn)槿绻?warning 都上評(píng)論P(yáng)R 會(huì)被刷得密密麻麻核心問(wèn)題反而被淹沒(méi)。機(jī)器評(píng)論也要有節(jié)制抓到真正的硬錯(cuò)誤就夠了。還要配套 CODEOWNERS 自動(dòng)指派。規(guī)則文件長(zhǎng)這樣# 核心流程模塊需要模塊負(fù)責(zé)人確認(rèn) src/core/ alice bob # 數(shù)據(jù)庫(kù)遷移文件必須過(guò)架構(gòu)師 db/migrations/ carol # 前端組件改動(dòng)過(guò)前端負(fù)責(zé)人 src/components/ david審查的第一步永遠(yuǎn)是找到對(duì)的人。CODEOWNERS 的價(jià)值在于把指派規(guī)則固化到文件里任何倉(cāng)庫(kù)只要改了對(duì)應(yīng)目錄系統(tǒng)自動(dòng)把人拉進(jìn)來(lái)省去了人工指定 reviewer 的溝通成本也避免了臨時(shí)隨手拉個(gè)人導(dǎo)致審查質(zhì)量不可控的問(wèn)題。2.4 審查邊界自動(dòng)化終于開(kāi)始的地方自動(dòng)化并不能覆蓋所有問(wèn)題這一點(diǎn)必須明確。我在設(shè)計(jì)的時(shí)候把檢查分成了三層第一層是格式與靜態(tài)規(guī)則機(jī)器自動(dòng)查第二層是單測(cè)與構(gòu)建驗(yàn)證CI 自動(dòng)跑第三層是架構(gòu)合理性、業(yè)務(wù)邏輯、邊界條件、擴(kuò)展性這些只能靠人。open-code-review 里的所有自動(dòng)化配置目標(biāo)都是壓縮第一層和第二層的消耗把人的精力和注意力集中到第三層上。很多團(tuán)隊(duì)翻車(chē)的點(diǎn)在于把自動(dòng)化工具當(dāng)作審查的全部lint 通過(guò)就合并導(dǎo)致代碼雖然格式統(tǒng)一但架構(gòu)腐爛得悄無(wú)聲息。我在推行這套方案時(shí)反復(fù)和團(tuán)隊(duì)強(qiáng)調(diào)tool review 從不等同于 human review自動(dòng)化環(huán)節(jié)是守門(mén)員不是裁判。守住低質(zhì)量的球最終判斷還是要交給人來(lái)下。3. 實(shí)操過(guò)程把 open-code-review 跑起來(lái)3.1 倉(cāng)庫(kù)初始化與目錄結(jié)構(gòu)整套方案落地不需要安裝任何獨(dú)立服務(wù)所有配置都放在倉(cāng)庫(kù)里。我習(xí)慣在模板倉(cāng)庫(kù)里維護(hù)這樣一個(gè)目錄結(jié)構(gòu).github/ ├── workflows/ │ └── review.yml ├── reviewdog.yml ├── CODEOWNERS └── PULL_REQUEST_TEMPLATE.md commitlint.config.js .husky/ ├── commit-msg └── pre-commit模板倉(cāng)庫(kù)本身也是一個(gè)普通 Git 倉(cāng)庫(kù)團(tuán)隊(duì)內(nèi)所有服務(wù)倉(cāng)庫(kù)都可以把這個(gè)目錄作為一個(gè)分支拉過(guò)去或者直接復(fù)制。這里要注意.github/PULL_REQUEST_TEMPLATE.md必須放在這個(gè)位置GitHub 才會(huì)在創(chuàng)建 PR 時(shí)自動(dòng)加載模板。GitLab 的 MR 模板路徑略有不同但原理一致。3.2 逐個(gè)文件配置與參數(shù)選擇先看 CI 工作流的核心文件.github/workflows/review.ymlname: code-review on: pull_request_target: types: [opened, synchronize, reopened] permissions: contents: read pull-requests: write jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci - uses: reviewdog/action-eslintv1 with: github_token: ${{ secrets.GITHUB_TOKEN }} reporter: github-pr-review level: warning filter_mode: diff_context逐個(gè)拆解這里面的關(guān)鍵參數(shù)。pull_request_target和pull_request的區(qū)別是前者使用目標(biāo)分支的代碼來(lái)跑工作流token 權(quán)限更大。對(duì)于 reviewdog 這種需要把評(píng)論寫(xiě)回 PR 的使用場(chǎng)景只能用pull_request_target。但要注意安全隱患工作流里不要直接執(zhí)行未經(jīng)審查的 PR 代碼如果需要裝依賴要在安全沙箱環(huán)境里做。filter_mode: diff_context表示只報(bào)告 diff 范圍內(nèi)及其上下文幾行的問(wèn)題這樣舊代碼里的歷史問(wèn)題不會(huì)被新 PR 觸發(fā)避免噪音。level: warning的意思是 warning 和 error 都會(huì)反饋給 PR但因?yàn)榍懊媾渲昧?reviewdog.yml 里的 level 設(shè)置最終評(píng)論閾值以兩者結(jié)合為準(zhǔn)。實(shí)踐經(jīng)驗(yàn)是新團(tuán)隊(duì)剛推行時(shí)可以把 level 設(shè)成 error等到大家習(xí)慣后再放寬到 warning。permissions字段也很重要。它遵循最小權(quán)限原則只給pull-requests: write其余全部只讀。不要貪圖方便把權(quán)限放開(kāi)審查機(jī)器人只需要寫(xiě)評(píng)論和讀代碼的能力給多了反而是風(fēng)險(xiǎn)敞口。接下來(lái)是 CODEOWNERS 的配置策略。文件路徑寫(xiě)規(guī)則時(shí)越具體的規(guī)則優(yōu)先級(jí)越高。我一般按模塊重要程度分層核心庫(kù)代碼、數(shù)據(jù)庫(kù)遷移、密鑰相關(guān)邏輯、支付相關(guān)邏輯都配置兩個(gè)以上 owner普通業(yè)務(wù)頁(yè)面只配一個(gè) owner。這里有一個(gè)可量化的經(jīng)驗(yàn)每個(gè)被標(biāo)記的目錄owner 至少兩人避免單個(gè)維護(hù)者休假時(shí)審查阻塞。3.3 審查人數(shù)、PR 大小與超時(shí)提醒的策略計(jì)算很多團(tuán)隊(duì)糾結(jié)代碼審查到底幾個(gè)人看才夠其實(shí)答案取決于改動(dòng)風(fēng)險(xiǎn)等級(jí)。我給 open-code-review 定的默認(rèn)策略是常規(guī) PR 至少一個(gè)非作者 reviewer 批準(zhǔn)涉及db/migrations/、src/core/、或超過(guò) 600 行變更的 PR必須兩個(gè) owner 或 owner 加架構(gòu)師共同批準(zhǔn)。為什么取 600 行這是很多研究里提到的認(rèn)知負(fù)荷臨界點(diǎn)——超過(guò)這個(gè)規(guī)模的 diff審查者很難保持全程注意力容易被局部細(xì)節(jié)帶偏忽略整體設(shè)計(jì)問(wèn)題。PR 拆分的參考原則我可以直接給到單個(gè) PR 的改動(dòng)文件控制在 10 個(gè)以內(nèi)改動(dòng)行數(shù)盡量控制在 400 到 600 行之間重構(gòu)類(lèi)改動(dòng)要額外拆分把遷移性重構(gòu)和新功能開(kāi)發(fā)分兩個(gè) PR 提交。這個(gè)數(shù)字不是拍腦袋定的配合分支策略可以直觀感受如果一次功能開(kāi)發(fā)是一個(gè)大 PR說(shuō)明分支粒度不對(duì)應(yīng)該讓 feature 分支按可獨(dú)立驗(yàn)收的子任務(wù)拆分。超時(shí)提醒也非常有必要。工作流里可以加一個(gè)獨(dú)立 job用 cron 定時(shí)掃描所有處于 pending review 狀態(tài)的 PR超過(guò) 24 小時(shí)就在指定頻道里催辦。這個(gè)能力用 GitHub Actions 的 schedule 事件就能做代碼量不大但對(duì)流程剛性的幫助非常明顯——它把有人忘了審從一個(gè)可被忽略的偶發(fā)現(xiàn)象變成一個(gè)每天自動(dòng)暴露的指標(biāo)。3.4 度量與復(fù)盤(pán)用數(shù)據(jù)看審查是否真的變好了open-code-review 的最后一塊拼圖是度量。沒(méi)有數(shù)據(jù)你就無(wú)法回答這套方案是否有效。我建議每?jī)芍芾淮蝹}(cāng)庫(kù)數(shù)據(jù)統(tǒng)計(jì)四個(gè)核心指標(biāo)從 PR 創(chuàng)建到首次 review 評(píng)論的時(shí)間反映響應(yīng)速度從首次 review 到合并的時(shí)間反映討論收斂速度每個(gè) PR 的評(píng)論條數(shù)反映討論深度太少說(shuō)明沒(méi)人認(rèn)真看被退回修改的 PR 占比反映前置質(zhì)量把關(guān)情況拉取 GitHub 數(shù)據(jù)用官方 CLI 就能完成。大致命令是這樣的gh pr list --repo your-org/your-repo --state merged --limit 50 \ --json number,createdAt,mergedAt,reviews \ --jq .[] | {num: .number, firstReviewAt: .reviews[0].submittedAt, createdAt, mergedAt}拿到數(shù)據(jù)后最值得關(guān)注的是響應(yīng)速度。如果 PR 創(chuàng)建后 24 小時(shí)內(nèi)沒(méi)有第一個(gè) review 評(píng)論說(shuō)明審查者沒(méi)有及時(shí)介入。這時(shí)候不要急著怪人要檢查指派規(guī)則是不是有漏洞比如 CODEOWNERS 沒(méi)覆蓋到新加的目錄或者負(fù)責(zé)人沒(méi)有收到通知。數(shù)據(jù)是用來(lái)定位流程問(wèn)題的不是用來(lái)追責(zé)的這個(gè)觀念一定得先立住。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄4.1 reviewdog 不評(píng)論了怎么辦這是推行過(guò)程中被問(wèn)得最多的問(wèn)題。reviewdog 明明跑完了PR 里卻看不到一條評(píng)論。排查順序我建議固定為第一步看 Actions 日志里 reviewdog 的輸出確認(rèn)它是否確實(shí)解析到了 lint 結(jié)果第二步確認(rèn) reporter 是不是github-pr-review寫(xiě)成了github-check就只會(huì)出現(xiàn)在 Checks 頁(yè)面不會(huì)出現(xiàn)在 Conversation第三步檢查filter_mode如果是filter_mode: file且 PR 改動(dòng)較少可能沒(méi)有匹配行最后看 GITHUB_TOKEN 權(quán)限contents: read是不夠?qū)懺u(píng)論的必須給pull-requests: write。4.2 PR 模板不生效或清單被批量勾選PR 模板不生效通常是因?yàn)槁窂讲粚?duì)GitHub 識(shí)別的是.github/PULL_REQUEST_TEMPLATE.md路徑錯(cuò)一個(gè)字符都沒(méi)戲。但比模板不生效更常見(jiàn)的問(wèn)題是清單被形式化開(kāi)發(fā)者創(chuàng)建 PR 時(shí)把所有 checkbox 一鍵勾掉審查者也不看。我的處理辦法是在清單底部加一行聲明我已逐項(xiàng)確認(rèn)上述條目并對(duì)遺漏項(xiàng)負(fù)責(zé)同時(shí)把清單勾選情況接入 CI——用一個(gè)腳本檢查 PR 描述里是否還有未勾選的自查項(xiàng)有就不能合并。4.3 團(tuán)隊(duì)抵觸強(qiáng)制審查怎么辦技術(shù)方案永遠(yuǎn)好辦人的問(wèn)題才難。我推行這套流程時(shí)也遇到過(guò)抵觸核心原因是大家覺(jué)得被強(qiáng)制審查是一種不信任。后來(lái)我改了一個(gè)做法先從核心模塊和數(shù)據(jù)庫(kù)遷移這類(lèi)高風(fēng)險(xiǎn)文件做強(qiáng)制 owner 審查其他代碼先保持建議審查等團(tuán)隊(duì)嘗到了甜頭——比如線上事故變少、回滾幾乎消失——再逐步擴(kuò)大強(qiáng)制范圍。同時(shí)leader 的 PR 也要走同一套流程而且?guī)ь^被機(jī)器評(píng)論和同事提意見(jiàn)這個(gè)示范作用比任何制度都管用。4.4 高頻問(wèn)題速查表整理了一份我在多個(gè)團(tuán)隊(duì)答疑時(shí)反復(fù)用到的高頻問(wèn)題表建議收藏問(wèn)題現(xiàn)象可能原因解決方法reviewdog 不貼評(píng)論token 缺少pull-requests: write權(quán)限檢查 workflow 的permissions字段評(píng)論全部集中在 summary沒(méi)有行級(jí)評(píng)論reporter 配錯(cuò)或 filter 模式過(guò)窄改github-pr-review把filter_mode調(diào)整為diff_context提交信息總是被 commitlint 攔下團(tuán)隊(duì)對(duì)規(guī)范不熟在 README 里附常用 type 示例并給docs、chore多留容錯(cuò)空間PR 在周五掛到下周沒(méi)人看指派規(guī)則遺漏或負(fù)責(zé)人臨時(shí)缺席設(shè)置 24 小時(shí)自動(dòng)催辦并在 CODEOWNERS 中為每個(gè)模塊配置備用 ownerlint 檢查被--no-verify繞過(guò)歷史技術(shù)債太重全量檢查跑不過(guò)只檢查 diff 范圍先保增量質(zhì)量再逐步清理存量審查意見(jiàn)集中在格式缺少業(yè)務(wù)深度清單里沒(méi)有引導(dǎo)業(yè)務(wù)視角的問(wèn)題在 PR 模板里增加影響范圍邊界條件等強(qiáng)提示項(xiàng)4.5 幾個(gè)值得長(zhǎng)期堅(jiān)持的細(xì)節(jié)習(xí)慣最后分享幾個(gè)不在配置文件里、但對(duì)流程質(zhì)量影響很大的細(xì)節(jié)習(xí)慣。第一個(gè)是審查者不要點(diǎn)全局 diff 慢慢劃要按提交順序逐個(gè) commit 看每一個(gè) commit 都是獨(dú)立的邏輯單元這樣定位問(wèn)題更精準(zhǔn)。第二個(gè)是發(fā)現(xiàn)小問(wèn)題不要立刻打斷作者把評(píng)論攢起來(lái)統(tǒng)一發(fā)減少作者來(lái)回切上下文的次數(shù)可以在評(píng)論里標(biāo)注這個(gè)可以放到后續(xù) PR 處理和這個(gè)必須本次修改兩類(lèi)。第三個(gè)是每月做一次代碼評(píng)審復(fù)盤(pán)會(huì)把當(dāng)月最典型的幾個(gè) review 案例拿出來(lái)講讓大家明白為什么這里當(dāng)時(shí)應(yīng)該被攔住這種案例式學(xué)習(xí)比抽象講解有效得多。根據(jù)我個(gè)人的實(shí)操體會(huì)open-code-review 這套方案真正起作用靠的不是某個(gè)工具的魔法而是把流程中可以被自動(dòng)化、被固化的部分全部先固化下來(lái)讓人工審查的精力集中在最有價(jià)值的地方。如果你團(tuán)隊(duì)現(xiàn)在正處于審查形同虛設(shè)的階段我非常建議先別急著鋪開(kāi)全部機(jī)制選一個(gè)核心倉(cāng)庫(kù)把提交規(guī)范、PR 模板、行級(jí)評(píng)論這三件事先跑起來(lái)等習(xí)慣養(yǎng)成后再逐步加 CODEOWNERS 和審查度量。流程設(shè)計(jì)永遠(yuǎn)要順勢(shì)而為一次只改變一個(gè)變量才最容易讓人接受并堅(jiān)持下去。