
本文為投稿文章,作者:PPPan。屬於 iOS 持續集成系列之一,同系列另有〈開篇〉、〈自動化單元測試〉與〈自動化打包與分發〉。
為保證代碼質量,Code Review 是極重要的一環。從星號的位置是否規範,到代碼結構是否符合軟件工程的基本原則,都在這項工作的覆蓋範圍內。
現實是,多數團隊沒有足夠時間做完整的 Code Review,於是只能把一部分工作交給計算機。我們只要定好合理流程,用代碼告訴機器該檢查什麼,剩下的交給這位可靠的夥伴。
導入自動化 Code Review 之後,代碼寫得不好,Xcode 會直接讓你難受:

如果你無視 Xcode 的心情,質量管理平台也會默默把這一切記錄下來:

這套機制既幫開發者寫出更高質量的代碼,也為管理者評估工程質量提供了一個切面,而維護成本相當低。

關鍵在於本地 Review 與遠端 Review 兩步。前者給開發者即時的質量回饋,讓問題在提交前就被修掉,避免在遠端 Review 拿到難看的分數;後者負責生成報表,為項目管理人員追蹤質量提供依據——在很多大公司,這也是績效參考之一。
其餘都是膠水步驟:用 WebHook 自動觸發遠端 Review、用 Git 鉤子做增量校驗而非全量校驗等。先看本地校驗。

開發者照平時一樣按下 CMD + B,等進度條跑完,滿屏警告就會精準指出某一行違反了哪條規則,接著依規範修正即可。從按下按鍵到產生警告,實際發生三件事:
生成 compile_commands.json 文件
OCLint 讀取相關 Rules,逐個掃描 compile_commands.json 中的 .m 文件
OCLint 把結果回報到 Xcode 上
核心就是 OCLint 與 compile_commands.json。
OCLint 是一套開源的靜態代碼分析器,以 C++ 撰寫、基於 Clang,支援 C、C++ 與 Objective-C。它在掃描過程中動態加載規則文件,因此能實現高度自定義的分析方案,並可與 Cmake、Bear、xcodebuild、xctool、Xcode、xcpretty、Jenkins CI、Travis CI 等無縫整合。
最新版本自帶 71 條 Rules,多數源自前人經驗——例如禁用 goto 的那條,就來自 Edsger W. Dijkstra 1968 年的手稿。這 71 條能擋掉一部分因書寫習慣與語言誤區造成的問題,但對有完整編碼規範的公司顯然不夠,我們必須自己寫 Rules。
好消息是 OCLint 已經準備好一切。它封裝了 Clang 與 AST(抽象語法樹),我們不必解析語法樹,只需專注規則邏輯。從它的接口就能看出這份體貼:
// 遇到一元操作符 bool VisitUnaryOperator(UnaryOperator *node) // 遇到二元操作符 bool VisitBinaryOperator(BinaryOperator *node) // 遇到 Objective-C 方法聲明 bool VisitObjCMethodDecl(ObjCMethodDecl *node)
規則開發完成後打包成 dylib,分析時加載即可。
這是 Clang 定義的一項規範,內容是一組工作目錄、目標文件與需執行的命令,讓工具能脫離編譯系統,把源碼轉成 AST 再做處理。看內容會更直觀:
[ { "directory": "/path/to/project/", "command": "/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang -x ...", "file": "/path/to/project/XXXViewController.m"}, ... ]OCLint 依此批量檢查源碼文件。
怎麼生成 compile_commands.json?最便捷的方式是用 oclint-xcodebuild:先讓 xcodebuild 產出日誌,再轉換。
xcodebuild | tee xcodebuild.log oclint-xcodebuild
截至 Xcode 8.1,這種做法仍能正確生成 json。但 OCLint 團隊已聲明不再維護 oclint-xcodebuild,未來某個 Xcode 版本可能失效。
另一個推薦方案是 xcpretty,一行搞定:
xcodebuild | xcpretty -r json-compilation-database --output /path/to/compile_commands.json
流程很簡單:本地安裝 OCLint 並取得公司自定義 Rules → 在 Xcode 中配置工程 → build,等待結果顯示。附上一份我們團隊的配置腳本:
source ~/.bash_profile cd ${SRCROOT} xcodebuild clean xcodebuild | tee xcodebuild.log oclint-xcodebuild oclint-json-compilation-database \ -e Vendor \ -e Pods \ -- \ -max-priority-1 100000 \ -max-priority-2 100000 \ -max-priority-3 100000 \ -report-type xcode \ -R /path/to/rules
遠端與本地大體相似,差別在於引用構建腳本的不再是 Xcode 而是 Jenkins CI,報表展示者從 Xcode 變成 SonarQube。流程如下:
工程師 git push 提交代碼 → Web Hook 觸發 Jenkins 構建 → OCLint 掃描並生成 PMD 格式報告 → Sonar-runner 讀取報告並呈現在 SonarQube。
由於 iOS 的特殊性,服務端必須是 macOS 系統。CI 選用開源的 Jenkins,質量管理平台選用開源的 SonarQube。SonarQube 上可以看到項目的代碼行數、文件數量、重複率、違反的規範、技術債時間等指標。它對 Java 極度友好,提供 SonarScanner 直接掃描源碼;Objective-C 就沒這麼幸運——報告展示可以,靜態分析仍得靠 OCLint。
Jenkins 上跑完 OCLint 後,需要一個中間人把報告解析成 SonarQube 認得的格式並上傳,這就是 Sonnar-Runner。它在我們的系統裡只扮演搬運工。由於它僅能解析 PMD 格式,因此 OCLint 需輸出為 PMD:
oclint -report-type pmd -o ./report.xml
SonarQube 自有一套規則,把代碼問題按嚴重程度分為五級,不同等級以不同權重影響項目質量評分。這套規則的 Rule name 必須與 OCLint 報告中的名稱一一對應,SonarQube 才能正確歸類並評分。
若使用 OCLint 原生 Rules,只需在 SonarQube 安裝 SonarQube Plugin for Objective C 即可正確識別。若使用自開發 Rules,則 Clone 該插件,在 profile-oclint.xml 與 rules.txt 中加入相應 rule name,打包後安裝即可。
舉例來說,用自開發 Rule 檢查完代碼後產出的 report.xml 中:

其中 binary operator space (HT_iOS_Coding_style 2.8) 就是我們自定義的錯誤名稱,SonarQube 上也必須存在同名 rule 才能正確識別。

接著在 profile-oclint.xml 補上對應片段:

重新打包安裝後,SonarQube 就能正確識別並分類這些問題。
開始之前,請確認 macOS 服務器已裝好最新版的 Xcode、OCLint、Jenkins 與 sonnar-runner,相關 Jenkins 插件齊備,自定義 Rule 也已就位。
檢查並生成報告:在 Jenkins 新建工程,配置好 Git 與構建觸發器,並在構建步驟加入一步 Execute Shell:
cd YourProjectDir xcodebuild clean xcodebuild -workspace MyProject.xcworkspace -scheme HTMarket -sdk iphonesimulator | tee xcodebuild.log | xcpretty oclint-xcodebuild oclint-json-compilation-database -e Pods \ -v \ -- \ -max-priority-1 100000 \ -max-priority-2 100000 \ -max-priority-3 100000 \ -report-type pmd \ -R /path/to/diy-rules \ -o /path/to/report.xml
三處需特別注意:一是加上 -sdk iphonesimulator 以避開需要 Code Sign 的問題;二是 -report-type 必須為 pmd;三是留意 -o 的輸出路徑,下一步會用到。
讀取到 SonarQube:在下方再加一步 Invoke Standalone SonarQube Analysis,選擇你的 sonnar-runner,並在 Analysis Properties 中填入:
sonar.projectKey=YOUR_PROJECT_NAME sonar.projectName=YOUR_PROJECT_NAME sonar.projectVersion=1.0 sonar.language=objc sonar.projectDescription=YOUR_PROJECT_DESCRIPTION sonar.sources=/path/to/source/directories sonar.objectivec.project=YOUR_PROJECT_NAME.xcodeproj sonar.objectivec.workspace= YOUR_PROJECT_NAME.xcworkspace sonar.objectivec.appScheme=YOUR_PROJECT_NAME sonar.sourceEncoding=UTF-8 sonar.objectivec.oclint.report=YOUR_REPORT_FILE_PATH
把 YOUR_PROJECT_NAME、YOUR_PROJECT_DESCRIPTION 與 YOUR_REPORT_FILE_PATH 換成實際值。順利的話,在 Jenkins 上立即構建,Sonar 平台就會出現質量報告。再搭配構建觸發器與 Git 平台的 WebHook,即可在提交代碼或合併分支時自動觸發。
compile_commands.json 為什麼是空的?
檢查 log 是否為空。log 為空代表 build 失敗,排除失敗原因後即可正常生成。
Jenkins 構建報 Code signing is required for product type 'Application' in SDK 'iOS 10.0'
這是因為構建了 Release 版本,且專案在 Xcode 8+ 開啟了 Automatic Code Sign。解法有兩種:若只需檢查代碼規範,在 xcodebuild 後加 -sdk iphonesimulator,以 Debug 方式構建;若確實要構建 Release,則關閉自動簽名,在 CI 上手動配置證書與 Provisioning Profile,或用 sed 在構建前修改相關配置。
OCLint
Jenkins
SonarQube
Edsger W. Dijkstra
AST (Abstract Syntax Tree)
json compilation database format specification
xcpretty
PMD
xcode8 與 ios10 升級後的問題集中討論帖 — TesterHome