如何为 IBAnalyzer 新增一个 Analyzer:协议驱动扩展机制实战教程
如何为 IBAnalyzer 新增一个 Analyzer:协议驱动扩展机制实战教程
IBAnalyzer 是一款无需运行 App、无需编写单元测试就能发现 xib / storyboard 常见问题的命令行检查工具。本文带你理解它的协议驱动扩展机制,并用 4 步实战流程为 IBAnalyzer 新增一个 Analyzer(分析器),让工具具备完全属于你的检查能力。
一、先搞懂:IBAnalyzer 是如何运转的
在动手之前,花 1 分钟看清整体链路,扩展起来会事半功倍:
- 扫描文件:Runner 接收一个项目路径,递归找出所有
.xib、.storyboard和.swift文件; - 解析数据:NibParser 从接口文件中提取 outlet / action 连接,SwiftParser 从 Swift 源码中提取类里的
@IBOutlet和@IBAction; - 组装配置:两份解析结果被打包进
AnalyzerConfiguration结构体,作为所有分析器的统一数据源; - 逐个执行分析器:Runner 遍历传入的
[Analyzer]数组,调用每个分析器的issues(for:)方法并合并结果; - 输出与退出码:main.swift 逐行打印问题,若存在"严重违规"(
isSeriousViolation == true),程序以退出码2结束,方便接入 CI 构建流程。
💡 关键点:解析逻辑与分析逻辑完全解耦。你新增 Analyzer 时不需要碰任何解析器,只需消费现成的
AnalyzerConfiguration。
二、扩展前的两个核心概念
2.1 Analyzer 协议:分析器的"标准插座"
整个扩展机制建立在两个轻量协议上,定义见 Analyzer.swift:
protocol Issue: CustomStringConvertible {
var isSeriousViolation: Bool { get }
}
protocol Analyzer {
func issues(for configuration: AnalyzerConfiguration) -> [Issue]
}
Issue:一条检查发现。description决定打印出的文案,isSeriousViolation决定它是否触发非零退出码(阻断构建);Analyzer:只需实现一个方法——接收配置,返回问题列表。就这么简单。
2.2 AnalyzerConfiguration:你唯一的"数据窗口"
结构体定义在 Analyzer.swift,包含三张映射表:
| 字段 | 类型 | 含义 |
|---|---|---|
classNameToNibMap |
<a href="https://link.gitcode.com/i/5ccbb988de48ee1e54cb0c1b211856fe" target="_blank">String: Nib] |
类名 → 接口文件中声明的 outlets / actions,模型见 [Nib.swift |
classNameToClassMap |
<a href="https://link.gitcode.com/i/a4b12f36adf23e387f177ccd7cff5527" target="_blank">String: Class] |
类名 → Swift 代码中的 outlets / actions / 继承链,模型见 [Class.swift |
uiKitClassNameToClassMap |
<a href="https://link.gitcode.com/i/75b016f617fe39dbca48526ecd485d1f" target="_blank">String: Class] |
UIKit 内置类的隐式 outlet(如 UITableView 的 dataSource),数据来自 [UIKitOutlets.swift |
写新分析器前,先想清楚:我的规则需要哪张表? 多数场景只需要前两张。
三、实战 4 步:新增一个 Analyzer
以下以新增「检测 outlet 命名不符合小驼峰规范」的分析器为例(实际项目中你完全可以换成任何规则)。
第 1 步:准备环境
克隆仓库并打开工作区:
git clone https://gitcode.com/gh_mirrors/ib/IBAnalyzer
open IBAnalyzer.xcworkspace
第 2 步:定义你的 Issue
参照现成写法——ConnectionIssue 用枚举 + 计算属性组织文案与严重级别。为新规则新建一个枚举即可:
enum NamingIssue: Issue {
case badOutletName(className: String, outlet: Declaration)
var description: String {
switch self {
case let .badOutletName(className, outlet):
return "\(outlet.description): warning: outlet '\(outlet.name)' in \(className) is not camelCase"
}
}
var isSeriousViolation: Bool { false } // 命名问题一般不阻断构建
}
📌 提示:Declaration 类型在 ConnectionAnalyzer.swift 中定义,自带 name、line、column,description 会输出 文件路径:行:列,直接用于定位问题。
第 3 步:实现 Analyzer 协议
在 IBAnalyzer/Analyzers/ 下新建文件,实现结构体:
struct NamingAnalyzer: Analyzer {
func issues(for configuration: AnalyzerConfiguration) -> [Issue] {
var result: [NamingIssue] = []
for (className, klass) in configuration.classNameToClassMap {
for outlet in klass.outlets where !outlet.name.isCamelCase() {
result.append(.badOutletName(className: className, outlet: outlet))
}
}
return result
}
}
核心逻辑就是遍历 AnalyzerConfiguration 中的映射表——和 ConnectionAnalyzer.issues(for:) 的思路完全一致。
第 4 步:在 main.swift 中注册
分析器不会自动生效,需要在 main.swift 的数组里追加一行:
let issues = try runner.issues(using: [ConnectionAnalyzer(), NamingAnalyzer()])
至此,运行 ibanalyzer ~/YourProject/ 时新规则就会随内置规则一起执行。
四、别忘了:为新 Analyzer 补单元测试
本项目测试风格非常轻量,值得直接照抄:
- 参考 ConnectionAnalyzerTests.swift:手动构造
Nib、Class与AnalyzerConfiguration,断言issues(for:)的返回值,无需真实文件; - 参考 RunnerTests.swift 中的
MockAnalyzer:验证 Runner 确实把正确的配置传给了分析器; - 样例接口文件可参考 Example.storyboard。
一个最小测试骨架:
func testFlagsNonCamelOutlet() {
let outlet = Declaration(name: "MyLabel", line: 1, column: 0)
let configuration = AnalyzerConfiguration(
classNameToNibMap: [:],
classNameToClassMap: ["A": Class(outlets: [outlet], actions: [], inherited: [])])
XCTAssertEqual(NamingAnalyzer().issues(for: configuration),
[NamingIssue.badOutletName(className: "A", outlet: outlet)])
}
五、进阶技巧与常见坑
- 想让违规阻断构建? 把
isSeriousViolation设为true,main.swift 会以退出码2退出,天然适配 CocoaPods 的 Run Script 构建阶段; - 想加命令行开关? 参照 Rule 枚举与 Configuration 单例,新增枚举 case 后,运行
ibanalyzer path --yourRule即可开启,分析器内用Configuration.shared.isEnabled(.yourRule)判断; - 继承链判断别漏:判断"是否缺少实现"时要考虑父类和 UIKit 类的继承匹配,可复用 classOrInheritedTypeOf 的遍历模式;
- 保持无状态:
ConnectionAnalyzer、NamingAnalyzer都是无状态结构体,Runner 可安全地多次调用,这也是本项目的默认风格。
六、总结清单 ✅
| 步骤 | 产物 | 关键文件 |
|---|---|---|
| 1 | 理解数据流 | Runner.swift |
| 2 | 实现 Issue 枚举 |
Analyzer.swift |
| 3 | 实现 Analyzer 协议 |
Analyzer.swift |
| 4 | 注册到 issues(using:) |
main.swift |
| 5 | 补单元测试 | ConnectionAnalyzerTests.swift |
可以看到,IBAnalyzer 的扩展机制把"数据获取"与"规则判断"彻底分离:协议只留了一个方法,配置对象封装了全部数据。新增一条检查规则,本质上就是"写一个纯函数"——这正是协议驱动设计在 CLI 工具中的经典应用。