简介

SwiftLint 是 realm 公司开发的一个插件，用于强制检查 Swift 代码风格和规则的一个工具。
SwiftLint 的工作原理是检查 Swift 代码编译过程中的 AST 和 SourceKit 环节，从而可以摆脱不同版本 Swift 语法变化的影响。AST 是编译前端形成的抽象语法树（Abstract Symbolic Tree）， SourceKit 过程用来对 AST 进行代码优化，减少内存开销，提高执行效率。

安装

1. 使用 Homebrew:
brew install swiftlint

2. 使用 CocoaPods:
将如下代码添加到你的 Podfile 即可：
pod 'SwiftLint'

3. 使用安装包:
通过从 最新的 GitHub 发布地址 下载 SwiftLint.pkg 然后执行的方式安装 SwiftLint。

用法

1. Xcode:
在 Xcode-Project-Build Phases-+(New Run Script Phase) 中添加一个新的 Script Phase 并且包含如下代码即可：

if which swiftlint >/dev/null; then
  swiftlint
else
  echo "warning: SwiftLint not installed, download from https://github.com/realm/SwiftLint"
fi

swiftlintScript.png

2. 命令行:
在有需要执行代码分析的 Swift 源码文件的目录下执行 swiftlint 命令，会对目录递归查找。

$ swiftlint help
   autocorrect  Automatically correct warnings and errors
   help         Display general or command-specific help
   lint         Print lint warnings and errors for the Swift files in the current directory (default command)
   rules        Display the list of rules and their identifiers
   version      Display the current version of SwiftLint

规则

1. 终端执行命令: swiftlint rules 或者 官方文档: rule-directory

opt-in:  为 yes 时，规则默认不生效，需要添加进配置的 opt_in_rules 时生效
correctable: 为 yes 时，执行 swiftlint autocorrect 命令，会自动修改代码格式为正确的格式
enabled in your config: 为 yes 时，规则默认生效，不需要额外配置
kind: 规则类型，仅用于规则的分类 
analyzer: 为 yes 时，可在 Xcode 的 Analyze 生效
configuration: 支持配置的属性默认值。例： warning 代表不符合代码规则时，编译器会警告。可在配置文件中改成 error，编译器会报错

rules 列表详见文章底部 附录 1. swiftlint rules

2. 规则开启与关闭
可以通过在一个源文件中定义一个如下格式的注释来关闭某个规则：
// swiftlint:disable <rule>
在该文件结束之前或者在定义如下格式的匹配注释之前，这条规则都会被禁用：
// swiftlint:enable <rule>
也可以通过添加 :previous, :this 或者 :next 来使关闭或者打开某条规则的命令分别应用于前一行，当前或者后一行代码。

// swiftlint:disable:next force_cast
let noWarning = NSNumber() as! Int
let hasWarning = NSNumber() as! Int
let noWarning2 = NSNumber() as! Int // swiftlint:disable:this force_cast
let noWarning3 = NSNumber() as! Int
// swiftlint:disable:previous force_cast

配置

在需要执行 SwiftLint 的目录下添加一个 .swiftlint.yml 文件的方式来配置 SwiftLint。可以被配置的参数有：

• disabled_rules: 关闭某些默认开启的规则。
• opt_in_rules: 一些规则是可选的，添加到这里才会生效。
• only_rules: 不可以和 disabled_rules 或者 opt_in_rules 并列。类似一个白名单，只有在这个列表中的规则才是开启的。

disabled_rules: # 执行时排除掉的规则
  - colon
opt_in_rules: # 一些规则仅仅是可选的
  - empty_count
included: # 执行 linting 时包含的路径。
  - Source
excluded: # 执行 linting 时忽略的路径。 优先级比 `included` 更高。
  - Carthage
force_cast: warning # 隐式
force_try:
  severity: warning # 显式
type_body_length: # 可以通过一个数组同时进行隐式设置
  - 300 # warning
  - 400 # error
file_length: # 或者也可以同时进行显式设置
  warning: 500
  error: 1200

reporter: "xcode" # 报告类型 (xcode, json, csv, checkstyle, codeclimate, junit, html, emoji, sonarqube, markdown, github-actions-logging)

自定义规则

在配置文件 .swiftlint.yml 里定义基于正则表达式的自定义规则：

custom_rules:
  pirates_beat_ninjas: # 规则标识符
    name: "Pirates Beat Ninjas" # 规则名称，可选
    regex: "([nN]inja)" # 匹配的模式
    match_kinds: # 需要匹配的语法类型，可选
      - comment
      - identifier
    message: "Pirates are better than ninjas." # 提示信息，可选
    severity: error # 提示的级别，可选
  no_hiding_in_strings:
    regex: "([nN]inja)"
    match_kinds: string

输出大概可能是这个样子的：

custom_rules

嵌套配置

SwiftLint 支持通过嵌套配置文件的方式来对代码分析过程进行更加细致的控制。

1. 在你需要的目录引入 .swiftlint.yml。
2. 在目录结构必要的地方引入额外的 .swiftlint.yml 文件。
3. 每个文件被检查时会使用在文件所在目录下的或者父目录的更深层目录下的配置文件。否则根配置文件将会生效。
4. excluded 和 included 在嵌套结构中会被忽略。

自动更正

SwiftLint 可以自动修正某些错误，磁盘上的文件会被一个修正后的版本覆盖。
请确保在对文件执行 swiftlint autocorrect 之前有对它们做过备份，否则的话有可能导致重要数据的丢失。
因为在执行自动更正修改某个文件后很有可能导致之前生成的代码检查信息无效或者不正确，所以当在执行代码更正时标准的检查是无法使用的。

SwiftLint rules 原理

SwiftLint rules 的源码在 Source/SwiftLintFramework/Rules 目录下，以 OverriddenSuperCallRule(方法需要调用 super method) 为例解读源码，路径为：/Source/SwiftLintFramework/Rules/Lint/OverriddenSuperCallRule.swift。
| overridden_super_call | yes | no | no | lint | no | warning, excluded: [], included: [“*"] |
主要看 validate(file:kind:dictionary:) 方法，在方法中使用了 configuration、SourceKittenDictionary。
configuration: OverriddenSuperCallConfiguration

public struct OverriddenSuperCallConfiguration: RuleConfiguration, Equatable {
    private let defaultIncluded = [
        "addChildViewController(_:)",
        "didReceiveMemoryWarning()",
        "removeFromParentViewController()",
        "viewDidAppear(_:)",
        "viewDidDisappear(_:)",
        "viewDidLoad()",
        "viewWillAppear(_:)",
        "viewWillDisappear(_:)",
        ...
    ]
    var severityConfiguration = SeverityConfiguration(.warning)
    var excluded: [String] = []
    var included: [String] = ["*"]
    public private(set) var resolvedMethodNames: [String]
    init() {
        resolvedMethodNames = defaultIncluded
    }
    public var consoleDescription: String {
        return severityConfiguration.consoleDescription +
            ", excluded: \(excluded)" +
            ", included: \(included)"
    }
    public mutating func apply(configuration: Any) throws {
        guard let configuration = configuration as? [String: Any] else {
            throw ConfigurationError.unknownConfiguration
        }
        if let severityString = configuration["severity"] as? String {
            try severityConfiguration.apply(configuration: severityString)
        }
        if let excluded = [String].array(of: configuration["excluded"]) {
            self.excluded = excluded
        }
        if let included = [String].array(of: configuration["included"]) {
            self.included = included
        }
        resolvedMethodNames = calculateResolvedMethodNames()
    }
    public var severity: ViolationSeverity {
        return severityConfiguration.severity
    }
    private func calculateResolvedMethodNames() -> [String] {
        var names: [String] = []
        if included.contains("*") && !excluded.contains("*") {
            names += defaultIncluded
        }
        names += included.filter({ $0 != "*" })
        names = names.filter { !excluded.contains($0) }
        return names
    }
}

• defaultIncluded: 默认的配置，里面有一些方法名。
• severityConfiguration: 规则冲突提示级别
• excluded: 需要排除的方法
• included：需要包含的方法
• func apply(configuration: Any): 应用自定义的配置
• calculateResolvedMethodNames(): 综合配置

SourceKittenDictionary 使用 [String: SourceKitRepresentable] 初始化。
[String: SourceKitRepresentable] 是 sourcekitten structure --file SourcekittenDemoViewController.swift 命令生成的 json 对象。详看: sourcekitten_structure.json
SourceKittenDictionary

public struct SourceKittenDictionary {
   init(_ value: [String: SourceKitRepresentable]) {…}
…

以 SourcekittenDemoViewController.swift 为例：

class SourcekittenDemoViewController: UIViewController {
    private var testVar: String?
    override func viewDidLoad() {
        super.viewDidLoad()
        self.view.backgroundColor = UIColor.lightGray
        testVar = "i am testVar"
    }
}

sourcekitten_structure.json

{
  "key.diagnostic_stage" : "source.diagnostic.stage.swift.parse",
  "key.length" : 414,
  "key.offset" : 0,
  "key.substructure" : [
    {
      "key.accessibility" : "source.lang.swift.accessibility.internal",
      "key.bodylength" : 189,
      "key.bodyoffset" : 223,
      "key.elements" : [
        {
          "key.kind" : "source.lang.swift.structure.elem.typeref",
          "key.length" : 16,
          "key.offset" : 205
        }
      ],
      "key.inheritedtypes" : [
        {
          "key.name" : "UIViewController"
        }
      ],
      "key.kind" : "source.lang.swift.decl.class",
      "key.length" : 246,
      "key.name" : "SourcekittenDemoViewController",
      "key.namelength" : 30,
      "key.nameoffset" : 173,
      "key.offset" : 167,
      "key.substructure" : [
        {
          "key.accessibility" : "source.lang.swift.accessibility.private",
          "key.attributes" : [
            {
              "key.attribute" : "source.decl.attribute.private",
              "key.length" : 7,
              "key.offset" : 228
            }
          ],
          "key.kind" : "source.lang.swift.decl.var.instance",
          "key.length" : 20,
          "key.name" : "testVar",
          "key.namelength" : 7,
          "key.nameoffset" : 240,
          "key.offset" : 236,
          "key.setter_accessibility" : "source.lang.swift.accessibility.private",
          "key.typename" : "String?"
        },
        {
          "key.accessibility" : "source.lang.swift.accessibility.internal",
          "key.attributes" : [
            {
              "key.attribute" : "source.decl.attribute.override",
              "key.length" : 8,
              "key.offset" : 261
            }
          ],
          "key.bodylength" : 120,
          "key.bodyoffset" : 290,
          "key.kind" : "source.lang.swift.decl.function.method.instance",
          "key.length" : 141,
          "key.name" : "viewDidLoad()",
          "key.namelength" : 13,
          "key.nameoffset" : 275,
          "key.offset" : 270,
          "key.substructure" : [
            {
              "key.bodylength" : 0,
              "key.bodyoffset" : 317,
              "key.kind" : "source.lang.swift.expr.call",
              "key.length" : 19,
              "key.name" : "super.viewDidLoad",
              "key.namelength" : 17,
              "key.nameoffset" : 299,
              "key.offset" : 299
            }
          ]
        }
      ]
    }
  ]
}

validate(file:kind:dictionary:)

func validate(file: SwiftLintFile, kind: SwiftDeclarationKind,
          dictionary: SourceKittenDictionary) -> [StyleViolation] {
             guard let offset = dictionary.bodyOffset,
                       let name = dictionary.name,
                   kind == .functionMethodInstance,
                       configuration.resolvedMethodNames.contains(name),
                   dictionary.enclosedSwiftAttributes.contains(.override)
       else { return [] }
              let callsToSuper = dictionary.extractCallsToSuper(methodName: name)
              if callsToSuper.isEmpty {
                 …
                 "Method '\(name)' should call to super function"
              } else if callsToSuper.count > 1 {
                 ...
                 "Method '\(name)' should call to super only once"
              }
              return []
}

public struct SourceKittenDictionary {
…
internal func extractCallsToSuper(methodName: String) -> [String] {
    guard let methodNameWithoutArguments = methodName.split(
separator: "(").first else { return [] }
    let superCall = “super.\(methodNameWithoutArguments)"
    return substructure.flatMap { elems -> [String] in
        guard let type = elems.expressionKind,
        let name = elems.name,
        type == .call && superCall == name else {
            return elems.extractCallsToSuper(
methodName: methodName)}
        return [name]}}
}

validate(file:kind:dictionary:) 通过判断：

方法 == 含有 .override 属性的实例方法 && 
methodName 在配置列表中 &&
Substructure 中表达式类型是 .call && 
Substructure 中方法调用名称 == super.{methodName}

满足上述条件的方法内若没有调用对应的 super 方法，或者
调用了多次对应的 super 方法，就会提示规则冲突。

问：sourcekitten 是什么？
答：SourceKitten 是基于 Apple 的 SourceKit 封装的命令行工具，SourceKitten 链接并与 sourcekitd.framework 通信以解析 Swift AST，最终提取 Swift 或 ObjC 文件的类结构和方法等。
sourcekitten 支持的命令如下：

SUBCOMMANDS:
  complete                Generate code completion options
  doc                     Print Swift or Objective-C docs as JSON
  format                  Format Swift file
  index                   Index Swift file and print as JSON
  module-info          Obtain Swift module information and print as json
  request                 Run a raw SourceKit request
  structure               Print Swift structure information as JSON
  syntax                  Print Swift syntax information as JSON
  version                 Display the current version of SourceKitten

问：SourceKit 是什么？
答：SourceKit 是一套工具集，使得大多数 Swift 源代码层面的操作特性得以支持，例如源代码解析、语法高亮、排版（typesetting）、自动补全、跨语言头文件生成，等等

问：Swift AST 是什么？
答：AST(Abstract Syntax Tree 抽象语法树) 是源代码的抽象语法结构的树状表示，树上的每个节点都表示源代码中的一种结构，是 Swift 文件编译过程中的产物。

Swift 文件编译过程:

Swift 文件编译过程

image.png

Swiftc 生成 AST：
Swiftc 是 swift 语言的编译工具，它可以直接把 .swift 文件编译生成可执行文件，也可以产生编译过程中某个中间文件。Swiftc 支持命令如下：

MODES:
  -dump-ast              Parse and type-check input file(s) and dump AST(s)
  -dump-parse            Parse input file(s) and dump AST(s)
  -emit-assembly         Emit assembly file(s) (-S)
  -emit-executable       Emit a linked executable
  -emit-ir               Emit LLVM IR file(s)
  -emit-sibgen           Emit serialized AST + raw SIL file(s)
  -emit-sib              Emit serialized AST + canonical SIL file(s)
  -emit-silgen           Emit raw SIL file(s)
  -emit-sil              Emit canonical SIL file(s)
  -parse                 Parse input file(s)
  -print-ast             Parse and type-check input file(s) and pretty print AST(s)
  -typecheck             Parse and type-check input file(s)
...

swiftc -dump-parse SourcekittenDemoViewController.swift

(source_file "SourcekittenDemoViewController.swift"
  (import_decl range=[SourcekittenDemoViewController.swift:9:1 - line:9:8] 'UIKit')
  (class_decl range=[SourcekittenDemoViewController.swift:11:1 - line:18:1] "SourcekittenDemoViewController" inherits: <null>
    (pattern_binding_decl range=[SourcekittenDemoViewController.swift:12:13 - line:12:32]
      (pattern_typed
        (pattern_named 'testVar')
        (type_optional
          (type_ident
            (component id='String' bind=none)))))
    (var_decl range=[SourcekittenDemoViewController.swift:12:17 - line:12:17] "testVar" type='<null type>' readImpl=stored writeImpl=stored readWriteImpl=stored)
    (func_decl range=[SourcekittenDemoViewController.swift:13:14 - line:17:5] "viewDidLoad()"
      (parameter "self")
      (parameter_list range=[SourcekittenDemoViewController.swift:13:30 - line:13:31])
      (brace_stmt range=[SourcekittenDemoViewController.swift:13:33 - line:17:5]
        (call_expr type='<null>' arg_labels=
          (unresolved_dot_expr type='<null>' field 'viewDidLoad' function_ref=unapplied
            (super_ref_expr type='<null>'))
          (tuple_expr type='()' location=SourcekittenDemoViewController.swift:14:26 range=[SourcekittenDemoViewController.swift:14:26 - line:14:27]))
        (sequence_expr type='<null>'
          (unresolved_dot_expr type='<null>' field 'backgroundColor' function_ref=unapplied
            (unresolved_dot_expr type='<null>' field 'view' function_ref=unapplied
              (declref_expr type='<null>' decl=SourcekittenDemoViewController.(file).SourcekittenDemoViewController.viewDidLoad().self@SourcekittenDemoViewController.swift:13:19 function_ref=unapplied)))
          (assign_expr type='<null>'
            (**NULL EXPRESSION**)
            (**NULL EXPRESSION**))
          (unresolved_dot_expr type='<null>' field 'lightGray' function_ref=unapplied
            (unresolved_decl_ref_expr type='<null>' name=UIColor function_ref=unapplied)))
        (sequence_expr type='<null>'
          (unresolved_decl_ref_expr type='<null>' name=testVar function_ref=unapplied)
          (assign_expr type='<null>'
            (**NULL EXPRESSION**)
            (**NULL EXPRESSION**))
          (string_literal_expr type='<null>' encoding=utf8 value="i am testVar" builtin_initializer=**NULL** initializer=**NULL**))))))

通过生成的 AST 信息可以看到 import_decl、class_decl、var_decl、func_decl、brace_stmt、call_expr 等及所在的行列数。sourcekit 可以通过这些信息实现语法高亮、排版、自动补全、跨语言头文件生成，等等

提醒 执行 swiftc -print-ast SourcekittenDemoViewController.swift 命令时，终端会报错 SourcekittenDemoViewController.swift:9:8: error: no such module 'UIKit' .
为解决此报错，需要指定 -sdk 和 -target 参数，如下：
swiftc -print-ast SourcekittenDemoViewController.swift -sdk /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS15.5.sdk -target arm64-apple-ios15.5
"15.5" 需要根据本地支持的版本做修改。

SwiftLint 规则建议

Swiftlint 规则没有完全符合每个工程期望的统一规则。基于项目应用上面，我得出一些经验教训，在此给出一点建议：

1. 成熟的项目规则宜松不宜紧。规则过多或过严会直接导致产生较多警告，改动太耗时间，产生大量提交。万一修改出了错误，查起来也会非常麻烦。
2. 可纠正代码 bug 的规则，建议提示级别为 error，而非 warning。如此可及时提醒修正错误。
   例如： OverriddenSuperCallRule 规则可用于避免遗漏调用 super 方法，从而避免工程中对此方法的 hook 不生效。
   例如: DiscardedNotificationCenterObserverRule 规则可用于避免因为未持有 observer，不能释放内存，从而导致内存泄露的 bug。
3. 推荐 swift 写法的规则建议使用。
   例如：使用 CGPoint(x:y:) 代替 CGPointMake(,)

基于上面三条建议，制定的规则示例如下：

only_rules:
  - block_based_kvo # Swift 3.2 之后使用新的 KVO API
  - compiler_protocol_init # 不应该直接调用字面量转换的初始化方法
  - control_statement # if while 等判断条件不要用括号括起来
  - custom_rules # 一些自定义规则
  - discarded_notification_center_observer # 当使用 block 注册通知中心 observer 的时候，应该存储函数返回的 observer, 以便之后的删除
  - discouraged_optional_boolean # 不建议使用可选布尔值
  - duplicate_imports # 重复导入
  - duplicate_enum_cases # 枚举不能设置两个或者以上相同的名字
  - empty_count
  - empty_string # 优先使用 isEmpty 判断，而不是将字符串与空字符串文字进行比较
  - empty_parameters # 闭包参数为空时,建议使用 `() -> ` 代替 `Void ->
  - explicit_init # 避免直接调用 init 方法
  - fallthrough # switch 语句中不建议使用 fallthrough
  - fatal_error_message # fatalError 必须拥有一个 message
  - file_name_no_space # 文件名不应包含任何空格
  - force_cast # 不建议直接强解类型
  - force_try # 避免 `try!`
  - force_unwrapping # 避免强制解包
  - identical_operands # 比较两个相同的操作数可能是一个错误
  - legacy_cggeometry_functions # 避免使用 C 风格的 CG 遗留函数，使用 struct extension
  - legacy_constructor # 使用 swift 提供的 struct 构造函数， 避免使用遗留的构造函数比如 CGPointMake(10, 10)
  - legacy_nsgeometry_functions # 避免使用 C 风格的 NS 遗留函数，使用 struct extension
  - literal_expression_end_indentation # 数组和字典文字的结尾应与开始它的行具有相同的缩进
  - lower_acl_than_parent # 确保定义的访问控制级别低于其父级
  - mark # 正确使用 mark 的格式 `// MARK: - message`
  - multiline_parameters # 函数和方法参数应该在同一行上，或者每行一个
  - no_extension_access_modifier # 在 extension 扩展前面,不建议使用 (fileprivate,public) 等修饰符
  - redundant_objc_attribute # Objective-C 属性（@objc）在声明中是多余的
  - redundant_optional_initialization # 不需要写默认值为 nil
  - redundant_string_enum_value # 字符串类型枚举，会有默认 string 值，与名字相同，不要再次设置
  - redundant_void_return # 在不必要的时候， 不需要写 ->() and -> Void
  - return_arrow_whitespace # 函数定义返回的 ->  前后有空格， 不换行
  - switch_case_alignment # Case 语句应与其封闭的 switch 语句垂直对齐，如果没有其他配置，则缩进
  - trailing_semicolon # 行末尾不加分号
  - type_name # 类型名字限制规则（类型名称应仅包含字母数字字符，以大写字符开头，长度在 3 到 40 个字符之间）
  - unneeded_break_in_switch # 在 switch-case 语句中, 有方法调用或操作时,避免使用 break 语句
  - unowned_variable_capture # 最好将引用捕获为弱引用以避免潜在的崩溃
  - void_return # 使用 `-> Void` 代替 `-> ()
  - weak_delegate # delegate 应该被设置为 weak

excluded: # paths to ignore during linting. Takes precedence over `included`.
  - Tests
  - Example
  - Resources

force_cast:
  severity: warning
  
force_try:
  severity: warning

no_extension_access_modifier:
  severity: warning
  
empty_count:
  severity: warning

type_name:
  min_length: 1
  max_length: 60

overridden_super_call:
  severity: error

prohibited_super_call:
  severity: error
  
discarded_notification_center_observer:
  severity: error

weak_delegate:
  severity: error

unowned_variable_capture:
  severity: error

reporter: "xcode" # reporter type (xcode, json, csv, checkstyle, junit, html, emoji, sonarqube, markdown)

custom_rules:
  ab_test_recovery:
    name: "AB Test Recovery"
    regex: '^ *//+[ \S]* ABTestHelper\.+'
    match_kinds:
      - comment
      - doccomment
    message: "AB Test Recovery. 调试期间注释掉的 ab test,上线前记得恢复"
    severity: warning
  url_Check:
    name: "URL Check"
    regex: '(https?|ftp|file)://[-A-Za-z0-9+&@#/%?=~_|!:,.;]+[-A-Za-z0-9+&@#/%=~_|]+[()（）]'
    match_kinds: string
    message: "URL 中发现有 '(' 或 ')' 或 '（' 或 '）' ，请注意确认正确性"
    severity: warning

附录

1. swiftlint rules

参考文献

1. SwiftLint
2. SwiftLint 的理解和使用
3. rule-directory
4. AST
5. LLVM优点
6. How a Swift file is compiled
7. SwiftSyntax详解
8. 使用“swiftc”命令编译swift文件时如何导入像“UIKit”这样的模块？