Sourcery - 基于 SwiftSyntax 的代码生成工具

深入的Sourcery指南已包含在我的SwiftyStack工程课程中。

Sourcery Pro 提供了一个强大的 Stencil 编辑器，并扩展了 Xcode 的功能，可以处理实时 AST 模板：在 Mac App Store 上可用

https://user-images.githubusercontent.com/1468993/114271090-f6c19200-9a0f-11eb-9bd8-d7bb15129eb2.mp4

Sourcery 是一个针对 Swift 语言的代码生成器，建立在苹果的 SwiftSyntax 之上。它扩展了语言抽象，允许你自动生成样板代码。

它被用于超过 40,000 个 iOS 和 macOS 项目中，并且在一些最受欢迎和好评的应用程序（包括 Airbnb、Bumble、纽约时报）中发挥力量。它的大规模社区采用是推动苹果实现派生相等性和自动 Codable 符合性的因素之一。Sourcery 由一个不断增长的贡献者社区维护。

在你的下一个项目中试试 Sourcery 或将其添加到现有项目中 -- 你会节省很多时间并感到非常满意！

重点总结

Sourcery 允许你消除重复的代码，并创建更好的架构和开发人员工作流。一个例子可能是为所有协议实现 Mocks，没有 Sourcery，你需要为每个协议编写 数百行代码，如下所示：

class MyProtocolMock: MyProtocol {

    //MARK: - sayHelloWith
    var sayHelloWithNameCallsCount = 0
    var sayHelloWithNameCalled: Bool {
        return sayHelloWithNameCallsCount > 0
    }
    var sayHelloWithNameReceivedName: String?
    var sayHelloWithNameReceivedInvocations: [String] = []
    var sayHelloWithNameClosure: ((String) -> Void)?

    func sayHelloWith(name: String) {
        sayHelloWithNameCallsCount += 1
        sayHelloWithNameReceivedName = name
        sayHelloWithNameReceivedInvocations.append(name)
        sayHelloWithNameClosure?(name)
    }

}

而使用 Sourcery？

extension MyProtocol: AutoMockable {}

Sourcery 消除了编写任何 mock 代码的需求，那么在你的项目中有多少协议呢？想象一下你将节省多少时间，使用 Sourcery 还会使得每一个 mock 一致，如果你重构或添加属性，mock 代码会自动为你更新，消除了可能的人为错误。

Sourcery 可以应用于代码库中的任意问题，如果你能向他人描述一个算法，你就可以使用 Sourcery 自动化它。

最常见的用途有：

但是关于更具体的用例呢，比如自动生成你的应用 BetaSetting 的所有 UI？你也可以使用 Sourcery

一旦你开始编写自己的模板并学习 Sourcery 的功能，不久你就离不开它了。

如何开始

有许多关于 Sourcery 不同用途的教程，你也可以随时在我们的 Swift 论坛分类中寻求帮助。

Sourcery 的魔力是一个很好的入门教程
为 iOS 生成 Swift 代码处理 JSON 处理代码
如何使用 Sourcery 自动化 Swift 样板代码生成字典转换
Codable 枚举实现枚举的 Codable 支持
Sourcery 研讨会

快速 Mock 简介和入门视频

你还可以观看这段由 Inside iOS Dev 制作的快速入门和 Mock 简介视频：

安装

二进制形式

从发布标签下载最新版本带有预编译的二进制文件。将压缩包解压缩到目标位置并运行 bin/sourcery
Homebrew

brew install sourcery
CocoaPods

将 pod 'Sourcery' 添加到你的 Podfile 并运行 pod update Sourcery。这将下载最新版本的二进制文件并将其放在项目的 CocoaPods 路径中，你可以用 $PODS_ROOT/Sourcery/bin/sourcery 来运行它。

如果你只想安装 sourcery 二进制文件，你可能只想使用 CLI-Only 子规格： pod 'Sourcery', :subspecs => ['CLI-Only']。
Mint

mint run krzysztofzablocki/Sourcery
从源码构建

从发布标签下载最新版本的源代码或克隆仓库并手动构建 Sourcery。
- 使用 Swift 包管理器构建
  
  在根目录运行 swift build -c release，然后将 .build/release/sourcery 复制到目标位置。
  
  注意：JS 模板在使用 SPM 构建时尚未支持。
- 使用 Xcode 构建
  
  运行 xcodebuild -scheme sourcery -destination generic/platform=macOS -archivePath sourcery.xcarchive archive 并从归档文件中导出二进制文件。
SPM（仅用于插件用途） 将包依赖添加到你的 Package.swift 中，版本为 1.8.3。

.package(url: "https://github.com/krzysztofzablocki/Sourcery.git", from: "1.8.3")

pre-commit 将依赖项添加到 .pre-commit-config.yaml。

- repo: https://github.com/krzysztofzablocki/Sourcery
  rev: 1.9.1
  hooks:
  - id: sourcery

文档

最新版本的完整文档可以在这里找到。

Linux 支持

Linux 支持在此页面描述。

用法

运行可执行文件

Sourcery 是一个命令行工具，你可以手动运行它或在自定义生成阶段使用以下命令运行：

$ ./bin/sourcery --sources <sources path> --templates <templates path> --output <output path>

注意：此命令因你安装 Sourcery 的方式而异（见安装）

Swift 包命令

Sourcery 现在可以用作 Swift 包命令插件。为此，必须将该包添加为你的 Swift 包或 Xcode 项目的依赖项（见上文安装）。

为了提供插件使用的配置，请在目标目录的根目录放置 .sourcery.yml 文件（在源文件夹而不是包的根目录）。

从命令行运行

要验证插件能否被 SwiftPM 查找到，请使用：

$ swift package plugin --list

要运行代码生成器，你需要允许对项目进行更改，使用 --allow-writing-to-package-directory 标志：

$ swift package --allow-writing-to-package-directory sourcery-command

在 Xcode 中运行

在使用此命令插件的项目/包内，右键点击项目并从 "SourceryPlugins" 菜单组中选择 "SourceryCommand"。

⚠️ 注意，这仅适用于 Xcode 14 及以上版本。

命令行选项

--sources - 源 swift 文件或目录的路径。你可以使用多个 --sources 选项提供多个路径。
--templates - 模板的路径。文件或目录。你可以使用多个 --templates 选项提供多个路径。
--force-parse - 生成文件的后缀名，你想要解析的 Sourcery 生成文件。你可以使用多个 --force-parse 选项提供多个后缀。（例如，如果使用 --force-parse toparse，即使由 Sourcery 生成的 file.toparse.swift 也会被解析）尝试实现多阶段生成时很有用。--force-parse 还可以用于处理 sourcery 注解内的内容。比如要处理 sourcery:inline:auto:Type.AutoCodable 注解内的代码，你可以使用 --force-parse AutoCodable
--output [默认: 当前路径] - 输出路径。文件或目录。
--config [默认: 当前路径] - 配置文件的路径。文件或目录。详见配置文件。
--args - 传递给模板的额外参数。每个参数可以有显式值，或者有隐式的 true 值。参数应该用逗号分隔，不带空格（例如 --args arg1=value,arg2）。在模板中通过 argument.name 访问参数。
--watch [默认: false] - 监视代码和模板文件夹的更改，并自动重新生成。
--verbose [默认: false] - 打开详细日志
--quiet [默认: false] - 关闭所有日志，仅输出错误
--disableCache [默认: false] - 关闭已解析数据的缓存
--prune [默认: false] - 修剪空的生成文件
--version - 显示当前版本的 Sourcery
--help - 显示帮助信息
--cacheBasePath - 缓存目录的基础路径。可以被配置文件覆盖。
--buildPath - 构建 .swifttemplate 文件时使用的目录路径。默认系统临时目录
--hideVersionHeader [默认: false] - 停止在生成文件头中添加 Sourcery 版本。

配置文件

你可以使用 .sourcery.yml 配置文件代替 CLI 参数：

sources:
  - <sources path>
  - <sources path>
templates:
  - <templates path>
  - <templates path>
forceParse:
  - <string value>
  - <string value>
output:
  <output path>
args:
  <name>: <value>

阅读更多关于配置文件的信息这里.