Sourcery 的 Swift Package 命令行插件
什么是Sourcery?
Sourcery 是當(dāng)下最流行的 Swift 代碼生成工具之一。其背后使用了 SwiftSyntax[1],旨在通過自動(dòng)生成樣板代碼來節(jié)省開發(fā)人員的時(shí)間。Sourcery 通過掃描一組輸入文件,然后借助模板的幫助,自動(dòng)生成模板中定義的 Swift 代碼。
示例
考慮一個(gè)為攝像機(jī)會(huì)話服務(wù)提供公共 API 的協(xié)議:
當(dāng)使用此新的 Camera service 進(jìn)行單元測(cè)試時(shí),我們希望確保 AVCaptureSession 沒有被真的創(chuàng)建。我們僅僅希望確認(rèn) camera service 被測(cè)試系統(tǒng)(SUT)正確的調(diào)用了,而不是去測(cè)試 camera service 本身。
因此,創(chuàng)建一個(gè)協(xié)議的 mock 實(shí)現(xiàn),使用空方法和一組變量來幫助我們進(jìn)行單元測(cè)試,并斷言(asset)進(jìn)行了正確的調(diào)用是有意義的。這是軟件開發(fā)中非常常見的一個(gè)場(chǎng)景,如果你曾維護(hù)過一個(gè)包含大量單元測(cè)試的大型代碼庫,這么做也可能有點(diǎn)乏味。
好吧~不用擔(dān)心!Sourcery 會(huì)幫助你!?? 它有一個(gè)叫做 AutoMockable[2] 的模板,此模板會(huì)為任意輸入文件中遵守 AutoMockable 協(xié)議的協(xié)議生成 mock 實(shí)現(xiàn)。
注意:在本文中,我擴(kuò)展地使用了術(shù)語 Mock,因?yàn)樗c Sourcery 模板使用的術(shù)語一致。Mock 是一個(gè)相當(dāng)重載的術(shù)語,但通常,如果我要?jiǎng)?chuàng)建一個(gè) 雙重測(cè)試[3],我會(huì)根據(jù)它的用途進(jìn)一步指定類型的名稱(可能是 Spy 、 Fake 、 Stub 等)。如果您有興趣了解更多關(guān)于雙重測(cè)試的信息,馬丁·福勒(Martin Fowler)有一篇非常好的文章,可以解釋這些差異。
現(xiàn)在,我們讓 Camera 遵守 AutoMockable。該接口的唯一目的是充當(dāng) Sourcery 的目標(biāo),從中查找并生成代碼。
此時(shí),可以在上面的輸入文件上運(yùn)行 Sourcery 命令,指定 AutoMockable 模板的路徑:
本文通過提供一個(gè) .sourcery.yml 文件來配置 Sourcery 插件。如果提供了配置文件或 Sourcery 可以找到配置文件,則將忽略與其值沖突的所有命令行參數(shù)。如果您想了解有關(guān)配置文件的更多信息,Sourcery的 repo 中有一節(jié)[4]介紹了該主題。
命令執(zhí)行完畢后,在輸出目錄下會(huì)生成一個(gè) 模板名 加 .generated.swift 為后綴的文件。在此例是 ./AutoMockable.generated.swift:
上面的文件(AutoMockable.generated.swift)包含了你對(duì)mock的期望:使用空方法實(shí)現(xiàn)與目標(biāo)協(xié)議的一致性,以及檢查是否調(diào)用了這些協(xié)議方法的一組變量。最棒的是… Sourcery 為您編寫了這一切!??
怎么運(yùn)行 Sourcery?
怎么使用 Swift package 運(yùn)行 Sourcery?
至此你可能在想如何以及怎樣在 Swift package 中運(yùn)行 Sourcery。你可以手動(dòng)執(zhí)行,然后講文件拖到包中,或者從包目錄中的命令運(yùn)行腳本。但是對(duì)于 Swift Package 有兩種內(nèi)置方式運(yùn)行可執(zhí)行文件:
- 通過命令行插件,可根據(jù)用戶輸入任意運(yùn)行
- 通過構(gòu)建工具插件,該插件作為構(gòu)建過程的一部分運(yùn)行。
在本文中,我將介紹 Sourcery 命令行插件,但我已經(jīng)在編寫第二部分,其中我將創(chuàng)建構(gòu)建工具插件,這帶來了許多有趣的挑戰(zhàn)。
創(chuàng)建插件包
讓我們首先創(chuàng)建一個(gè)空包,并去掉測(cè)試和其他我們現(xiàn)在不需要的文件夾。然后我們可以創(chuàng)建一個(gè)新的插件 ??Target?
? 并添加 Sourcery 的二進(jìn)制文件作為其依賴項(xiàng)。
為了讓消費(fèi)者使用這個(gè)插件,它還需要被定義為一個(gè)產(chǎn)品:
讓我們一步一步地仔細(xì)查看上面的代碼:
- 定義插件目標(biāo)。
- 以custom 為意圖,定義了 .command 功能,因?yàn)闆]有任何默認(rèn)功能( documentationGeneration 和 sourceCodeFormatting)與該命令的用例匹配。給動(dòng)詞一個(gè)合理的名稱很重要,因?yàn)檫@是從命令行調(diào)用插件的方式。
- 插件需要向用戶請(qǐng)求寫入包目錄的權(quán)限,因?yàn)樯傻奈募⒈晦D(zhuǎn)儲(chǔ)到該目錄。
- 為插件定義了一個(gè)二進(jìn)制目標(biāo)文件。這將允許插件通過其上下文訪問可執(zhí)行文件。
我知道我并沒有詳細(xì)介紹上面的一些概念,但如果您想了解更多關(guān)于命令插件的信息,這里有一篇由 Tibor B?decs 寫的超級(jí)棒的文章?。如果你還想了解更多關(guān)于 Swift Packages 中二級(jí)制的目標(biāo)(文件),我同樣有一篇??現(xiàn)今 Swift 包中的二進(jìn)制目標(biāo)??。
編寫插件
現(xiàn)在已經(jīng)創(chuàng)建了包,是時(shí)候編寫一些代碼了!我們首先在 Plugins/SourceryCommand 下創(chuàng)建一個(gè)名為 SourceryCommand.swift 的文件,然后添加一個(gè) CommandPlugin 協(xié)議的結(jié)構(gòu)體,這將作為該插件的入口:
然后我們?yōu)槊罹帉憣?shí)現(xiàn):
讓我們仔細(xì)看看上面的代碼:
- 首先.sourcery.yml 文件必須在包的根目錄,否則將報(bào)錯(cuò)。這將使 Sourcery 神奇的工作,并使包可配置。
- 可執(zhí)行文件路徑的 URL 是從命令的上下文中檢索的。
- 創(chuàng)建一個(gè)進(jìn)程,并將 Sourcery 的可執(zhí)行文件的 URL 設(shè)置為其可執(zhí)行文件路徑。
- 這一步有點(diǎn)麻煩。Sourcery 使用緩存來減少后續(xù)運(yùn)行的代碼生成時(shí)間,但問題是這些緩存是在包文件夾之外讀取和寫入的文件。插件的沙箱規(guī)則不允許這樣做,因此--disableCache 標(biāo)志用于禁用此行為并允許命令運(yùn)行。
- 進(jìn)程同步運(yùn)行并等待。
- 最后,檢查進(jìn)程終止?fàn)顟B(tài)和代碼,以確保進(jìn)程已正常退出。在任何其他情況下,通過Diagnostics API 向用戶告知錯(cuò)誤。
就這樣!現(xiàn)在讓我們使用它
使用(插件)包
考慮一個(gè)用戶正在使用插件,該插件將依賴項(xiàng)引入了他們的 Package.swift 文件:
注意,與構(gòu)建工具插件不同,命令插件不需要應(yīng)用于任何目標(biāo),因?yàn)樗鼈冃枰謩?dòng)運(yùn)行。
用戶只使用了上面的 AutoMockable 模板(可以在 Sources/SourceryPluginSample/SourceryTemplates 下找到),與本文前面顯示的示例相匹配:
根據(jù)插件的要求,用戶還提供了一個(gè)位于 SourceryPluginSample 目錄下的 .sourcery.yml 配置文件:
運(yùn)行命令
用戶已經(jīng)設(shè)置好了,但是他們現(xiàn)在如何運(yùn)行包??? 有兩種方法:
命令行
運(yùn)行插件的一種方法是用命令行。可以通過從包目錄中運(yùn)行 swift package plugin --list 來檢索特定包的可用插件列表。然后可以從列表中選擇一個(gè)包,并通過運(yùn)行 swift package <command's verb> 來執(zhí)行,在這個(gè)特殊的例子中,運(yùn)行: swift package sourcery-code-generation。
注意,由于此包需要特殊權(quán)限,因此 --allow-writing-to-package-directory 必須與命令一起使用。
此時(shí),你可能會(huì)想,為什么我要費(fèi)心編寫一個(gè)插件,仍然必須從命令行運(yùn)行,而我可以用一個(gè)簡(jiǎn)單的腳本在幾行 bash 中完成相同的工作?好吧,讓我們來看看 Xcode 14 中會(huì)出現(xiàn)什么,你會(huì)明白為什么我會(huì)提倡編寫插件??。
Xcode
這是運(yùn)行命令插件最令人興奮的方式,但不幸的是,它僅在 Xcode 14 中可用。因此,如果您需要運(yùn)行命令,但尚未使用 Xcode 14,請(qǐng)參閱命令行部分。
如果你正好在使用 Xcode 14,你可以通過在文件資源管理器中右鍵單擊包,從列表中找到要執(zhí)行的插件,然后單擊它來執(zhí)行包的任何命令。
下一步
這是插件的初始實(shí)現(xiàn)。我將研究如何改進(jìn)它,使它更加健壯。和往常一樣,我非常致力于公開構(gòu)建,并使我的文章中的所有內(nèi)容都開源,這樣任何人都可以提交問題或創(chuàng)建任何具有改進(jìn)或修復(fù)的 PRs。這沒有什么不同??, 這是 公共倉庫的鏈接。
此外,如果您喜歡這篇文章,請(qǐng)關(guān)注即將到來的第二部分,其中我將制作一個(gè) Sourcery 構(gòu)建工具插件。我知道這聽起來不多,但這不是一項(xiàng)容易的任務(wù)!
參考資料
[1] SwiftSyntax: ??https://github.com/apple/swift-syntax。??
[2] AutoMockable: ??https://github.com/krzysztofzablocki/Sourcery/blob/master/Templates/Templates/AutoMockable.stencil。??
[3] 雙重測(cè)試: ??https://en.wikipedia.org/wiki/Test_double。??
[4] repo: ??https://github.com/krzysztofzablocki/Sourcery/blob/master/guides/Usage.md#configuration-file。??