源代碼審查工具 open-code-review 的原理與實(shí)戰(zhàn))
寫代碼這么多年我一直覺(jué)得 code review 是最能體現(xiàn)團(tuán)隊(duì)技術(shù)氛圍的一件事。代碼寫得好不好review 別人代碼時(shí)一針見(jiàn)血說(shuō)明你對(duì)自己寫的東西有沒(méi)有深入思考過(guò)。但現(xiàn)實(shí)很骨感項(xiàng)目趕進(jìn)度的時(shí)候Review 往往是最先被犧牲的環(huán)節(jié)。我見(jiàn)過(guò)太多團(tuán)隊(duì)嘴上說(shuō)一定要 review實(shí)際合并請(qǐng)求掛了兩三天沒(méi)人看或者 Reviewer 只回一句LGTM就合進(jìn)去了。這些場(chǎng)景背后都是同一個(gè)問(wèn)題人肉 review 的成本和效果不成正比。于是我開(kāi)始折騰自動(dòng)代碼審查測(cè)試過(guò)好幾款商業(yè)工具和開(kāi)源項(xiàng)目也在 CI 里折騰過(guò)各種靜態(tài)掃描方案。今天想聊的是我目前在用的一個(gè)開(kāi)源項(xiàng)目叫open-code-review。它不是那種玄乎的 AI 魔法也不是單純的 linter而是把靜態(tài)分析、規(guī)則引擎和代碼托管平臺(tái)的交互串起來(lái)的一套自動(dòng)化審查工具。說(shuō)白了它就是幫你把代碼審查里那些重復(fù)性、機(jī)械性的部分交給機(jī)器讓人把精力聚焦在真正需要判斷力的地方。這篇文章會(huì)從項(xiàng)目設(shè)計(jì)的思路聊起講清楚它內(nèi)部的規(guī)則機(jī)制、接入方式、在 GitLab/GitHub 上的實(shí)戰(zhàn)效果以及我踩過(guò)的一些坑。如果你正在糾結(jié)要不要給團(tuán)隊(duì)上自動(dòng)代碼審查用現(xiàn)成的商業(yè)版還是自己搭這篇應(yīng)該能給你一個(gè)比較完整的參考。1. 項(xiàng)目整體設(shè)計(jì)與思路拆解1.1 代碼審查的痛點(diǎn)到底在哪先說(shuō)個(gè)我觀察到的現(xiàn)象。很多團(tuán)隊(duì)并非不想做代碼審查而是Review的過(guò)程有天然的結(jié)構(gòu)性問(wèn)題。第一個(gè)痛點(diǎn)是時(shí)效性。一個(gè)合并請(qǐng)求提出之后早上的代碼下午才有人看下午的代碼第二天才有人回應(yīng)等到所有討論結(jié)束分支可能已經(jīng)落后主分支幾十個(gè)提交了。這個(gè)時(shí)間差會(huì)導(dǎo)致兩個(gè)后果一是 Reviewer 需要在腦子里重新理解一次上下文二是開(kāi)發(fā)者會(huì)傾向于在 review 期間繼續(xù)堆代碼最后合并請(qǐng)求膨脹到幾百行連作者自己都不想看。第二個(gè)痛點(diǎn)是注意力分配。人腦在檢查代碼時(shí)真正有價(jià)值的其實(shí)是這段邏輯對(duì)不對(duì)這個(gè)設(shè)計(jì)是否合理這種高層次的判斷。但現(xiàn)實(shí)中大部分 review 討論消耗在了這里空行多了這個(gè)變量命名不規(guī)范為什么不用現(xiàn)成的工具函數(shù)這類機(jī)械問(wèn)題上。不是說(shuō)這些問(wèn)題不重要但它們完全不需要一個(gè)資深工程師花時(shí)間去盯。第三個(gè)痛點(diǎn)是標(biāo)準(zhǔn)不一致。同一個(gè)團(tuán)隊(duì)里有的人對(duì)代碼風(fēng)格極其敏感有的人只關(guān)心功能是否正確。一個(gè)文件經(jīng)過(guò)不同人 review得到的反饋風(fēng)格可能完全不一樣這在團(tuán)隊(duì)規(guī)范尚未沉淀成文檔的初創(chuàng)團(tuán)隊(duì)里尤其明顯。open-code-review 想解決的就是后面這兩類問(wèn)題把機(jī)械檢查自動(dòng)化把標(biāo)準(zhǔn)統(tǒng)一固化進(jìn)規(guī)則引擎同時(shí)用機(jī)器評(píng)論的方式跟人工 review 形成互補(bǔ)而不是取代。1.2 這個(gè)項(xiàng)目到底做了什么從項(xiàng)目命名就能看出來(lái)它的核心是開(kāi)放——規(guī)則可配置、流程可接入、平臺(tái)可擴(kuò)展。我實(shí)際用下來(lái)它的定位介于傳統(tǒng) linter 和商業(yè)智能審查工具之間。傳統(tǒng) linter 比如 ESLint、Pylint 這類只管單個(gè)文件范圍內(nèi)的語(yǔ)法和風(fēng)格問(wèn)題它們跑在本地或 CI 里輸出一份報(bào)告就完事了。它們不懂哪個(gè)提交改了哪些文件這種版本上下文也不會(huì)主動(dòng)去對(duì)應(yīng)平臺(tái)里發(fā)評(píng)論。商業(yè)智能審查工具一般集成度高、開(kāi)箱即用但規(guī)則是黑盒出了問(wèn)題你很難定位它為什么報(bào)這一條而且價(jià)格對(duì)中小團(tuán)隊(duì)不太友好。open-code-review 走的是中間路線。它會(huì)讀取合并請(qǐng)求的變更內(nèi)容在變更的代碼上做分析然后以機(jī)器人的身份把問(wèn)題直接作為評(píng)論發(fā)到對(duì)應(yīng)的代碼行上。整個(gè)過(guò)程的規(guī)則完全暴露給你你可以看到每條檢查項(xiàng)是依據(jù)什么邏輯觸發(fā)的也可以隨時(shí)調(diào)整閾值和開(kāi)關(guān)。具體來(lái)說(shuō)這個(gè)項(xiàng)目的核心模塊包括變更提取模塊對(duì)接代碼托管平臺(tái) API拉取合并請(qǐng)求的 diff 數(shù)據(jù)規(guī)則引擎內(nèi)置一批開(kāi)箱即用的檢查規(guī)則同時(shí)支持自定義規(guī)則配置評(píng)論發(fā)送模塊把審查結(jié)果按文件按行寫入評(píng)論區(qū)報(bào)告生成模塊輸出一份整體的審查摘要便于在 CI 日志里查看我之前在幾個(gè)內(nèi)部項(xiàng)目里接入了一輪整體感受是輕容器鏡像很小配置文件是 YAML塞進(jìn) GitLab CI 或者 GitHub Actions 里只要十幾分鐘就能跑完首輪。1.3 為什么推薦組合式架構(gòu)而不是一個(gè)腳本搞定剛開(kāi)始我也想得很簡(jiǎn)單寫個(gè) Python 腳本拉 diff然后調(diào)一段規(guī)則判斷最后 POST 評(píng)論到 API。聽(tīng)起來(lái)半天就能搞定。但真正做起來(lái)會(huì)發(fā)現(xiàn)一個(gè)問(wèn)題這個(gè)腳本會(huì)越寫越復(fù)雜。一開(kāi)始只是檢查新增代碼里有沒(méi)有 TODO 標(biāo)記后來(lái)想加禁止直接在生產(chǎn)代碼里使用 console.log再后來(lái)想加文件是否超過(guò) 500 行是否有重復(fù)度高的相似代碼段每個(gè)需求都是獨(dú)立維度如果全寫在一個(gè)大腳本里最終的維護(hù)成本會(huì)高到你想重寫。open-code-review 的架構(gòu)思路是把這些能力拆成模塊規(guī)則之間解耦。每條規(guī)則只負(fù)責(zé)一件事輸入是某個(gè)文件的某一行或某一段代碼輸出是一條或零條問(wèn)題記錄。這樣新增規(guī)則的時(shí)候不需要?jiǎng)悠渌a只需要往規(guī)則目錄里放一個(gè)文件并在配置文件里聲明啟用即可。這也是我想給所有準(zhǔn)備折騰類似工具的人一個(gè)建議任何自動(dòng)化審查工具的架構(gòu)都應(yīng)該按照數(shù)據(jù)采集、分析判斷、結(jié)果回寫三層去設(shè)計(jì)。分層越清晰后面加功能越省力。2. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)2.1 規(guī)則引擎的設(shè)計(jì)思路與典型規(guī)則規(guī)則引擎是整個(gè)項(xiàng)目的核心也是我最喜歡研究的部分。它內(nèi)置了幾類規(guī)則我分別說(shuō)一下它們的檢查邏輯。第一類是關(guān)鍵詞掃描規(guī)則。比如在代碼里搜索TODO、FIXME、HACK這些標(biāo)記它們往往意味著開(kāi)發(fā)者留下了一個(gè)未完成的事務(wù)。這個(gè)掃描不是簡(jiǎn)單地在整個(gè)文件里找字符串而是只針對(duì)本次變更新增的行做匹配所以不會(huì)把歷史上遺留的 TODO 全都報(bào)一遍只會(huì)提示你這次新增的代碼里又引入了新的 TODO請(qǐng)確認(rèn)是否合理。第二類是編碼規(guī)范規(guī)則。以 Python 項(xiàng)目為例它會(huì)檢查新增代碼里的命名風(fēng)格比如函數(shù)名是不是小寫下劃線、類名是不是駝峰式也會(huì)檢查常見(jiàn)的函數(shù)參數(shù)長(zhǎng)度超過(guò)閾值單行代碼過(guò)長(zhǎng)這類問(wèn)題。這類規(guī)則跟 PyLint 有重疊但它的優(yōu)勢(shì)是能站在 diff 的粒度上工作只提示變化的部分不會(huì)把整個(gè)項(xiàng)目的存量問(wèn)題一次性拋給你。第三類是安全隱患規(guī)則。比如檢測(cè)代碼里是否拼接了 SQL 語(yǔ)句而非使用參數(shù)化查詢是否在日志里打印了包含password、token、secret等關(guān)鍵字的變量值是否存在把敏感信息硬編碼進(jìn)代碼的嫌疑。這類規(guī)則的價(jià)值在于它能在代碼評(píng)審之前先替人眼掃一遍最容易出問(wèn)題的幾個(gè)點(diǎn)。第四類是工程結(jié)構(gòu)規(guī)則。檢查單次變更涉及的文件數(shù)量是否過(guò)多、單個(gè)文件的新增行數(shù)是否過(guò)大、是否引入了新的第三方依賴但未更新依賴鎖定文件等等。我自己就在規(guī)則里加過(guò)一條禁止在共享公共模塊里直接使用print()輸出調(diào)試信息因?yàn)樗鼤?huì)污染標(biāo)準(zhǔn)輸出流。用它的規(guī)則配置接口實(shí)現(xiàn)起來(lái)并不復(fù)雜大致是把這條規(guī)則聲明成匹配函數(shù)名print且調(diào)用點(diǎn)位于特定目錄下的組合條件。2.2 規(guī)則配置文件的要點(diǎn)解析open-code-review 使用 YAML 作為配置格式根目錄下默認(rèn)的配置文件類似這樣project: language: python base_branch: main rules: enabled: - todo_check - forbidden_function_check - large_diff_check - sql_injection_check disabled: [] thresholds: max_added_lines: 250 max_file_count: 10 ignore_paths: - docs/** - tests/test_data/**這里有三個(gè)關(guān)鍵概念要理解。第一個(gè)是base_branch。它決定了變更的對(duì)比基準(zhǔn)差分動(dòng)作會(huì)拿當(dāng)前分支跟這個(gè)基準(zhǔn)分支做對(duì)比從而得到精確的變更列表。默認(rèn)設(shè)成主干分支名如果你的團(tuán)隊(duì)用的是master或者trunk要同步改過(guò)來(lái)否則提取出來(lái)的變更集會(huì)跟你預(yù)期完全不一樣。第二個(gè)是thresholds閾值配置。max_added_lines: 250的含義是單次變更新增超過(guò) 250 行時(shí)觸發(fā)提醒。這個(gè)值需要根據(jù)團(tuán)隊(duì)實(shí)際節(jié)奏調(diào)整。如果你們的合并請(qǐng)求普遍在 100 行以內(nèi)設(shè)置成 250 就太寬松了規(guī)則基本不觸發(fā)。反過(guò)來(lái)如果團(tuán)隊(duì)經(jīng)常有大規(guī)模重構(gòu)的合并請(qǐng)求設(shè)得太小會(huì)產(chǎn)生大量噪音評(píng)論。第三個(gè)是ignore_paths忽略規(guī)則。這個(gè)非常實(shí)用。項(xiàng)目里總有一些不需要審查的目錄比如docs/文檔目錄、tests/test_data/測(cè)試數(shù)據(jù)目錄、還有自動(dòng)生成的代碼。不忽略這些路徑的話每次提交都會(huì)在文檔改幾個(gè)字時(shí)觸發(fā)一堆無(wú)關(guān)緊要的評(píng)論。2.3 與代碼托管平臺(tái)集成的方式作為一個(gè)自動(dòng)代碼審查工具它必須要跟代碼托管平臺(tái)深度結(jié)合才有意義。目前它支持 GitHub、GitLab 以及 Gitea 這三類常見(jiàn)的平臺(tái)。從實(shí)現(xiàn)上看集成方式是通過(guò)平臺(tái)提供的 REST API 完成的。以 GitLab 為例它會(huì)讀取合并請(qǐng)求的 iidInternal ID然后調(diào)用項(xiàng)目的 commits API 獲取本次 MR 的所有提交再調(diào)用/compare接口獲取與目標(biāo)分支的 diff 內(nèi)容。拿到 diff 之后逐文件逐行做規(guī)則分析最后通過(guò) note API 把每條問(wèn)題以評(píng)論的形式寫在對(duì)應(yīng)代碼行上。這里有個(gè)值得注意的技術(shù)細(xì)節(jié)diff 文件里的行號(hào)跟實(shí)際文件的全局行號(hào)不是一回事。diff 格式里每段都有 -l,s l,s 頭部表示舊文件和新文件的起始行號(hào)與區(qū)塊長(zhǎng)度。如果你直接拿 diff 里的行號(hào)去拼評(píng)論位置發(fā)到平臺(tái)上的評(píng)論會(huì)掛在不正確的代碼行上這是非常容易踩坑的地方。open-code-review 的處理方法是做一次行號(hào)映射解析增量段頭部維護(hù)一個(gè)diff 中的行號(hào)到實(shí)際新文件中的行號(hào)的轉(zhuǎn)換表再根據(jù)每條規(guī)則命中的代碼內(nèi)容反向定位。這個(gè)過(guò)程如果你自己在腳本里實(shí)現(xiàn)一定要先寫單測(cè)覆蓋各種頭部格式不然不同 diff 風(fēng)格下很容易出現(xiàn)偏移。3. 實(shí)操過(guò)程與核心環(huán)節(jié)實(shí)現(xiàn)3.1 本地運(yùn)行環(huán)境準(zhǔn)備我先說(shuō)一下我本地的部署嘗試。項(xiàng)目是用 Go 寫的編譯后是一個(gè)單二進(jìn)制文件非常方便在 CI 和本地之間復(fù)用。為了不污染開(kāi)發(fā)環(huán)境我直接用 Docker 跑了一次驗(yàn)證git clone https://github.com/example/open-code-review.git cd open-code-review docker build -t open-code-review:local .鏡像構(gòu)建完成后需要準(zhǔn)備一個(gè)包含平臺(tái)訪問(wèn)令牌的環(huán)境變量文件。以 GitLab 為例你需要生成一個(gè)具備api權(quán)限的 Personal Access Tokenexport OCR_GITLAB_URLhttps://gitlab.example.com export OCR_GITLAB_TOKENglpat-xxxxxxx export OCR_GITLAB_PROJECT_ID42 export OCR_MR_IID15然后在項(xiàng)目倉(cāng)庫(kù)根目錄創(chuàng)建.open-code-review.yaml配置文件并執(zhí)行docker run --rm \ -e OCR_GITLAB_URL \ -e OCR_GITLAB_TOKEN \ -e OCR_GITLAB_PROJECT_ID \ -e OCR_MR_IID \ -v $(pwd)/.open-code-review.yaml:/config.yaml \ open-code-review:local --config /config.yaml這里我重點(diǎn)解釋一下為什么要以環(huán)境變量的方式傳項(xiàng)目標(biāo)識(shí)而不是寫在配置里。因?yàn)樵趯?shí)際場(chǎng)景里同一個(gè)配置文件要復(fù)用到多個(gè)項(xiàng)目倉(cāng)庫(kù)中如果項(xiàng)目標(biāo)識(shí)寫死在 YAML 里每個(gè)團(tuán)隊(duì)都要復(fù)制一份配置文件。用環(huán)境變量注入后配置文件可以沉淀為團(tuán)隊(duì)模板。3.2 GitLab CI 接入配置實(shí)戰(zhàn)本地運(yùn)行驗(yàn)證通過(guò)之后就可以把工具接到 GitLab CI 里了。我推薦的做法是把它做成流水線里的一個(gè)獨(dú)立階段放在測(cè)試階段之前這樣可以盡早發(fā)現(xiàn)問(wèn)題。下面是一段我實(shí)際使用的.gitlab-ci.yml配置整理出來(lái)供參考code-review: stage: review image: docker:latest variables: DOCKER_DRIVER: overlay2 services: - docker:dind script: - docker build -t open-code-review . - docker run --rm -e OCR_GITLAB_URL${CI_SERVER_URL} -e OCR_GITLAB_TOKEN${GITLAB_TOKEN} -e OCR_GITLAB_PROJECT_ID${CI_PROJECT_ID} -e OCR_MR_IID${CI_MERGE_REQUEST_IID} -v ${CI_PROJECT_DIR}/.open-code-review.yaml:/config.yaml open-code-review --config /config.yaml only: - merge_requests有幾個(gè)地方需要特別說(shuō)明。第一CI_MERGE_REQUEST_IID這個(gè)變量只有流水線由合并請(qǐng)求事件觸發(fā)時(shí)才會(huì)被賦值。如果你手動(dòng)執(zhí)行流水線或者流水線是在分支提交時(shí)跑的這個(gè)變量會(huì)是空字符串工具會(huì)因?yàn)槟貌坏?MR 編號(hào)而退出。所以別忘記在only里限制merge_requests事件這是很多初用者最容易忽略的一步。第二GITLAB_TOKEN需要你在 GitLab 的 CI/CD Variables 里配置Scope 選Masked保護(hù)一下。注意不要把它寫在代碼倉(cāng)庫(kù)的配置文件里任何一個(gè)能看倉(cāng)庫(kù)內(nèi)容的人都能把它提取出來(lái)。第三用docker:dind服務(wù)來(lái)支持 Docker 構(gòu)建是一種比較重的方案。如果你的 GitLab Runner 已經(jīng)配置了 shell executor建議直接先把二進(jìn)制編譯好做成項(xiàng)目公共鏡像然后在流水線里用image: open-code-review:1.2.0直接引用這樣每次跑流水線就不用重復(fù)構(gòu)建速度會(huì)快很多。3.3 GitHub Actions 接入方式更簡(jiǎn)單如果你們工作流在 GitHub 上接入會(huì)更順滑。GitHub Actions 對(duì)這類在 PR 上發(fā)評(píng)論的工具支持極好核心原因是它內(nèi)置了GITHUB_TOKEN和豐富的 events 上下文。name: open-code-review on: pull_request: types: [opened, synchronize] permissions: contents: read pull-requests: write jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - name: Run open-code-review uses: your-org/open-code-review-actionv1 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: config: .open-code-review.yaml我一開(kāi)始接入時(shí)沒(méi)有寫fetch-depth: 0這個(gè)參數(shù)結(jié)果吃了大虧。工具分析 diff 需要訪問(wèn)完整的main分支歷史而默認(rèn) checkout 只拉取當(dāng)前 PR 的最新代碼和最小歷史最終導(dǎo)致對(duì)比結(jié)果錯(cuò)亂工具報(bào)了一堆莫名其妙的錯(cuò)誤位置。還有一點(diǎn)permissions里的pull-requests: write是必須顯式聲明的。GitHub 從 2023 年起收緊了GITHUB_TOKEN的默認(rèn)權(quán)限如果不聲明機(jī)器人發(fā)的評(píng)論會(huì)被拒絕報(bào) 403 錯(cuò)誤。這些都屬于開(kāi)始跑起來(lái)才會(huì)發(fā)現(xiàn)的問(wèn)題我放在后面的排查清單里詳細(xì)展開(kāi)。3.4 從零配置一套自定義審查規(guī)則除了內(nèi)置規(guī)則open-code-review 還支持自定義規(guī)則。對(duì)團(tuán)隊(duì)來(lái)說(shuō)這個(gè)過(guò)程其實(shí)是把團(tuán)隊(duì)約定沉淀成自動(dòng)化檢查的好機(jī)會(huì)。這個(gè)項(xiàng)目提供了基于 JSON Path 的自定義規(guī)則接口比如我想檢查項(xiàng)目?jī)?nèi)是否禁止直接調(diào)用requests.get()而必須走統(tǒng)一封裝的 HTTP 客戶端我可以寫一條自定義規(guī)則custom_rules: - name: no_direct_requests_get message: 請(qǐng)使用項(xiàng)目的 http_client 封裝發(fā)起網(wǎng)絡(luò)請(qǐng)求不要直接調(diào)用 requests.get severity: warning match: language: python expr: | Call(attrAttribute(attrName(idget), valueName(idrequests)))這里的expr用的是類似 AST 匹配的模式它能把代碼解析成抽象語(yǔ)法樹(shù)之后做結(jié)構(gòu)化匹配而不是簡(jiǎn)單的文本搜索。這意味著你不用擔(dān)心注釋里寫著requests.get被誤傷也不用擔(dān)心字符串類型里包含同樣內(nèi)容被誤判。這種結(jié)構(gòu)級(jí)匹配比正則表達(dá)式可靠得多也是它作為審查工具比較專業(yè)的地方。如果你之前只寫過(guò)簡(jiǎn)單的grep式檢查剛開(kāi)始用 AST 匹配會(huì)有學(xué)習(xí)成本但一旦熟悉了就會(huì)發(fā)現(xiàn)它的表達(dá)能力和準(zhǔn)確性上了一個(gè)臺(tái)階。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄4.1 評(píng)論位置錯(cuò)亂最常見(jiàn)的坑我第一次在真實(shí)項(xiàng)目里啟用 open-code-review 時(shí)遇到的最大問(wèn)題是評(píng)論位置不對(duì)。比如新增了 10 行代碼理論上規(guī)則命中應(yīng)該定位在第 8 行的位置結(jié)果評(píng)論掛在了第 3 行有的甚至跑到了文件的頭部。排查了一圈發(fā)現(xiàn)問(wèn)題出在 diff 的解析上。在 GitLab 的完整 diff 響應(yīng)中new_line和new_lines字段的值不是連續(xù)的因?yàn)樵谧兏鼔K中間可能夾雜著上下文行和平臺(tái)自身的標(biāo)記。比如一個(gè)文件新增了 20 行但 diff 響應(yīng)中出現(xiàn)的new_line可能是[1, 2, 3, 10, 11, 12, 13, 14]這種不連續(xù)的序列因?yàn)樗话袃?nèi)容變化的行不包含變更塊前后的上下文。如果你直接拿命中規(guī)則的 diff 索引去當(dāng)作行號(hào)用一定會(huì)錯(cuò)位。open-code-review 內(nèi)部是先用變更塊頭部的 -l,s l,s 建立映射然后逐行累加偏移量確保每條評(píng)論的落點(diǎn)準(zhǔn)確。假如你是自己實(shí)現(xiàn)類似的工具建議在解析 diff 階段就建立完整的映射表而不是在規(guī)則分析階段臨時(shí)推算。4.2 誤報(bào)太多導(dǎo)致團(tuán)隊(duì)免疫工具剛上線時(shí)最容易出現(xiàn)的問(wèn)題就是所有人都被機(jī)器人評(píng)論轟炸最后大家都免疫了看到機(jī)器人評(píng)論就直接忽略審閱體驗(yàn)反而變得更糟。我自己遇到的誤報(bào)來(lái)源主要有三類。第一類是規(guī)則閾值設(shè)得太激進(jìn)。比如max_added_lines默認(rèn)閾值設(shè)成 250但團(tuán)隊(duì)里很多人習(xí)慣在測(cè)試文件里一次性加十幾條用例每用例大約 20 行一次測(cè)試提交輕松超過(guò) 250 行。對(duì)代碼變更來(lái)說(shuō)這完全合理但對(duì)測(cè)試代碼來(lái)說(shuō)觸發(fā)閾值就是在制造噪音。解決辦法是把測(cè)試目錄加入ignore_paths或者針對(duì)測(cè)試文件降低規(guī)則的觸發(fā)動(dòng)機(jī)。第二類是命名規(guī)范規(guī)則在 Python 和 JavaScript 混用項(xiàng)目里的沖突。同一個(gè)倉(cāng)庫(kù)里后端 Python 代碼用snake_case前端 JS 代碼用camelCase如果規(guī)則沒(méi)有區(qū)分語(yǔ)言前端代碼會(huì)瘋狂觸發(fā)命名規(guī)則。open-code-review 支持按文件類型應(yīng)用規(guī)則比如rules_overrides: - paths: - frontend/** language: javascript enable_snake_case_check: false enable_camel_case_check: true第三類是約定型的公司內(nèi)部代碼被規(guī)則誤傷。比如我們公司內(nèi)部統(tǒng)一封裝了一個(gè)日志組件log內(nèi)部有l(wèi)og.println()之類的調(diào)試方法但有條規(guī)則恰好在檢查 禁止使用 console.log 時(shí)把log.println也匹配進(jìn)去了。這個(gè)問(wèn)題最終通過(guò)自定義規(guī)則的允許名單解決了?？刂普`報(bào)的核心原則跟調(diào)告警閾值一樣要讓每條評(píng)論都有足夠高的準(zhǔn)確率。寧可不報(bào)一個(gè)真實(shí)問(wèn)題也不要報(bào)三條里只有一條有用的。團(tuán)隊(duì)對(duì)工具的信心一旦建立起來(lái)后面配合度會(huì)高很多。4.3 CI 超時(shí)拖慢流水線接入自動(dòng)代碼審查之后工作流多了一個(gè)新環(huán)節(jié)CI 總時(shí)間難免會(huì)變長(zhǎng)。我遇到過(guò)一輪改造直接把整個(gè)流水線從 6 分鐘拖到了 11 分鐘。問(wèn)題出在沒(méi)有做增量運(yùn)算。open-code-review 在掃描時(shí)默認(rèn)會(huì)對(duì)每個(gè) MR 做全量文件掃描雖然規(guī)則會(huì)過(guò)濾掉沒(méi)有變更的文件但工具在啟動(dòng)階段仍然會(huì)初始化倉(cāng)庫(kù)的全部?jī)?nèi)容。對(duì)于大型 monorepo這個(gè)初始化的時(shí)間成本相當(dāng)可觀。優(yōu)化方案有兩個(gè)。最直接的是在配置里加scan_only_changed_files: true讓工具只對(duì)變更文件做規(guī)則檢查。第二個(gè)方案是為工具建立增量緩存這次掃描過(guò)的文件如果在上次審查后沒(méi)有變更直接跳過(guò)。GitHub Actions 有actions/cacheGitLab CI 可以對(duì)指定目錄做 cache。我用的是第二套方案把緩存目錄放在/tmp/ocr_cache下并用分支名作為 cache key效果很明顯。variables: OCR_CACHE_DIR: /tmp/ocr_cachecache: key: $CI_COMMIT_REF_SLUG paths: - /tmp/ocr_cache4.4 權(quán)限配置不生效還有一次失效發(fā)生在 GitLab 的 Bot 賬號(hào)權(quán)限上。我給機(jī)器人賬號(hào)開(kāi)了developer角色按理說(shuō)可以在 MR 上發(fā)評(píng)論。但實(shí)際運(yùn)行時(shí) API 返回 403查日志發(fā)現(xiàn)是創(chuàng)建 note 的接口權(quán)限不足。GitLab 的權(quán)限模型在這里有個(gè)細(xì)節(jié)開(kāi)發(fā)者角色可以去評(píng)論 MR但如果 MR 設(shè)置了只有項(xiàng)目成員可以評(píng)論并且機(jī)器人賬號(hào)不是 MR 的參與者則仍會(huì)被拒絕。解決路徑有兩個(gè)一是把機(jī)器人賬號(hào)提升為 maintainer 角色二是在 MR 級(jí)別的設(shè)置里放行機(jī)器人賬號(hào)。大多數(shù)團(tuán)隊(duì)選擇前者因?yàn)闄C(jī)器人賬號(hào)本來(lái)就是服務(wù)賬號(hào)權(quán)限高一點(diǎn)問(wèn)題不大。4.5 問(wèn)題速查表我把踩過(guò)的坑整理成了一個(gè)速查表方便后續(xù)排查時(shí)直接翻閱?，F(xiàn)象常見(jiàn)原因解決動(dòng)作評(píng)論掛在不正確的代碼行上diff 行號(hào)映射未轉(zhuǎn)換檢查頭部解析邏輯建立新舊行號(hào)映射流水線因工具報(bào)錯(cuò)而失敗在非 merge request 事件觸發(fā)了任務(wù)在 CI 配置里限制only: merge_requestsAPI 返回 403Token 權(quán)限不足或未聲明 write 權(quán)限檢查 Token scope補(bǔ)上pull-requests: write權(quán)限CI 總時(shí)間明顯變長(zhǎng)全量掃描所有文件開(kāi)啟scan_only_changed_files配置緩存路徑相同問(wèn)題被反復(fù)評(píng)論MR 反復(fù) push 觸發(fā)多次審查在工具配置里去重邏輯記錄已經(jīng)評(píng)論過(guò)的消息哈希忽略規(guī)則未生效忽略路徑是目錄但未加通配符確認(rèn)docs/**寫法而不是docs/5. 從工具到流程團(tuán)隊(duì)落地的一些心得自動(dòng)代碼審查工具本質(zhì)上是一種流程基礎(chǔ)設(shè)施它不是一個(gè)裝完就完事的獨(dú)立軟件需要跟團(tuán)隊(duì)已有的開(kāi)發(fā)節(jié)奏融合。我個(gè)人的建議是分階段引入。第一個(gè)月先只做告警型規(guī)則比如命名規(guī)范、調(diào)試語(yǔ)句殘留這些低風(fēng)險(xiǎn)高確定性的事項(xiàng)。這個(gè)階段目的是讓團(tuán)隊(duì)熟悉機(jī)器人的存在體會(huì)到自動(dòng)檢查省了我不少事。第二個(gè)月再加入偏向安全類的規(guī)則比如 SQL 注入、硬編碼密鑰這類問(wèn)題這些問(wèn)題開(kāi)發(fā)者自己容易忽略但影響面大機(jī)器人提出之后認(rèn)可度會(huì)很高。第三個(gè)月再考慮加入復(fù)雜度分析、文件規(guī)模檢查這類規(guī)則這類問(wèn)題比較主觀需要跟團(tuán)隊(duì)討論確認(rèn)閾值最好在周會(huì)上過(guò)一遍示例再統(tǒng)一上線。另外機(jī)器人評(píng)論的語(yǔ)氣也值得調(diào)教。我給工具配了一套自定義模板把錯(cuò)誤改成建議把你改成我們比如建議優(yōu)先使用項(xiàng)目封裝的http_client來(lái)做網(wǎng)絡(luò)請(qǐng)求這里直接調(diào)用requests.get雖然能跑通但在超時(shí)重試和日志追蹤上會(huì)缺失一層統(tǒng)一處理。如果確實(shí)需要直接使用麻煩在注釋里說(shuō)明一下原因。這種語(yǔ)氣比冷冰冰地說(shuō)禁止使用更容易讓團(tuán)隊(duì)成員接受也更符合團(tuán)隊(duì)內(nèi)部的技術(shù)氛圍。工具雖然是機(jī)器人但在團(tuán)隊(duì)協(xié)作里表達(dá)方式往往決定了反饋被接受的程度。如果你想在自己團(tuán)隊(duì)里推進(jìn)自動(dòng)化代碼審查我建議從最困擾團(tuán)隊(duì)的那個(gè)具體問(wèn)題出發(fā)。不必一步到位把全部規(guī)則都配上也不必將它做成阻斷門禁。它更像一個(gè)冷靜的代碼執(zhí)筆人在每次合并前幫你把容易疏漏的細(xì)節(jié)再看一遍。代碼審查這件事機(jī)器的歸機(jī)器人的歸人。把重復(fù)勞動(dòng)交給工具之后真正的 Review 才終于可以把力氣花在這個(gè)設(shè)計(jì)好不好這個(gè)抽象合不合理這些值得花力氣的地方上。希望這篇文章能幫你把團(tuán)隊(duì)代碼審查的自動(dòng)化之路走得更順。 開(kāi)源代碼審查工具 open-code-review 的原理與實(shí)戰(zhàn)
寫代碼這么多年我一直覺(jué)得 code review 是最能體現(xiàn)團(tuán)隊(duì)技術(shù)氛圍的一件事。代碼寫得好不好review 別人代碼時(shí)一針見(jiàn)血說(shuō)明你對(duì)自己寫的東西有沒(méi)有深入思考過(guò)。但現(xiàn)實(shí)很骨感項(xiàng)目趕進(jìn)度的時(shí)候Review 往往是最先被犧牲的環(huán)節(jié)。我見(jiàn)過(guò)太多團(tuán)隊(duì)嘴上說(shuō)一定要 review實(shí)際合并請(qǐng)求掛了兩三天沒(méi)人看或者 Reviewer 只回一句LGTM就合進(jìn)去了。這些場(chǎng)景背后都是同一個(gè)問(wèn)題人肉 review 的成本和效果不成正比。于是我開(kāi)始折騰自動(dòng)代碼審查測(cè)試過(guò)好幾款商業(yè)工具和開(kāi)源項(xiàng)目也在 CI 里折騰過(guò)各種靜態(tài)掃描方案。今天想聊的是我目前在用的一個(gè)開(kāi)源項(xiàng)目叫open-code-review。它不是那種玄乎的 AI 魔法也不是單純的 linter而是把靜態(tài)分析、規(guī)則引擎和代碼托管平臺(tái)的交互串起來(lái)的一套自動(dòng)化審查工具。說(shuō)白了它就是幫你把代碼審查里那些重復(fù)性、機(jī)械性的部分交給機(jī)器讓人把精力聚焦在真正需要判斷力的地方。這篇文章會(huì)從項(xiàng)目設(shè)計(jì)的思路聊起講清楚它內(nèi)部的規(guī)則機(jī)制、接入方式、在 GitLab/GitHub 上的實(shí)戰(zhàn)效果以及我踩過(guò)的一些坑。如果你正在糾結(jié)要不要給團(tuán)隊(duì)上自動(dòng)代碼審查用現(xiàn)成的商業(yè)版還是自己搭這篇應(yīng)該能給你一個(gè)比較完整的參考。1. 項(xiàng)目整體設(shè)計(jì)與思路拆解1.1 代碼審查的痛點(diǎn)到底在哪先說(shuō)個(gè)我觀察到的現(xiàn)象。很多團(tuán)隊(duì)并非不想做代碼審查而是Review的過(guò)程有天然的結(jié)構(gòu)性問(wèn)題。第一個(gè)痛點(diǎn)是時(shí)效性。一個(gè)合并請(qǐng)求提出之后早上的代碼下午才有人看下午的代碼第二天才有人回應(yīng)等到所有討論結(jié)束分支可能已經(jīng)落后主分支幾十個(gè)提交了。這個(gè)時(shí)間差會(huì)導(dǎo)致兩個(gè)后果一是 Reviewer 需要在腦子里重新理解一次上下文二是開(kāi)發(fā)者會(huì)傾向于在 review 期間繼續(xù)堆代碼最后合并請(qǐng)求膨脹到幾百行連作者自己都不想看。第二個(gè)痛點(diǎn)是注意力分配。人腦在檢查代碼時(shí)真正有價(jià)值的其實(shí)是這段邏輯對(duì)不對(duì)這個(gè)設(shè)計(jì)是否合理這種高層次的判斷。但現(xiàn)實(shí)中大部分 review 討論消耗在了這里空行多了這個(gè)變量命名不規(guī)范為什么不用現(xiàn)成的工具函數(shù)這類機(jī)械問(wèn)題上。不是說(shuō)這些問(wèn)題不重要但它們完全不需要一個(gè)資深工程師花時(shí)間去盯。第三個(gè)痛點(diǎn)是標(biāo)準(zhǔn)不一致。同一個(gè)團(tuán)隊(duì)里有的人對(duì)代碼風(fēng)格極其敏感有的人只關(guān)心功能是否正確。一個(gè)文件經(jīng)過(guò)不同人 review得到的反饋風(fēng)格可能完全不一樣這在團(tuán)隊(duì)規(guī)范尚未沉淀成文檔的初創(chuàng)團(tuán)隊(duì)里尤其明顯。open-code-review 想解決的就是后面這兩類問(wèn)題把機(jī)械檢查自動(dòng)化把標(biāo)準(zhǔn)統(tǒng)一固化進(jìn)規(guī)則引擎同時(shí)用機(jī)器評(píng)論的方式跟人工 review 形成互補(bǔ)而不是取代。1.2 這個(gè)項(xiàng)目到底做了什么從項(xiàng)目命名就能看出來(lái)它的核心是開(kāi)放——規(guī)則可配置、流程可接入、平臺(tái)可擴(kuò)展。我實(shí)際用下來(lái)它的定位介于傳統(tǒng) linter 和商業(yè)智能審查工具之間。傳統(tǒng) linter 比如 ESLint、Pylint 這類只管單個(gè)文件范圍內(nèi)的語(yǔ)法和風(fēng)格問(wèn)題它們跑在本地或 CI 里輸出一份報(bào)告就完事了。它們不懂哪個(gè)提交改了哪些文件這種版本上下文也不會(huì)主動(dòng)去對(duì)應(yīng)平臺(tái)里發(fā)評(píng)論。商業(yè)智能審查工具一般集成度高、開(kāi)箱即用但規(guī)則是黑盒出了問(wèn)題你很難定位它為什么報(bào)這一條而且價(jià)格對(duì)中小團(tuán)隊(duì)不太友好。open-code-review 走的是中間路線。它會(huì)讀取合并請(qǐng)求的變更內(nèi)容在變更的代碼上做分析然后以機(jī)器人的身份把問(wèn)題直接作為評(píng)論發(fā)到對(duì)應(yīng)的代碼行上。整個(gè)過(guò)程的規(guī)則完全暴露給你你可以看到每條檢查項(xiàng)是依據(jù)什么邏輯觸發(fā)的也可以隨時(shí)調(diào)整閾值和開(kāi)關(guān)。具體來(lái)說(shuō)這個(gè)項(xiàng)目的核心模塊包括變更提取模塊對(duì)接代碼托管平臺(tái) API拉取合并請(qǐng)求的 diff 數(shù)據(jù)規(guī)則引擎內(nèi)置一批開(kāi)箱即用的檢查規(guī)則同時(shí)支持自定義規(guī)則配置評(píng)論發(fā)送模塊把審查結(jié)果按文件按行寫入評(píng)論區(qū)報(bào)告生成模塊輸出一份整體的審查摘要便于在 CI 日志里查看我之前在幾個(gè)內(nèi)部項(xiàng)目里接入了一輪整體感受是輕容器鏡像很小配置文件是 YAML塞進(jìn) GitLab CI 或者 GitHub Actions 里只要十幾分鐘就能跑完首輪。1.3 為什么推薦組合式架構(gòu)而不是一個(gè)腳本搞定剛開(kāi)始我也想得很簡(jiǎn)單寫個(gè) Python 腳本拉 diff然后調(diào)一段規(guī)則判斷最后 POST 評(píng)論到 API。聽(tīng)起來(lái)半天就能搞定。但真正做起來(lái)會(huì)發(fā)現(xiàn)一個(gè)問(wèn)題這個(gè)腳本會(huì)越寫越復(fù)雜。一開(kāi)始只是檢查新增代碼里有沒(méi)有 TODO 標(biāo)記后來(lái)想加禁止直接在生產(chǎn)代碼里使用 console.log再后來(lái)想加文件是否超過(guò) 500 行是否有重復(fù)度高的相似代碼段每個(gè)需求都是獨(dú)立維度如果全寫在一個(gè)大腳本里最終的維護(hù)成本會(huì)高到你想重寫。open-code-review 的架構(gòu)思路是把這些能力拆成模塊規(guī)則之間解耦。每條規(guī)則只負(fù)責(zé)一件事輸入是某個(gè)文件的某一行或某一段代碼輸出是一條或零條問(wèn)題記錄。這樣新增規(guī)則的時(shí)候不需要?jiǎng)悠渌a只需要往規(guī)則目錄里放一個(gè)文件并在配置文件里聲明啟用即可。這也是我想給所有準(zhǔn)備折騰類似工具的人一個(gè)建議任何自動(dòng)化審查工具的架構(gòu)都應(yīng)該按照數(shù)據(jù)采集、分析判斷、結(jié)果回寫三層去設(shè)計(jì)。分層越清晰后面加功能越省力。2. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)2.1 規(guī)則引擎的設(shè)計(jì)思路與典型規(guī)則規(guī)則引擎是整個(gè)項(xiàng)目的核心也是我最喜歡研究的部分。它內(nèi)置了幾類規(guī)則我分別說(shuō)一下它們的檢查邏輯。第一類是關(guān)鍵詞掃描規(guī)則。比如在代碼里搜索TODO、FIXME、HACK這些標(biāo)記它們往往意味著開(kāi)發(fā)者留下了一個(gè)未完成的事務(wù)。這個(gè)掃描不是簡(jiǎn)單地在整個(gè)文件里找字符串而是只針對(duì)本次變更新增的行做匹配所以不會(huì)把歷史上遺留的 TODO 全都報(bào)一遍只會(huì)提示你這次新增的代碼里又引入了新的 TODO請(qǐng)確認(rèn)是否合理。第二類是編碼規(guī)范規(guī)則。以 Python 項(xiàng)目為例它會(huì)檢查新增代碼里的命名風(fēng)格比如函數(shù)名是不是小寫下劃線、類名是不是駝峰式也會(huì)檢查常見(jiàn)的函數(shù)參數(shù)長(zhǎng)度超過(guò)閾值單行代碼過(guò)長(zhǎng)這類問(wèn)題。這類規(guī)則跟 PyLint 有重疊但它的優(yōu)勢(shì)是能站在 diff 的粒度上工作只提示變化的部分不會(huì)把整個(gè)項(xiàng)目的存量問(wèn)題一次性拋給你。第三類是安全隱患規(guī)則。比如檢測(cè)代碼里是否拼接了 SQL 語(yǔ)句而非使用參數(shù)化查詢是否在日志里打印了包含password、token、secret等關(guān)鍵字的變量值是否存在把敏感信息硬編碼進(jìn)代碼的嫌疑。這類規(guī)則的價(jià)值在于它能在代碼評(píng)審之前先替人眼掃一遍最容易出問(wèn)題的幾個(gè)點(diǎn)。第四類是工程結(jié)構(gòu)規(guī)則。檢查單次變更涉及的文件數(shù)量是否過(guò)多、單個(gè)文件的新增行數(shù)是否過(guò)大、是否引入了新的第三方依賴但未更新依賴鎖定文件等等。我自己就在規(guī)則里加過(guò)一條禁止在共享公共模塊里直接使用print()輸出調(diào)試信息因?yàn)樗鼤?huì)污染標(biāo)準(zhǔn)輸出流。用它的規(guī)則配置接口實(shí)現(xiàn)起來(lái)并不復(fù)雜大致是把這條規(guī)則聲明成匹配函數(shù)名print且調(diào)用點(diǎn)位于特定目錄下的組合條件。2.2 規(guī)則配置文件的要點(diǎn)解析open-code-review 使用 YAML 作為配置格式根目錄下默認(rèn)的配置文件類似這樣project: language: python base_branch: main rules: enabled: - todo_check - forbidden_function_check - large_diff_check - sql_injection_check disabled: [] thresholds: max_added_lines: 250 max_file_count: 10 ignore_paths: - docs/** - tests/test_data/**這里有三個(gè)關(guān)鍵概念要理解。第一個(gè)是base_branch。它決定了變更的對(duì)比基準(zhǔn)差分動(dòng)作會(huì)拿當(dāng)前分支跟這個(gè)基準(zhǔn)分支做對(duì)比從而得到精確的變更列表。默認(rèn)設(shè)成主干分支名如果你的團(tuán)隊(duì)用的是master或者trunk要同步改過(guò)來(lái)否則提取出來(lái)的變更集會(huì)跟你預(yù)期完全不一樣。第二個(gè)是thresholds閾值配置。max_added_lines: 250的含義是單次變更新增超過(guò) 250 行時(shí)觸發(fā)提醒。這個(gè)值需要根據(jù)團(tuán)隊(duì)實(shí)際節(jié)奏調(diào)整。如果你們的合并請(qǐng)求普遍在 100 行以內(nèi)設(shè)置成 250 就太寬松了規(guī)則基本不觸發(fā)。反過(guò)來(lái)如果團(tuán)隊(duì)經(jīng)常有大規(guī)模重構(gòu)的合并請(qǐng)求設(shè)得太小會(huì)產(chǎn)生大量噪音評(píng)論。第三個(gè)是ignore_paths忽略規(guī)則。這個(gè)非常實(shí)用。項(xiàng)目里總有一些不需要審查的目錄比如docs/文檔目錄、tests/test_data/測(cè)試數(shù)據(jù)目錄、還有自動(dòng)生成的代碼。不忽略這些路徑的話每次提交都會(huì)在文檔改幾個(gè)字時(shí)觸發(fā)一堆無(wú)關(guān)緊要的評(píng)論。2.3 與代碼托管平臺(tái)集成的方式作為一個(gè)自動(dòng)代碼審查工具它必須要跟代碼托管平臺(tái)深度結(jié)合才有意義。目前它支持 GitHub、GitLab 以及 Gitea 這三類常見(jiàn)的平臺(tái)。從實(shí)現(xiàn)上看集成方式是通過(guò)平臺(tái)提供的 REST API 完成的。以 GitLab 為例它會(huì)讀取合并請(qǐng)求的 iidInternal ID然后調(diào)用項(xiàng)目的 commits API 獲取本次 MR 的所有提交再調(diào)用/compare接口獲取與目標(biāo)分支的 diff 內(nèi)容。拿到 diff 之后逐文件逐行做規(guī)則分析最后通過(guò) note API 把每條問(wèn)題以評(píng)論的形式寫在對(duì)應(yīng)代碼行上。這里有個(gè)值得注意的技術(shù)細(xì)節(jié)diff 文件里的行號(hào)跟實(shí)際文件的全局行號(hào)不是一回事。diff 格式里每段都有 -l,s l,s 頭部表示舊文件和新文件的起始行號(hào)與區(qū)塊長(zhǎng)度。如果你直接拿 diff 里的行號(hào)去拼評(píng)論位置發(fā)到平臺(tái)上的評(píng)論會(huì)掛在不正確的代碼行上這是非常容易踩坑的地方。open-code-review 的處理方法是做一次行號(hào)映射解析增量段頭部維護(hù)一個(gè)diff 中的行號(hào)到實(shí)際新文件中的行號(hào)的轉(zhuǎn)換表再根據(jù)每條規(guī)則命中的代碼內(nèi)容反向定位。這個(gè)過(guò)程如果你自己在腳本里實(shí)現(xiàn)一定要先寫單測(cè)覆蓋各種頭部格式不然不同 diff 風(fēng)格下很容易出現(xiàn)偏移。3. 實(shí)操過(guò)程與核心環(huán)節(jié)實(shí)現(xiàn)3.1 本地運(yùn)行環(huán)境準(zhǔn)備我先說(shuō)一下我本地的部署嘗試。項(xiàng)目是用 Go 寫的編譯后是一個(gè)單二進(jìn)制文件非常方便在 CI 和本地之間復(fù)用。為了不污染開(kāi)發(fā)環(huán)境我直接用 Docker 跑了一次驗(yàn)證git clone https://github.com/example/open-code-review.git cd open-code-review docker build -t open-code-review:local .鏡像構(gòu)建完成后需要準(zhǔn)備一個(gè)包含平臺(tái)訪問(wèn)令牌的環(huán)境變量文件。以 GitLab 為例你需要生成一個(gè)具備api權(quán)限的 Personal Access Tokenexport OCR_GITLAB_URLhttps://gitlab.example.com export OCR_GITLAB_TOKENglpat-xxxxxxx export OCR_GITLAB_PROJECT_ID42 export OCR_MR_IID15然后在項(xiàng)目倉(cāng)庫(kù)根目錄創(chuàng)建.open-code-review.yaml配置文件并執(zhí)行docker run --rm \ -e OCR_GITLAB_URL \ -e OCR_GITLAB_TOKEN \ -e OCR_GITLAB_PROJECT_ID \ -e OCR_MR_IID \ -v $(pwd)/.open-code-review.yaml:/config.yaml \ open-code-review:local --config /config.yaml這里我重點(diǎn)解釋一下為什么要以環(huán)境變量的方式傳項(xiàng)目標(biāo)識(shí)而不是寫在配置里。因?yàn)樵趯?shí)際場(chǎng)景里同一個(gè)配置文件要復(fù)用到多個(gè)項(xiàng)目倉(cāng)庫(kù)中如果項(xiàng)目標(biāo)識(shí)寫死在 YAML 里每個(gè)團(tuán)隊(duì)都要復(fù)制一份配置文件。用環(huán)境變量注入后配置文件可以沉淀為團(tuán)隊(duì)模板。3.2 GitLab CI 接入配置實(shí)戰(zhàn)本地運(yùn)行驗(yàn)證通過(guò)之后就可以把工具接到 GitLab CI 里了。我推薦的做法是把它做成流水線里的一個(gè)獨(dú)立階段放在測(cè)試階段之前這樣可以盡早發(fā)現(xiàn)問(wèn)題。下面是一段我實(shí)際使用的.gitlab-ci.yml配置整理出來(lái)供參考code-review: stage: review image: docker:latest variables: DOCKER_DRIVER: overlay2 services: - docker:dind script: - docker build -t open-code-review . - docker run --rm -e OCR_GITLAB_URL${CI_SERVER_URL} -e OCR_GITLAB_TOKEN${GITLAB_TOKEN} -e OCR_GITLAB_PROJECT_ID${CI_PROJECT_ID} -e OCR_MR_IID${CI_MERGE_REQUEST_IID} -v ${CI_PROJECT_DIR}/.open-code-review.yaml:/config.yaml open-code-review --config /config.yaml only: - merge_requests有幾個(gè)地方需要特別說(shuō)明。第一CI_MERGE_REQUEST_IID這個(gè)變量只有流水線由合并請(qǐng)求事件觸發(fā)時(shí)才會(huì)被賦值。如果你手動(dòng)執(zhí)行流水線或者流水線是在分支提交時(shí)跑的這個(gè)變量會(huì)是空字符串工具會(huì)因?yàn)槟貌坏?MR 編號(hào)而退出。所以別忘記在only里限制merge_requests事件這是很多初用者最容易忽略的一步。第二GITLAB_TOKEN需要你在 GitLab 的 CI/CD Variables 里配置Scope 選Masked保護(hù)一下。注意不要把它寫在代碼倉(cāng)庫(kù)的配置文件里任何一個(gè)能看倉(cāng)庫(kù)內(nèi)容的人都能把它提取出來(lái)。第三用docker:dind服務(wù)來(lái)支持 Docker 構(gòu)建是一種比較重的方案。如果你的 GitLab Runner 已經(jīng)配置了 shell executor建議直接先把二進(jìn)制編譯好做成項(xiàng)目公共鏡像然后在流水線里用image: open-code-review:1.2.0直接引用這樣每次跑流水線就不用重復(fù)構(gòu)建速度會(huì)快很多。3.3 GitHub Actions 接入方式更簡(jiǎn)單如果你們工作流在 GitHub 上接入會(huì)更順滑。GitHub Actions 對(duì)這類在 PR 上發(fā)評(píng)論的工具支持極好核心原因是它內(nèi)置了GITHUB_TOKEN和豐富的 events 上下文。name: open-code-review on: pull_request: types: [opened, synchronize] permissions: contents: read pull-requests: write jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - name: Run open-code-review uses: your-org/open-code-review-actionv1 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: config: .open-code-review.yaml我一開(kāi)始接入時(shí)沒(méi)有寫fetch-depth: 0這個(gè)參數(shù)結(jié)果吃了大虧。工具分析 diff 需要訪問(wèn)完整的main分支歷史而默認(rèn) checkout 只拉取當(dāng)前 PR 的最新代碼和最小歷史最終導(dǎo)致對(duì)比結(jié)果錯(cuò)亂工具報(bào)了一堆莫名其妙的錯(cuò)誤位置。還有一點(diǎn)permissions里的pull-requests: write是必須顯式聲明的。GitHub 從 2023 年起收緊了GITHUB_TOKEN的默認(rèn)權(quán)限如果不聲明機(jī)器人發(fā)的評(píng)論會(huì)被拒絕報(bào) 403 錯(cuò)誤。這些都屬于開(kāi)始跑起來(lái)才會(huì)發(fā)現(xiàn)的問(wèn)題我放在后面的排查清單里詳細(xì)展開(kāi)。3.4 從零配置一套自定義審查規(guī)則除了內(nèi)置規(guī)則open-code-review 還支持自定義規(guī)則。對(duì)團(tuán)隊(duì)來(lái)說(shuō)這個(gè)過(guò)程其實(shí)是把團(tuán)隊(duì)約定沉淀成自動(dòng)化檢查的好機(jī)會(huì)。這個(gè)項(xiàng)目提供了基于 JSON Path 的自定義規(guī)則接口比如我想檢查項(xiàng)目?jī)?nèi)是否禁止直接調(diào)用requests.get()而必須走統(tǒng)一封裝的 HTTP 客戶端我可以寫一條自定義規(guī)則custom_rules: - name: no_direct_requests_get message: 請(qǐng)使用項(xiàng)目的 http_client 封裝發(fā)起網(wǎng)絡(luò)請(qǐng)求不要直接調(diào)用 requests.get severity: warning match: language: python expr: | Call(attrAttribute(attrName(idget), valueName(idrequests)))這里的expr用的是類似 AST 匹配的模式它能把代碼解析成抽象語(yǔ)法樹(shù)之后做結(jié)構(gòu)化匹配而不是簡(jiǎn)單的文本搜索。這意味著你不用擔(dān)心注釋里寫著requests.get被誤傷也不用擔(dān)心字符串類型里包含同樣內(nèi)容被誤判。這種結(jié)構(gòu)級(jí)匹配比正則表達(dá)式可靠得多也是它作為審查工具比較專業(yè)的地方。如果你之前只寫過(guò)簡(jiǎn)單的grep式檢查剛開(kāi)始用 AST 匹配會(huì)有學(xué)習(xí)成本但一旦熟悉了就會(huì)發(fā)現(xiàn)它的表達(dá)能力和準(zhǔn)確性上了一個(gè)臺(tái)階。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄4.1 評(píng)論位置錯(cuò)亂最常見(jiàn)的坑我第一次在真實(shí)項(xiàng)目里啟用 open-code-review 時(shí)遇到的最大問(wèn)題是評(píng)論位置不對(duì)。比如新增了 10 行代碼理論上規(guī)則命中應(yīng)該定位在第 8 行的位置結(jié)果評(píng)論掛在了第 3 行有的甚至跑到了文件的頭部。排查了一圈發(fā)現(xiàn)問(wèn)題出在 diff 的解析上。在 GitLab 的完整 diff 響應(yīng)中new_line和new_lines字段的值不是連續(xù)的因?yàn)樵谧兏鼔K中間可能夾雜著上下文行和平臺(tái)自身的標(biāo)記。比如一個(gè)文件新增了 20 行但 diff 響應(yīng)中出現(xiàn)的new_line可能是[1, 2, 3, 10, 11, 12, 13, 14]這種不連續(xù)的序列因?yàn)樗话袃?nèi)容變化的行不包含變更塊前后的上下文。如果你直接拿命中規(guī)則的 diff 索引去當(dāng)作行號(hào)用一定會(huì)錯(cuò)位。open-code-review 內(nèi)部是先用變更塊頭部的 -l,s l,s 建立映射然后逐行累加偏移量確保每條評(píng)論的落點(diǎn)準(zhǔn)確。假如你是自己實(shí)現(xiàn)類似的工具建議在解析 diff 階段就建立完整的映射表而不是在規(guī)則分析階段臨時(shí)推算。4.2 誤報(bào)太多導(dǎo)致團(tuán)隊(duì)免疫工具剛上線時(shí)最容易出現(xiàn)的問(wèn)題就是所有人都被機(jī)器人評(píng)論轟炸最后大家都免疫了看到機(jī)器人評(píng)論就直接忽略審閱體驗(yàn)反而變得更糟。我自己遇到的誤報(bào)來(lái)源主要有三類。第一類是規(guī)則閾值設(shè)得太激進(jìn)。比如max_added_lines默認(rèn)閾值設(shè)成 250但團(tuán)隊(duì)里很多人習(xí)慣在測(cè)試文件里一次性加十幾條用例每用例大約 20 行一次測(cè)試提交輕松超過(guò) 250 行。對(duì)代碼變更來(lái)說(shuō)這完全合理但對(duì)測(cè)試代碼來(lái)說(shuō)觸發(fā)閾值就是在制造噪音。解決辦法是把測(cè)試目錄加入ignore_paths或者針對(duì)測(cè)試文件降低規(guī)則的觸發(fā)動(dòng)機(jī)。第二類是命名規(guī)范規(guī)則在 Python 和 JavaScript 混用項(xiàng)目里的沖突。同一個(gè)倉(cāng)庫(kù)里后端 Python 代碼用snake_case前端 JS 代碼用camelCase如果規(guī)則沒(méi)有區(qū)分語(yǔ)言前端代碼會(huì)瘋狂觸發(fā)命名規(guī)則。open-code-review 支持按文件類型應(yīng)用規(guī)則比如rules_overrides: - paths: - frontend/** language: javascript enable_snake_case_check: false enable_camel_case_check: true第三類是約定型的公司內(nèi)部代碼被規(guī)則誤傷。比如我們公司內(nèi)部統(tǒng)一封裝了一個(gè)日志組件log內(nèi)部有l(wèi)og.println()之類的調(diào)試方法但有條規(guī)則恰好在檢查 禁止使用 console.log 時(shí)把log.println也匹配進(jìn)去了。這個(gè)問(wèn)題最終通過(guò)自定義規(guī)則的允許名單解決了?？刂普`報(bào)的核心原則跟調(diào)告警閾值一樣要讓每條評(píng)論都有足夠高的準(zhǔn)確率。寧可不報(bào)一個(gè)真實(shí)問(wèn)題也不要報(bào)三條里只有一條有用的。團(tuán)隊(duì)對(duì)工具的信心一旦建立起來(lái)后面配合度會(huì)高很多。4.3 CI 超時(shí)拖慢流水線接入自動(dòng)代碼審查之后工作流多了一個(gè)新環(huán)節(jié)CI 總時(shí)間難免會(huì)變長(zhǎng)。我遇到過(guò)一輪改造直接把整個(gè)流水線從 6 分鐘拖到了 11 分鐘。問(wèn)題出在沒(méi)有做增量運(yùn)算。open-code-review 在掃描時(shí)默認(rèn)會(huì)對(duì)每個(gè) MR 做全量文件掃描雖然規(guī)則會(huì)過(guò)濾掉沒(méi)有變更的文件但工具在啟動(dòng)階段仍然會(huì)初始化倉(cāng)庫(kù)的全部?jī)?nèi)容。對(duì)于大型 monorepo這個(gè)初始化的時(shí)間成本相當(dāng)可觀。優(yōu)化方案有兩個(gè)。最直接的是在配置里加scan_only_changed_files: true讓工具只對(duì)變更文件做規(guī)則檢查。第二個(gè)方案是為工具建立增量緩存這次掃描過(guò)的文件如果在上次審查后沒(méi)有變更直接跳過(guò)。GitHub Actions 有actions/cacheGitLab CI 可以對(duì)指定目錄做 cache。我用的是第二套方案把緩存目錄放在/tmp/ocr_cache下并用分支名作為 cache key效果很明顯。variables: OCR_CACHE_DIR: /tmp/ocr_cachecache: key: $CI_COMMIT_REF_SLUG paths: - /tmp/ocr_cache4.4 權(quán)限配置不生效還有一次失效發(fā)生在 GitLab 的 Bot 賬號(hào)權(quán)限上。我給機(jī)器人賬號(hào)開(kāi)了developer角色按理說(shuō)可以在 MR 上發(fā)評(píng)論。但實(shí)際運(yùn)行時(shí) API 返回 403查日志發(fā)現(xiàn)是創(chuàng)建 note 的接口權(quán)限不足。GitLab 的權(quán)限模型在這里有個(gè)細(xì)節(jié)開(kāi)發(fā)者角色可以去評(píng)論 MR但如果 MR 設(shè)置了只有項(xiàng)目成員可以評(píng)論并且機(jī)器人賬號(hào)不是 MR 的參與者則仍會(huì)被拒絕。解決路徑有兩個(gè)一是把機(jī)器人賬號(hào)提升為 maintainer 角色二是在 MR 級(jí)別的設(shè)置里放行機(jī)器人賬號(hào)。大多數(shù)團(tuán)隊(duì)選擇前者因?yàn)闄C(jī)器人賬號(hào)本來(lái)就是服務(wù)賬號(hào)權(quán)限高一點(diǎn)問(wèn)題不大。4.5 問(wèn)題速查表我把踩過(guò)的坑整理成了一個(gè)速查表方便后續(xù)排查時(shí)直接翻閱?，F(xiàn)象常見(jiàn)原因解決動(dòng)作評(píng)論掛在不正確的代碼行上diff 行號(hào)映射未轉(zhuǎn)換檢查頭部解析邏輯建立新舊行號(hào)映射流水線因工具報(bào)錯(cuò)而失敗在非 merge request 事件觸發(fā)了任務(wù)在 CI 配置里限制only: merge_requestsAPI 返回 403Token 權(quán)限不足或未聲明 write 權(quán)限檢查 Token scope補(bǔ)上pull-requests: write權(quán)限CI 總時(shí)間明顯變長(zhǎng)全量掃描所有文件開(kāi)啟scan_only_changed_files配置緩存路徑相同問(wèn)題被反復(fù)評(píng)論MR 反復(fù) push 觸發(fā)多次審查在工具配置里去重邏輯記錄已經(jīng)評(píng)論過(guò)的消息哈希忽略規(guī)則未生效忽略路徑是目錄但未加通配符確認(rèn)docs/**寫法而不是docs/5. 從工具到流程團(tuán)隊(duì)落地的一些心得自動(dòng)代碼審查工具本質(zhì)上是一種流程基礎(chǔ)設(shè)施它不是一個(gè)裝完就完事的獨(dú)立軟件需要跟團(tuán)隊(duì)已有的開(kāi)發(fā)節(jié)奏融合。我個(gè)人的建議是分階段引入。第一個(gè)月先只做告警型規(guī)則比如命名規(guī)范、調(diào)試語(yǔ)句殘留這些低風(fēng)險(xiǎn)高確定性的事項(xiàng)。這個(gè)階段目的是讓團(tuán)隊(duì)熟悉機(jī)器人的存在體會(huì)到自動(dòng)檢查省了我不少事。第二個(gè)月再加入偏向安全類的規(guī)則比如 SQL 注入、硬編碼密鑰這類問(wèn)題這些問(wèn)題開(kāi)發(fā)者自己容易忽略但影響面大機(jī)器人提出之后認(rèn)可度會(huì)很高。第三個(gè)月再考慮加入復(fù)雜度分析、文件規(guī)模檢查這類規(guī)則這類問(wèn)題比較主觀需要跟團(tuán)隊(duì)討論確認(rèn)閾值最好在周會(huì)上過(guò)一遍示例再統(tǒng)一上線。另外機(jī)器人評(píng)論的語(yǔ)氣也值得調(diào)教。我給工具配了一套自定義模板把錯(cuò)誤改成建議把你改成我們比如建議優(yōu)先使用項(xiàng)目封裝的http_client來(lái)做網(wǎng)絡(luò)請(qǐng)求這里直接調(diào)用requests.get雖然能跑通但在超時(shí)重試和日志追蹤上會(huì)缺失一層統(tǒng)一處理。如果確實(shí)需要直接使用麻煩在注釋里說(shuō)明一下原因。這種語(yǔ)氣比冷冰冰地說(shuō)禁止使用更容易讓團(tuán)隊(duì)成員接受也更符合團(tuán)隊(duì)內(nèi)部的技術(shù)氛圍。工具雖然是機(jī)器人但在團(tuán)隊(duì)協(xié)作里表達(dá)方式往往決定了反饋被接受的程度。如果你想在自己團(tuán)隊(duì)里推進(jìn)自動(dòng)化代碼審查我建議從最困擾團(tuán)隊(duì)的那個(gè)具體問(wèn)題出發(fā)。不必一步到位把全部規(guī)則都配上也不必將它做成阻斷門禁。它更像一個(gè)冷靜的代碼執(zhí)筆人在每次合并前幫你把容易疏漏的細(xì)節(jié)再看一遍。代碼審查這件事機(jī)器的歸機(jī)器人的歸人。把重復(fù)勞動(dòng)交給工具之后真正的 Review 才終于可以把力氣花在這個(gè)設(shè)計(jì)好不好這個(gè)抽象合不合理這些值得花力氣的地方上。希望這篇文章能幫你把團(tuán)隊(duì)代碼審查的自動(dòng)化之路走得更順。