[翻譯練習] 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教程