如何为 IBAnalyzer 新增一个 Analyzer:协议驱动扩展机制实战教程

原创2026-10-23 16:26:292,344 阅读

如何为 IBAnalyzer 新增一个 Analyzer:协议驱动扩展机制实战教程

IBAnalyzer 是一款无需运行 App、无需编写单元测试就能发现 xib / storyboard 常见问题的命令行检查工具。本文带你理解它的协议驱动扩展机制,并用 4 步实战流程为 IBAnalyzer 新增一个 Analyzer(分析器),让工具具备完全属于你的检查能力。

一、先搞懂:IBAnalyzer 是如何运转的

在动手之前,花 1 分钟看清整体链路,扩展起来会事半功倍:

  1. 扫描文件:Runner 接收一个项目路径,递归找出所有 .xib、.storyboard 和 .swift 文件;
  2. 解析数据:NibParser 从接口文件中提取 outlet / action 连接,SwiftParser 从 Swift 源码中提取类里的 @IBOutlet 和 @IBAction;
  3. 组装配置:两份解析结果被打包进 AnalyzerConfiguration 结构体,作为所有分析器的统一数据源;
  4. 逐个执行分析器:Runner 遍历传入的 [Analyzer] 数组,调用每个分析器的 issues(for:) 方法并合并结果;
  5. 输出与退出码: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 补单元测试

本项目测试风格非常轻量,值得直接照抄:

一个最小测试骨架:

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 工具中的经典应用。

登录后查看全文
IBAnalyzer