[翻译练习] SwiftLint 自述

时间  2019-11-29
标签 翻译 练习 swiftlint 自述 繁體版
原文   原文链接

译自：github.com/realm/Swift…html

SwiftLint

SwiftLint 是一个用于强制检查 Swift 代码风格和规定的一个工具，基本上以 GitHub's Swift 代码风格指南为基础。git

SwiftLint Hook 了 Clang 和 SourceKit 从而可以使用 AST 来表示源代码文件的更多精确结果。github

Test Status
codecov.io

该项目遵照 贡献者契约行为守则。一旦参与，你将被视为支持这一守则。请将 不可接受的行为报告给 info@realm.io。正则表达式

安装

使用 Homebrew：

brew install swiftlint
复制代码

使用 CocoaPods：

将以下代码添加到你的 Podfile 便可：shell

pod 'SwiftLint'
复制代码

在下一次执行 pod install 时将会把 SwiftLint 的二进制文件和依赖下载到 Pods/ 目录下而且将容许你经过 ${PODS_ROOT}/SwiftLint/swiftlint 在 Script Build Phases 中调用 SwiftLint。json

自从 SwiftLint 支持安装某个特定版本后，安装一个指定版本的 SwiftLint 是目前推荐的作法相比较于简单地选择最新版本安装的话（好比经过 Homebrew 安装的话）。swift

请注意这会将 SwiftLint 二进制文件、所依赖的二进制文件和 Swift 二进制库安装到 Pods/ 目录下，因此请将此目录添加到版本控制系统中进行跟踪。数组

使用安装包：

你也能够经过从最新的 GitHub 发布地址下载 SwiftLint.pkg 而后执行的方式安装 SwiftLint。xcode

编译源代码：

你也能够经过 Clone SwiftLint 的 Git 仓库到本地而后执行 git submodule update --init --recursive; make install (Xcode 8.3+) 编译源代码的方式来安装。ruby

用法

报告

咱们鼓励您观看本次报告，来得到将 SwiftLint 整合到你的项目中的推荐方式的一个高层次归纳：

Presentation

Xcode

整合 SwiftLint 到 Xcode 体系中去从而可使警告和错误显示到 IDE 上，只须要在 Xcode 中添加一个新的“Run Script Phase”而且包含以下代码便可：

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

或者，脚本看起来应该像这样若是你已经经过 CocoaPods 安装了 SwiftLint：

"${PODS_ROOT}/SwiftLint/swiftlint"
复制代码

格式化保存 Xcode 插件

在 XCode 中保存时执行 swiftlint autocorrect，须要从 Alcatraz 安装 SwiftLintXcode 插件。

⚠ ️若是没有禁用 SIP 的话，这个插件在 Xcode 8 或者更新版本的 Xcode 上将不会工做。不推荐此操做。

AppCode

在 AppCode 中使用 SwiftLint，安装这个插件而且在插件设置中配置 SwiftLint 的安装路径便可。autocorrect 操做快捷键为 ⌥⏎。

Atom

整合 SwiftLint 到 Atom 须要从 APM 安装 linter-swiftlint 包。

命令行

$ swiftlint help
Available commands:

   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
复制代码

在包含有须要执行代码分析的 Swift 源码文件的目录下执行 swiftlint 命令，会对目录进行递归查找。

当使用 lint 或者 autocorrect 命令时，你能够经过添加 --use-script-input-files 选项而且设置如下实例变量：SCRIPT_INPUT_FILE_COUNT 和 SCRIPT_INPUT_FILE_0, SCRIPT_INPUT_FILE_1... SCRIPT_INPUT_FILE_{SCRIPT_INPUT_FILE_COUNT} 的方式来指定一个文件列表（就像被 Xcode 特别是 ExtraBuildPhase Xcode 插件修改的文件组成的列表，或者相似 Git 工做树中 git ls-files -m 命令显示的被修改的文件列表）。

也有相似的用来设置输入文件的环境变量以 自定义 Xcode script phases 。

使用多个 Swift 版本

SwiftLint 工做于 SourceKit 这一层，因此 Swift 版本发生变化时它也能继续工做！

这也是 SwiftLint 轻量化的缘由，由于它不须要一个完整的 Swift 编译器，它只是与已经安装在你的电脑上的官方编译器进行通讯。

你应该老是使用和你编译代码一样的工具集来执行 SwiftLint。

若是你有多套工具集或者安装了多个不一样版本的 Xcode，你可能会须要覆盖 SwiftLint 默认的工具集。

下面这些命令能够控制 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

sourcekitd.framework 默认须要位于 usr/lib/ 中，上面传入的路径的子目录中。

你可能也给反向 DNS 符号设置了 TOOLCHAINS 环境变量来标记一个特定的 Swift 工具集版本：

$ TOOLCHAINS=com.apple.dt.toolchain.Swift_2_3 swiftlint autocorrect
复制代码

在 Linux 上，SourceKit 默认须要位于 /usr/lib/libsourcekitdInProc.so 或者经过 LINUX_SOURCEKIT_LIB_PATH 环境变量进行指定。

Swift Version Support

这里有一份 SwiftLint 版本和对应该 Swift 版本的对照表做为参考。

Swift 版本 最后一个 SwiftLint 支持版本
Swift 1.x SwiftLint 0.1.2
Swift 2.x SwiftLint 0.18.1
Swift 3.x 最新的
Swift 4.x 最新的

规则

SwiftLint 已经包含了超过 75 条规则，而且咱们但愿 Swift 社区（就是你！）会在之后有更多的贡献，咱们鼓励提交 Pull Requests。

你能够在 Rules.md 找到规则的更新列表和更多信息。

你也能够检视 Source/SwiftLintFramework/Rules 目录来查看它们的实现。

opt_in_rules 默认是关闭的（即，你须要在你的配置文件中明确地打开它们）。

何时须要将一个规则设为 opt-in 的指南：

  • 一个可能会有许多负面做用的规则（例如 empty_count）
  • 一个过慢的规则
  • 一个不通用或者仅在某些特定场景下可用的规则（例如 force_unwrapping）

在代码中关闭某个规则

能够经过在一个源文件中定义一个以下格式的注释来关闭某个规则：

// swiftlint:disable <rule>

在该文件结束以前或者在定义以下格式的匹配注释以前，这条规则都会被禁用：

// swiftlint:enable <rule>

例如：

// swiftlint:disable colon
let noWarning :String = "" // No warning about colons immediately after variable names!
// swiftlint:enable colon
let hasWarning :String = "" // Warning generated about colons immediately after variable names
复制代码

也能够经过添加 :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 rules 命令能够输出全部可用的规则和他们的标识符组成的列表。

配置

能够经过在你须要执行 SwiftLint 的目录下添加一个 .swiftlint.yml 文件的方式来配置 SwiftLint。能够被配置的参数有：

包含的规则：

  • disabled_rules: 关闭某些默认开启的规则。
  • opt_in_rules: 一些规则是可选的。
  • whitelist_rules: 不能够和 disabled_rules 或者 opt_in_rules 并列。相似一个白名单，只有在这个列表中的规则才是开启的。
disabled_rules: # 执行时排除掉的规则
 - colon
 - comma
 - control_statement
opt_in_rules: # 一些规则仅仅是可选的
 - empty_count
 - missing_docs
  # 能够经过执行以下指令来查找全部可用的规则:
  # swiftlint rules
included: # 执行 linting 时包含的路径。若是出现这个 `--path` 会被忽略。
 - Source
excluded: # 执行 linting 时忽略的路径。 优先级比 `included` 更高。
 - Carthage
 - Pods
 - Source/ExcludedFolder
 - Source/ExcludedFile.swift

# 可配置的规则能够经过这个配置文件来自定义
# 二进制规则能够设置他们的严格程度
force_cast: warning # 隐式
force_try:
 severity: warning # 显式
# 同时有警告和错误等级的规则，能够只设置它的警告等级
# 隐式
line_length: 110
# 能够经过一个数组同时进行隐式设置
type_body_length:
 - 300 # warning
 - 400 # error
# 或者也能够同时进行显式设置
file_length:
 warning: 500
 error: 1200
# 命名规则能够设置最小长度和最大程度的警告/错误
# 此外它们也能够设置排除在外的名字
type_name:
 min_length: 4 # 只是警告
 max_length: # 警告和错误
 warning: 40
 error: 50
 excluded: iPhone # 排除某个名字
identifier_name:
 min_length: # 只有最小长度
 error: 4 # 只有错误
 excluded: # 排除某些名字
 - id
 - URL
 - GlobalAPIKey
reporter: "xcode" # 报告类型 (xcode, json, csv, checkstyle, junit, html, emoji)
复制代码

定义自定义规则

你能够用以下语法在你的配置文件里定义基于正则表达式的自定义规则：

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

输出大概多是这个样子的：

你能够经过提供一个或者多个 match_kinds 的方式来对匹配进行筛选，它会将含有不包括在列表中的语法类型的匹配排除掉。这里有所有可用的语法类型：

  • argument
  • attribute.builtin
  • attribute.id
  • buildconfig.id
  • buildconfig.keyword
  • comment
  • comment.mark
  • comment.url
  • doccomment
  • doccomment.field
  • identifier
  • keyword
  • number
  • objectliteral
  • parameter
  • placeholder
  • string
  • string_interpolation_anchor
  • typeidentifier

嵌套配置

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

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

自动更正

SwiftLint 能够自动修正某些错误，磁盘上的文件会被一个修正后的版本覆盖。

请确保在对文件执行 swiftlint autocorrect 以前有对它们作过备份，不然的话有可能致使重要数据的丢失。

由于在执行自动更正修改某个文件后颇有可能致使以前生成的代码检查信息无效或者不正确，因此当在执行代码更正时标准的检查是没法使用的。

协议

MIT 许可。

关于

SwiftLint 是由 Realm Inc 创建和维护的。Realm 的名字和标志是属于 Realm Inc 的注册商标。

咱们 :heart: 开源软件！看一下咱们的其余开源项目，瞅一眼咱们的博客，或者在推特上跟咱们唠唠嗑(@realm)。

若有任何知识产权、版权问题或理论错误，还请指正。 https://juejin.im/post/5a32129351882578da0de237 转载请注明原做者及以上信息。

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程