SwiftLint

SwiftLint 是一个用于强制执行 Swift 代码风格和约定的工具，基于已归档的 GitHub Swift 风格指南。SwiftLint 强制执行 Swift 社区普遍接受的风格规则。这些规则在流行的风格指南中有详细描述，如 Kodeco 的 Swift 风格指南。

SwiftLint 利用 Clang 和 SourceKit 来使用源文件的 AST 表示，以获得更准确的结果。

本项目遵循贡献者契约行为准则。参与即表示你同意遵守此准则。请将不可接受的行为报告给 info@realm.io。

切换语言：中文 한국어

视频介绍

为了对 SwiftLint 有一个高层次的了解，我们建议你观看 JP Simard 于 2017 年 1 月 9 日录制的这个演示（提供文字记录）：

安装

Swift 包管理器

SwiftLint 可以作为命令插件或构建工具插件使用。

在你的 Package.swift 文件中添加

.package(url: "https://github.com/SimplyDanny/SwiftLintPlugins", from: "<版本>")

以自动使用最新版本的 SwiftLint，或将依赖固定到特定版本：

.package(url: "https://github.com/SimplyDanny/SwiftLintPlugins", exact: "<版本>")

其中，将 <版本> 替换为所需的最低版本或确切版本。

[!注意] 直接从 SwiftLint 仓库使用插件有几个缺点。为了避免这些问题并减少开销，强烈建议从专门的 SwiftLintPlugins 仓库使用插件，尽管 SwiftLint 仓库中的插件也完全可用。如果更喜欢使用 SwiftLint 的插件，只需在上面的包声明中使用 URL https://github.com/realm/SwiftLint。

然而，SwiftLintPlugins 极大地简化了插件的采用。它列出了一些使 SwiftLint 自身提供的插件变得非常麻烦的原因。由于插件代码和发布版本保持同步，两者在功能上没有区别，但使用专门的插件仓库可以节省大量时间和麻烦。

本文档假设你使用的是 SwiftLintPlugins。

Xcode 包依赖

使用以下链接将 SwiftLint 作为包依赖添加到 Xcode 项目中：

https://github.com/SimplyDanny/SwiftLintPlugins

Homebrew

brew install swiftlint

CocoaPods

在你的 Podfile 中添加以下内容：

pod 'SwiftLint'

这将在下次执行 pod install 时下载 SwiftLint 二进制文件和依赖项到 Pods/ 目录，并允许你通过 ${PODS_ROOT}/SwiftLint/swiftlint 在脚本构建阶段调用它。

通过 CocoaPods 安装还可以将 SwiftLint 固定到特定版本，而不是简单地使用最新版本（这是 Homebrew 的情况）。

请注意，这将把 SwiftLint 二进制文件、其依赖项的二进制文件和 Swift 二进制库分发添加到 Pods/ 目录中，因此不建议将此目录提交到 Git 等 SCM 中。

Mint

mint install realm/SwiftLint

Bazel

在你的 MODULE.bazel 中添加以下内容：

bazel_dep(name = "swiftlint", version = "0.52.4", repo_name = "SwiftLint")

或者在你的 WORKSPACE 中添加以下内容：

<details> <summary>WORKSPACE</summary>

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "build_bazel_rules_apple",
    sha256 = "390841dd5f8a85fc25776684f4793d56e21b098dfd7243cd145b9831e6ef8be6",
    url = "https://github.com/bazelbuild/rules_apple/releases/download/2.4.1/rules_apple.2.4.1.tar.gz",
)

load(
    "@build_bazel_rules_apple//apple:repositories.bzl",
    "apple_rules_dependencies",
)

apple_rules_dependencies()

load(
    "@build_bazel_rules_swift//swift:repositories.bzl",
    "swift_rules_dependencies",
)

swift_rules_dependencies()

load(
    "@build_bazel_rules_swift//swift:extras.bzl",
    "swift_rules_extra_dependencies",
)

swift_rules_extra_dependencies()

http_archive(
    name = "SwiftLint",
    sha256 = "c6ea58b9c72082cdc1ada4a2d48273ecc355896ed72204cedcc586b6ccb8aca6",
    url = "https://github.com/realm/SwiftLint/releases/download/0.52.4/bazel.tar.gz",
)

load("@SwiftLint//bazel:repos.bzl", "swiftlint_repos")

swiftlint_repos()

load("@SwiftLint//bazel:deps.bzl", "swiftlint_deps")

swiftlint_deps()

</details>

然后你可以使用以下命令在当前目录中运行 SwiftLint：

bazel run -c opt @SwiftLint//:swiftlint

预构建包

从最新 GitHub 发布版本下载 SwiftLint.pkg 并运行它。

从源代码

确保已安装构建工具 Bazel 和最新的 Swift 工具链，并且所有工具都可以在你的 PATH 中找到。

要构建 SwiftLint，克隆此仓库并运行 make install。

设置

[!重要] 虽然在编译 Swift 源文件之前运行 SwiftLint 以在存在 lint 违规时提前退出构建看起来很直观，但重要的是要理解 SwiftLint 是设计用来分析可编译的有效源代码的。不可编译的代码很容易导致意外和令人困惑的结果，特别是在使用 --fix/--autocorrect 命令行参数执行时。

构建工具插件

SwiftLint 可以作为 Swift 包项目和 Xcode 项目的构建工具插件使用。

构建工具插件通过在包/项目目录中定位最顶层的配置文件来确定 SwiftLint 的工作目录。如果在其中找不到配置文件，则使用包/项目目录作为工作目录。

当插件无法解析 SwiftLint 工作目录时，它会抛出错误。例如，在目标的 Swift 文件不位于项目目录内的 Xcode 项目中会发生这种情况。

为了最大化与插件的兼容性，避免需要使用 --config 选项的项目结构。

Swift 包项目

[!注意] 需要通过 Swift 包管理器安装。

构建工具插件在构建每个目标时运行。当项目有多个目标时，必须将插件单独添加到所需的目标中。

要做到这一点，请将插件添加到要进行 lint 检查的目标中，如下所示：

.target(
    ...
    plugins: [.plugin(name: "SwiftLintBuildToolPlugin", package: "SwiftLintPlugins")]
),

Swift 包命令插件

[!注意] 需要通过 Swift 包管理器安装。

命令插件使得可以从命令行运行 SwiftLint，如下所示：

swift package plugin swiftlint

Xcode 项目

[!注意] 需要通过 Xcode 包依赖安装。

构建工具插件作为每个目标的构建阶段运行。当项目有多个目标时，必须将插件单独添加到所需的目标中。

要做到这一点，请将 SwiftLintBuildToolPlugin 添加到要进行 lint 检查的目标的 构建阶段 中的 运行构建工具插件 阶段。

[!提示] 首次使用插件时，请确保在提示时信任并启用它。如果存在宏构建警告，请选择它以信任并启用宏。

对于无人值守使用（例如在 CI 上），可以通过以下任一方式禁用包插件和宏验证：

使用 xcodebuild 选项：

-skipPackagePluginValidation
-skipMacroValidation

设置 Xcode 默认值：

defaults write com.apple.dt.Xcode IDESkipPackagePluginFingerprintValidatation -bool YES
defaults write com.apple.dt.Xcode IDESkipMacroFingerprintValidation -bool YES

[!重要] 无人值守使用选项绕过了 Xcode 的验证对话框，并隐式信任所有插件和宏，这有安全隐患。

意外的 Xcode 项目结构

SwiftLint 的配置文件位于包/项目目录之外的项目结构不被构建工具插件直接支持。这是因为无法向构建工具插件传递参数（例如，传递配置文件路径）。

如果你的项目结构无法直接与构建工具插件配合使用，请考虑以下选项之一：

要使用位于包/项目目录外的配置文件，可以在该目录中添加一个配置文件，指定父配置路径到其他配置文件，例如，parent_config: path/to/.swiftlint.yml。
你也可以考虑使用运行脚本构建阶段来替代构建工具插件。

Xcode 运行脚本构建阶段

[!注意] 根据使用的安装方法，运行脚本构建阶段中的 shell 命令语法可能不同或需要额外配置。有关更多信息，请参阅安装说明。

如果构建工具插件不适用于你的项目设置，或者需要额外的自定义设置，可以将 SwiftLint 添加为运行脚本构建阶段。当项目设置依赖于 --config SwiftLint 选项时，这很有用；或者要在单个 swiftlint 调用中一起对所有目标进行 lint 检查。文件包含和排除可以在 .swiftlint.yml 配置中配置。

要做到这一点，请在主应用目标的 构建阶段 的 编译源文件 阶段之后添加一个自定义脚本到 运行脚本 阶段。使用以下脚本实现：

if command -v swiftlint >/dev/null 2>&1
then
    swiftlint
else
    echo "警告：未找到 `swiftlint`
```ruby
swiftlint(
    mode: :lint,                            # SwiftLint模式: :lint (默认) 或 :autocorrect
    executable: "Pods/SwiftLint/swiftlint", # SwiftLint 二进制路径 (可选)。如果通过 CocoaPods 安装则很重要
    path: "/path/to/lint",                  # 指定要lint的路径 (可选)
    output_file: "swiftlint.result.json",   # 输出文件的路径 (可选)
    reporter: "json",                       # 要使用的自定义报告器 (可选)
    config_file: ".swiftlint-ci.yml",       # 配置文件的路径 (可选)
    files: [                                # 要处理的文件列表 (可选)
        "AppDelegate.swift",
        "path/to/project/Model.swift"
    ],
    ignore_exit_status: true,               # 允许fastlane继续运行,即使SwiftLint返回非零退出状态 (默认: false)
    quiet: true,                            # 不打印状态日志,如'Linting '和'Done linting' (默认: false) 
    strict: true                            # 警告也视为失败？ (默认: false)
)

Docker

SwiftLint 也可以作为 Docker 镜像使用,基于 Ubuntu。因此第一次使用时,你需要使用以下命令拉取 docker 镜像:

docker pull ghcr.io/realm/swiftlint:latest

之后,你只需要在 docker 中运行 swiftlint,像这样:

docker run -it -v `pwd`:`pwd` -w `pwd` ghcr.io/realm/swiftlint:latest

这将在你当前所在的文件夹 (pwd) 中执行 swiftlint,显示类似以下的输出:

$ docker run -it -v `pwd`:`pwd` -w `pwd` ghcr.io/realm/swiftlint:latest
正在lint当前工作目录中的Swift文件
正在lint 'RuleDocumentation.swift' (1/490)
...
正在lint 'YamlSwiftLintTests.swift' (490/490)
lint完成! 在490个文件中发现0个违规,0个严重问题。

这里有更多关于 Docker镜像使用的文档。

命令行用法

$ swiftlint help
概述: 一个用于强制执行Swift样式和约定的工具。

用法: swiftlint <子命令>

选项:
  --version               显示版本。
  -h, --help              显示帮助信息。

子命令:
  analyze                 运行分析规则
  docs                    在默认网络浏览器中打开SwiftLint文档网站
  generate-docs           为选定的规则组生成markdown文档
  lint (默认)             打印lint警告和错误
  baseline                对现有基线进行操作
  reporters               显示报告器列表及其标识符
  rules                   显示规则列表及其标识符
  version                 显示SwiftLint的当前版本

  使用 'swiftlint help <子命令>' 查看详细帮助。

在包含要lint的Swift文件的目录中运行swiftlint。目录将被递归搜索。

当使用lint或analyze时,要指定文件列表(比如由ExtraBuildPhase Xcode插件指定的Xcode修改的文件列表,或基于git ls-files -m的工作树中修改的文件),你可以通过传递选项--use-script-input-files并设置以下实例变量来实现: SCRIPT_INPUT_FILE_COUNT 和 SCRIPT_INPUT_FILE_0, SCRIPT_INPUT_FILE_1, ..., SCRIPT_INPUT_FILE_{SCRIPT_INPUT_FILE_COUNT - 1}。

这些与为自定义Xcode脚本阶段设置的输入文件环境变量相同。

使用多个Swift版本

SwiftLint 挂钩到 SourceKit,因此即使 Swift 不断发展,它也能继续工作!

这也使 SwiftLint 保持精简,因为它不需要附带完整的 Swift 编译器,它只需与你机器上已安装的官方编译器通信即可。

你应该始终使用与编译代码相同的工具链运行 SwiftLint。

如果你安装了多个工具链或 Xcode,你可能想要覆盖 SwiftLint 的默认 Swift 工具链。

以下是 SwiftLint 确定使用哪个 Swift 工具链的顺序:

$XCODE_DEFAULT_TOOLCHAIN_OVERRIDE
$TOOLCHAIN_DIR 或 $TOOLCHAINS
xcrun -find swift
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
/Applications/Xcode-beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
~/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
~/Applications/Xcode-beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain

预期在上述路径值的 usr/lib/ 子目录中找到 sourcekitd.framework。

你还可以设置 TOOLCHAINS 环境变量为标识 Swift 工具链版本的反向 DNS 表示法:

TOOLCHAINS=com.apple.dt.toolchain.Swift_2_3 swiftlint --fix

在 Linux 上,预期 SourceKit 位于 /usr/lib/libsourcekitdInProc.so 或由 LINUX_SOURCEKIT_LIB_PATH 环境变量指定。

Git `pre-commit` 钩子

SwiftLint 可以作为 pre-commit 钩子运行。一旦安装,将以下内容添加到仓库根目录的 .pre-commit-config.yaml 中:

repos:
  - repo: https://github.com/realm/SwiftLint
    rev: 0.50.3
    hooks:
      - id: swiftlint

将 rev 调整为你选择的 SwiftLint 版本。可以使用 pre-commit autoupdate 更新到当前版本。

可以使用 entry 配置 SwiftLint 以应用修复并在出现错误时失败:

-   repo: https://github.com/realm/SwiftLint
    rev: 0.50.3
    hooks:
    -   id: swiftlint
        entry: swiftlint --fix --strict

规则

SwiftLint 包含超过 200 条规则,Swift 社区(就是你!)会随着时间的推移继续贡献更多规则。鼓励提交 Pull requests。

你可以在这里找到更新的规则列表和有关它们的更多信息。

你还可以查看 Source/SwiftLintBuiltInRules/Rules 目录以查看它们的实现。

可选规则

opt_in_rules 默认是禁用的(即,你必须在配置文件中明确启用它们)。

将规则标记为可选的指南:

可能有许多误报的规则(例如 empty_count)
太慢的规则
不是普遍共识或仅在某些情况下有用的规则(例如 force_unwrapping)

在代码中禁用规则

可以使用以下格式的注释在源文件中禁用规则:

// swiftlint:disable <rule1> [<rule2> <rule3>...]

这些规则将被禁用,直到文件结束或直到lint工具看到匹配的启用注释:

// swiftlint:enable <rule1> [<rule2> <rule3>...]

例如:

// swiftlint:disable colon
let noWarning :String = "" // 变量名后立即出现冒号不会产生警告!
// swiftlint:enable colon
let hasWarning :String = "" // 变量名后立即出现冒号会产生警告

包含 all 关键字将禁用所有规则,直到lint工具看到匹配的启用注释:

// swiftlint:disable all // swiftlint:enable all

例如:

// swiftlint:disable all
let noWarning :String = "" // 变量名后立即出现冒号不会产生警告!
let i = "" // 短标识符名称也不会产生警告
// swiftlint:enable all
let hasWarning :String = "" // 变量名后立即出现冒号会产生警告
let y = "" // 短标识符名称会产生警告

也可以通过附加 :previous、:this 或 :next 来修改 disable 或 enable 命令,分别只将命令应用于前一行、当前行或下一行。

例如:

// 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 rules 打印所有可用规则及其标识符的列表。

配置

通过在运行 SwiftLint 的目录中添加 .swiftlint.yml 文件来配置 SwiftLint。可以配置以下参数:

规则包含:

disabled_rules: 从默认启用集中禁用规则。
opt_in_rules: 启用不属于默认集的规则。特殊标识符 all 将启用所有可选的 linter 规则,除了列在 disabled_rules 中的规则。
only_rules: 只有此列表中指定的规则将被启用。不能与 disabled_rules 或 opt_in_rules 一起指定。
analyzer_rules: 这是一个完全独立的规则列表,仅由 analyze 命令运行。所有分析器规则都是可选的,因此这是唯一可配置的规则列表,没有 disabled_rules 和 only_rules 的等价物。特殊标识符 all 也可以在这里使用,以启用除列在 disabled_rules 中的规则之外的所有分析器规则。

# 默认情况下,SwiftLint 使用一组合理的默认规则,你可以调整:
disabled_rules: # 默认启用的规则标识符,用于从运行中排除
  - colon
  - comma
  - control_statement
opt_in_rules: # 一些规则默认是关闭的,所以你需要选择加入
  - empty_count # 运行 `swiftlint rules` 可以找到所有可用的规则

# 或者,通过取消注释此选项来明确指定所有规则:
# only_rules: # 如果使用此选项,请删除 `disabled_rules` 和 `opt_in_rules`
#   - empty_parameters
#   - vertical_whitespace

analyzer_rules: # 由 `swiftlint analyze` 运行的规则
  - explicit_self

# 在 linting 期间包括的区分大小写的路径。在命令行上提供的目录路径将被忽略。
included: 
  - Sources
excluded: # 在 linting 期间忽略的区分大小写的路径。优先于 `included`
  - Carthage
  - Pods
  - Sources/ExcludedFolder
  - Sources/ExcludedFile.swift
  - Sources/*/ExcludedFile.swift # 使用通配符排除文件

# 如果为 true,当没有找到可 lint 的文件时,SwiftLint 不会失败。
allow_zero_lintable_files: false

# 如果为 true,SwiftLint 会将所有警告视为错误。
strict: false

# 基准文件的路径,该文件将用于过滤检测到的违规。
baseline: Baseline.json

# 将检测到的违规保存为新基准的路径。
write_baseline: Baseline.json

# 如果为 true,SwiftLint 将在 linting 或分析后检查更新。
check_for_updates: true

# 可配置的规则可以从此配置文件进行自定义
# 二进制规则可以设置其严重程度级别
force_cast: warning # 隐式
force_try:
  severity: warning # 显式
# 同时具有警告和错误级别的规则,可以只设置警告级别
# 隐式
line_length: 110
# 它们可以用数组隐式设置两者
type_body_length:
  - 300 # warning
  - 400 # error
# 或者可以显式设置两者
file_length:
  warning: 500
  error: 1200
# 命名规则可以为 min_length 和 max_length 设置警告/错误
# 此外,它们可以设置排除的名称
type_name:
  min_length: 4 # 只有警告
  max_length: # 警告和错误
    warning: 40
    error: 50
  excluded: iPhone # 通过字符串排除
  allowed_symbols: ["_"] # 这些
custom_rules:
  no_hiding_in_strings:
    regex: "([nN]inja)"
    match_kinds: string

与Swift自定义规则不同，你可以使用官方SwiftLint构建（例如从Homebrew获取）来运行正则表达式自定义规则。

自动修正

SwiftLint可以自动修正某些违规。磁盘上的文件将被覆盖为修正后的版本。

请确保在运行swiftlint --fix之前备份这些文件，否则可能会丢失重要数据。

在应用修正时修改文件时，违规（或其偏移量）很可能不正确，因此在修正过程中会禁用标准lint检查。

分析

swiftlint analyze命令可以使用完整的类型检查AST来lint Swift文件。必须通过--compiler-log-path标志将包含干净的swiftc构建命令调用（增量构建将失败）的编译器日志路径传递给analyze。例如：--compiler-log-path /path/to/xcodebuild.log

可以通过以下方式获取：

清理DerivedData（增量构建无法与analyze一起使用）
运行xcodebuild -workspace {WORKSPACE}.xcworkspace -scheme {SCHEME} > xcodebuild.log
运行swiftlint analyze --compiler-log-path xcodebuild.log

分析器规则往往比lint规则慢得多。

使用多个配置文件

SwiftLint提供了多种方法来包含多个配置文件。多个配置文件会合并成一个单一配置，然后像应用单个配置文件一样应用。

有很多使用多个配置文件可能有帮助的用例：

例如，可以使用团队范围内共享的SwiftLint配置，同时允许通过子配置文件在每个项目中进行覆盖。

团队范围配置：

disabled_rules:
- force_cast

项目特定配置：

opt_in_rules:
- force_cast

子/父配置（本地）

你可以在配置文件中指定child_config和/或parent_config引用。这些引用应该是相对于它们所在配置文件文件夹的本地路径。这甚至可以递归工作，只要没有循环和歧义。

子配置被视为细化，因此具有更高的优先级，而父配置被视为基础，在冲突情况下具有较低的优先级。

这里有一个例子，假设你有以下文件结构：

ProjectRoot
    |_ .swiftlint.yml
    |_ .swiftlint_refinement.yml
    |_ Base
        |_ .swiftlint_base.yml

要包含细化和基础文件，你的.swiftlint.yml应该如下所示：

child_config: .swiftlint_refinement.yml
parent_config: Base/.swiftlint_base.yml

在合并父配置和子配置时，会仔细处理included和excluded配置，以考虑包含配置文件的目录位置差异。

子/父配置（远程）

就像你可以提供本地child_config/parent_config引用一样，你也可以放置指向配置文件的URL，而不是引用本地路径。为了让SwiftLint检测到这些远程引用，它们必须以http://或https://开头。

引用的远程配置文件甚至可以递归引用其他远程配置文件，但不允许包含本地引用。

使用远程引用，你的.swiftlint.yml可能如下所示：

parent_config: https://myteamserver.com/our-base-swiftlint-config.yml

每次运行SwiftLint并有互联网连接时，SwiftLint都会尝试获取每个引用的远程配置的新版本。如果此请求超时，则使用缓存版本（如果可用）。如果没有可用的缓存版本，SwiftLint将失败 - 但不用担心，一旦SwiftLint成功运行至少一次，缓存版本应该就会存在。

如果需要，可以通过配置文件使用remote_timeout/remote_timeout_if_cached指定符手动指定远程配置获取的超时时间。这些值默认分别为2秒或1秒。

命令行

在通过命令行运行SwiftLint时，除了提供一个配置文件外，你还可以传递一个层次结构，其中第一个配置被视为父配置，而最后一个被视为最高优先级的子配置。

一个简单的例子，包括两个配置文件，如下所示：

swiftlint --config .swiftlint.yml --config .swiftlint_child.yml

嵌套配置

除了主配置（根文件夹中的.swiftlint.yml文件）外，你还可以将其他名为.swiftlint.yml的配置文件放入目录结构中，这些文件然后作为子配置合并，但只对与配置位于同一目录或更深目录中且没有其他配置文件的文件有效。换句话说：嵌套配置不会递归工作 - 每个文件最多可应用一个嵌套配置，除了主配置之外。

只有当.swiftlint.yml文件尚未用于构建主配置时（例如，通过类似child_config: Folder/.swiftlint.yml的引用），才会将其视为嵌套配置。此外，嵌套配置的parent_config/child_config规范会被忽略，因为这没有意义。

如果通过--config参数明确指定了一个（或多个）SwiftLint文件，则该配置将被视为覆盖，无论目录中是否存在其他.swiftlint.yml文件。因此，如果你想使用嵌套配置，就不能使用--config参数。