什么是Sourcery?
Sourcery 是當下最流行的 Swift 代碼生成工具之一。其背后使用了 SwiftSyntax[1]，旨在通過自動生成樣板代碼來節省開發人員的時間。Sourcery 通過掃描一組輸入文件，然后借助模板的幫助，自動生成模板中定義的 Swift 代碼。
示例
考慮一個為攝像機會話服務提供公共 API 的協議：
protocol Camera {
func start()
func stop()
func capture(_ completion: @escaping (UIImage?) -> Void)
func rotate()
}當使用此新的 Camera service 進行單元測試時，我們希望確保 AVCaptureSession 沒有被真的創建。我們僅僅希望確認 camera service 被測試系統（SUT）正確的調用了，而不是去測試 camera service 本身。
因此，創建一個協議的 mock 實現，使用空方法和一組變量來幫助我們進行單元測試，并斷言（asset）進行了正確的調用是有意義的。這是軟件開發中非常常見的一個場景，如果你曾維護過一個包含大量單元測試的大型代碼庫，這么做也可能有點乏味。
好吧~不用擔心！Sourcery 會幫助你！?? 它有一個叫做 AutoMockable[2] 的模板，此模板會為任意輸入文件中遵守 AutoMockable 協議的協議生成 mock 實現。
注意：在本文中，我擴展地使用了術語 Mock，因為它與 Sourcery 模板使用的術語一致。Mock 是一個相當重載的術語，但通常，如果我要創建一個 雙重測試[3]，我會根據它的用途進一步指定類型的名稱（可能是 Spy 、 Fake 、 Stub 等）。如果您有興趣了解更多關于雙重測試的信息，馬丁·福勒（Martin Fowler）有一篇非常好的文章，可以解釋這些差異。
現在，我們讓 Camera 遵守 AutoMockable。該接口的唯一目的是充當 Sourcery 的目標，從中查找并生成代碼。
import UIKit
// Protocol to be matched
protocol AutoMockable {}
public protocol Camera: AutoMockable {
func start()
func stop()
func capture(_ completion: @escaping (UIImage?) -> Void)
func rotate()
}
此時，可以在上面的輸入文件上運行 Sourcery 命令，指定 AutoMockable 模板的路徑：
sourcery --sources Camera.swift --templates AutoMockable.stencil --output .
本文通過提供一個 .sourcery.yml 文件來配置 Sourcery 插件。如果提供了配置文件或 Sourcery 可以找到配置文件，則將忽略與其值沖突的所有命令行參數。如果您想了解有關配置文件的更多信息，Sourcery的 repo 中有一節[4]介紹了該主題。
命令執行完畢后，在輸出目錄下會生成一個 模板名 加 .generated.swift 為后綴的文件。在此例是 ./AutoMockable.generated.swift：
// Generated using Sourcery 1.8.2 — https://github.com/krzysztofzablocki/Sourcery
// DO NOT EDIT
// swiftlint:disable line_length
// swiftlint:disable variable_name
import Foundation
#if os(iOS) || os(tvOS) || os(watchOS)
import UIKit
#elseif os(OSX)
import AppKit
#endif
class CameraMock: Camera {
//MARK: - start
var startCallsCount = 0
var startCalled: Bool {
return startCallsCount > 0
}
var startClosure: (() -> Void)?
func start() {
startCallsCount += 1
startClosure?()
}
//MARK: - stop
var stopCallsCount = 0
var stopCalled: Bool {
return stopCallsCount > 0
}
var stopClosure: (() -> Void)?
func stop() {
stopCallsCount += 1
stopClosure?()
}
//MARK: - capture
var captureCallsCount = 0
var captureCalled: Bool {
return captureCallsCount > 0
}
var captureReceivedCompletion: ((UIImage?) -> Void)?
var captureReceivedInvocations: [((UIImage?) -> Void)] = []
var captureClosure: ((@escaping (UIImage?) -> Void) -> Void)?
func capture(_ completion: @escaping (UIImage?) -> Void) {
captureCallsCount += 1
captureReceivedCompletion = completion
captureReceivedInvocations.append(completion)
captureClosure?(completion)
}
//MARK: - rotate
var rotateCallsCount = 0
var rotateCalled: Bool {
return rotateCallsCount > 0
}
var rotateClosure: (() -> Void)?
func rotate() {
rotateCallsCount += 1
rotateClosure?()
}
}
上面的文件（AutoMockable.generated.swift）包含了你對mock的期望：使用空方法實現與目標協議的一致性，以及檢查是否調用了這些協議方法的一組變量。最棒的是… Sourcery 為您編寫了這一切！??
怎么運行 Sourcery？
怎么使用 Swift package 運行 Sourcery？
至此你可能在想如何以及怎樣在 Swift package 中運行 Sourcery。你可以手動執行，然后講文件拖到包中，或者從包目錄中的命令運行腳本。但是對于 Swift Package 有兩種內置方式運行可執行文件：
- 通過命令行插件，可根據用戶輸入任意運行
- 通過構建工具插件，該插件作為構建過程的一部分運行。
在本文中，我將介紹 Sourcery 命令行插件，但我已經在編寫第二部分，其中我將創建構建工具插件，這帶來了許多有趣的挑戰。
創建插件包
讓我們首先創建一個空包，并去掉測試和其他我們現在不需要的文件夾。然后我們可以創建一個新的插件 ??Target?? 并添加 Sourcery 的二進制文件作為其依賴項。
為了讓消費者使用這個插件，它還需要被定義為一個產品：
// swift-tools-version: 5.6
import PackageDescription
let package = Package(
name: "SourceryPlugins",
products: [
.plugin(name: "SourceryCommand", targets: ["SourceryCommand"])
],
targets: [
// 1
.plugin(
name: "SourceryCommand",
// 2
capability: .command(
intent: .custom(verb: "sourcery-code-generation", description: "Generates Swift files from a given set of inputs"),
// 3
permissions: [.writeToPackageDirectory(reason: "Need access to the package directory to generate files")]
),
dependencies: ["Sourcery"]
),
// 4
.binaryTarget(
name: "Sourcery",
path: "Sourcery.artifactbundle"
)
]
)
讓我們一步一步地仔細查看上面的代碼：
- 定義插件目標。
- 以custom 為意圖，定義了 .command 功能，因為沒有任何默認功能（ documentationGeneration 和 sourceCodeFormatting）與該命令的用例匹配。給動詞一個合理的名稱很重要，因為這是從命令行調用插件的方式。
- 插件需要向用戶請求寫入包目錄的權限，因為生成的文件將被轉儲到該目錄。
- 為插件定義了一個二進制目標文件。這將允許插件通過其上下文訪問可執行文件。
我知道我并沒有詳細介紹上面的一些概念，但如果您想了解更多關于命令插件的信息，這里有一篇由 Tibor B?decs 寫的超級棒的文章?。如果你還想了解更多關于 Swift Packages 中二級制的目標（文件），我同樣有一篇??現今 Swift 包中的二進制目標??。
編寫插件
現在已經創建了包，是時候編寫一些代碼了！我們首先在 Plugins/SourceryCommand 下創建一個名為 SourceryCommand.swift 的文件，然后添加一個 CommandPlugin 協議的結構體，這將作為該插件的入口：
import PackagePlugin
import Foundation
@main
struct SourceryCommand: CommandPlugin {
func performCommand(context: PluginContext, arguments: [String]) async throws {
}
}
然后我們為命令編寫實現：
func performCommand(context: PluginContext, arguments: [String]) async throws {
// 1
let configFilePath = context.package.directory.appending(subpath: ".sourcery.yml").string
guard FileManager.default.fileExists(atPath: configFilePath) else {
Diagnostics.error("Could not find config at: \(configFilePath)")
return
}
//2
let sourceryExecutable = try context.tool(named: "sourcery")
let sourceryURL = URL(fileURLWithPath: sourceryExecutable.path.string)
// 3
let process = Process()
process.executableURL = sourceryURL
// 4
process.arguments = [
"--disableCache"
]
// 5
try process.run()
process.waitUntilExit()
// 6
let gracefulExit = process.terminationReason == .exit && process.terminationStatus == 0
if !gracefulExit {
Diagnostics.error("?? The plugin execution failed")
}
}讓我們仔細看看上面的代碼：
- 首先.sourcery.yml 文件必須在包的根目錄，否則將報錯。這將使 Sourcery 神奇的工作，并使包可配置。
- 可執行文件路徑的 URL 是從命令的上下文中檢索的。
- 創建一個進程，并將 Sourcery 的可執行文件的 URL 設置為其可執行文件路徑。
- 這一步有點麻煩。Sourcery 使用緩存來減少后續運行的代碼生成時間，但問題是這些緩存是在包文件夾之外讀取和寫入的文件。插件的沙箱規則不允許這樣做，因此--disableCache 標志用于禁用此行為并允許命令運行。
- 進程同步運行并等待。
- 最后，檢查進程終止狀態和代碼，以確保進程已正常退出。在任何其他情況下，通過Diagnostics API 向用戶告知錯誤。
就這樣！現在讓我們使用它
使用（插件）包
考慮一個用戶正在使用插件，該插件將依賴項引入了他們的 Package.swift 文件：
// swift-tools-version: 5.6
// The swift-tools-version declares the minimum version of Swift required to build this package.
import PackageDescription
let package = Package(
name: "SourceryPluginSample",
products: [
// Products define the executables and libraries a package produces, and make them visible to other packages.
.library(
name: "SourceryPluginSample",
targets: ["SourceryPluginSample"]),
],
dependencies: [
.package(url: "https://github.com/pol-piella/sourcery-plugins.git", branch: "main")
],
targets: [
.target(
name: "SourceryPluginSample",
dependencies: [],
exclude: ["SourceryTemplates"]
),
]
)
注意，與構建工具插件不同，命令插件不需要應用于任何目標，因為它們需要手動運行。
用戶只使用了上面的 AutoMockable 模板（可以在 Sources/SourceryPluginSample/SourceryTemplates 下找到），與本文前面顯示的示例相匹配：
protocol AutoMockable {}
protocol Camera: AutoMockable {
func start()
func stop()
func capture(_ completion: @escaping (UIImage?) -> Void)
func rotate()
}根據插件的要求，用戶還提供了一個位于 SourceryPluginSample 目錄下的 .sourcery.yml 配置文件：
sources:
- Sources/SourceryPluginSample
templates:
- Sources/SourceryPluginSample/SourceryTemplates
output: Sources/SourceryPluginSample
運行命令
用戶已經設置好了，但是他們現在如何運行包？?? 有兩種方法：
命令行
運行插件的一種方法是用命令行?？梢酝ㄟ^從包目錄中運行 swift package plugin --list 來檢索特定包的可用插件列表。然后可以從列表中選擇一個包，并通過運行 swift package <command's verb> 來執行，在這個特殊的例子中，運行： swift package sourcery-code-generation。
注意，由于此包需要特殊權限，因此 --allow-writing-to-package-directory 必須與命令一起使用。
此時，你可能會想，為什么我要費心編寫一個插件，仍然必須從命令行運行，而我可以用一個簡單的腳本在幾行 bash 中完成相同的工作？好吧，讓我們來看看 Xcode 14 中會出現什么，你會明白為什么我會提倡編寫插件??。
Xcode
這是運行命令插件最令人興奮的方式，但不幸的是，它僅在 Xcode 14 中可用。因此，如果您需要運行命令，但尚未使用 Xcode 14，請參閱命令行部分。
如果你正好在使用 Xcode 14，你可以通過在文件資源管理器中右鍵單擊包，從列表中找到要執行的插件，然后單擊它來執行包的任何命令。
下一步
這是插件的初始實現。我將研究如何改進它，使它更加健壯。和往常一樣，我非常致力于公開構建，并使我的文章中的所有內容都開源，這樣任何人都可以提交問題或創建任何具有改進或修復的 PRs。這沒有什么不同??, 這是 公共倉庫的鏈接。
此外，如果您喜歡這篇文章，請關注即將到來的第二部分，其中我將制作一個 Sourcery 構建工具插件。我知道這聽起來不多，但這不是一項容易的任務！
參考資料
[1] SwiftSyntax: ??https://github.com/apple/swift-syntax。??
[2] AutoMockable: ??https://github.com/krzysztofzablocki/Sourcery/blob/master/Templates/Templates/AutoMockable.stencil。??
[3] 雙重測試: ??https://en.wikipedia.org/wiki/Test_double。??
[4] repo: ??https://github.com/krzysztofzablocki/Sourcery/blob/master/guides/Usage.md#configuration-file。??
