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

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

了解更多关于 Sourcery Pro 的信息

Sourcery 是一款 Swift 语言的代码生成器，构建于 Apple 自己的 SwiftSyntax 之上。它扩展了语言抽象，允许您自动生成样板代码。

它被 iOS 和 macOS 上超过 40,000 个项目使用，并为一些最受欢迎和广受好评的应用程序提供支持（包括 Airbnb、Bumble、纽约时报）。它的大规模社区采用是推动 Apple 实现派生 Equality 和自动 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 移除了编写任何 mocks 代码的需要。您的项目中有多少个协议？想象一下您将节省多少时间，使用 Sourcery 还可以使每个 mock 保持一致性，如果您重构或添加属性，mock 代码将自动为您更新，从而消除可能的人为错误。

Sourcery 可以应用于代码库中的任何问题，如果您可以向另一个人描述一个算法，您就可以使用 Sourcery 将其自动化。

最常见的用途是

• Equality (相等) & Hashing (哈希)
• 枚举 cases & Counts (计数)
• Lenses (镜头)
• Mocks & Stubs (模拟和桩)
• LinuxMain
• Decorators (装饰器)
• Persistence and advanced Codable (持久化和高级 Codable)
• Property level diffing (属性级别差异)

但是更具体的用例呢，例如自动生成应用程序 BetaSetting 的所有 UI？您也可以为此使用 Sourcery

一旦您开始编写自己的模板并了解 Sourcery 的强大功能，您将离不开它。

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

• The Magic of Sourcery (Sourcery 的魔力) 是一个很好的入门教程
• Generating Swift Code for iOS (为 iOS 生成 Swift 代码) 涉及 JSON 处理代码
• How To Automate Swift Boilerplate with Sourcery (如何使用 Sourcery 自动化 Swift 样板代码) 生成到字典的转换
• Codable Enums (可编码枚举) 实现了对枚举的 Codable 支持
• Sourcery 研讨会

您还可以观看 Inside iOS Dev 制作的这个快速入门和 mocking 介绍视频

• 二进制形式

  从 release 标签 下载带有预构建二进制文件的最新版本。 将归档文件解压缩到所需的目标位置并运行 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

• 从源代码构建

  从 release 标签 下载最新的源代码，或克隆存储库并手动构建 Sourcery。

  • 使用 Swift Package Manager 构建

    在根文件夹中运行 swift build -c release，然后将 .build/release/sourcery 复制到所需的目标位置。

    注意：使用 SPM 构建时，尚不支持 JS 模板。

  • 使用 Xcode 构建

    运行 xcodebuild -scheme sourcery -destination generic/platform=macOS -archivePath sourcery.xcarchive archive 并从归档文件中导出二进制文件。

• SPM（仅用于插件） 从版本 1.8.3 开始，将包依赖项添加到您的 Package.swift 清单中。

.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

最新版本的完整文档可在此处获得：here (这里)。

Linux 支持在此页面上描述。

Sourcery 是一个命令行工具； 您可以手动运行它，也可以使用以下命令在自定义构建阶段运行它

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

注意：此命令取决于您安装 Sourcery 的方式（请参阅安装）

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

在使用了此命令插件的项目/包中，右键单击该项目，然后从“SourceryPlugins”菜单组中选择“SourceryCommand”。

⚠️请注意，这仅适用于 Xcode 14 及更高版本。

• --sources - 源 Swift 文件或目录的路径。您可以使用多个 --sources 选项提供多个路径。
• --templates - 模板的路径。文件或目录。您可以使用多个 --templates 选项提供多个路径。
• --force-parse - 您要解析的 Sourcery 生成文件的文件扩展名。 您可以使用多个 --force-parse 选项提供多个扩展名。 （即，即使 file.toparse.swift 是由 Sourcery 生成的，如果 --force-parse toparse，它也会被解析）。 在尝试实现多阶段生成时很有用。 --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 版本添加到生成的文件标头中。
• --headerPrefix - 标头的其他前缀。

您可以不使用 CLI 参数，而是使用 .sourcery.yml 配置文件

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

在此处阅读有关此配置文件的更多信息：here (这里)。

如果您在使用二进制 zip 分发时收到未经验证的开发者警告，请尝试：xattr -dr com.apple.quarantine Sourcery-1.1.1

欢迎并鼓励对 Sourcery 做出贡献！

很容易参与。 有关更多详细信息，请参见贡献指南。

贡献者列表可通过 GitHub 获得.

为了阐明对我们社区的期望，Sourcery 采用了 Contributor Covenant 定义的行为准则。 该文档已在许多开源社区中使用，并很好地阐明了我的价值观。 有关更多信息，请参见行为准则。

如果您想支持 Sourcery 的开发，可以通过 GitHub Sponsors 或 Open Collective 进行赞助，非常感谢🙇‍

如果您是一家公司，并希望直接赞助该项目并在其徽标上加上徽标，则可以直接与我联系

Sourcery 在 MIT 许可下可用。 有关更多信息，请参见LICENSE。

该工具由以下工具提供支持

• Stencil 和 Kyle Fuller 的其他一些库：Kyle Fuller

谢谢！ 致

• Mariusz Ostrowski 创建徽标。
• Artsy Eidolon 团队，因为我们使用他们的代码库作为性能测试解析器的存根数据。
• Olivier Halligon 向我展示了他用于 CLI 工具的设置脚本，这些脚本为我们的 rakefile 提供支持。
• 感谢 JP Simard 创建了 SourceKitten，它最初为 Sourcery 提供支持，并且对于项目的成功至关重要。

如果您想为资产相关的数据（如 .xib、.storyboard 等）生成代码，请使用 SwiftGen。SwiftGen 和 Sourcery 是互补的工具。

请务必查看我的其他库和工具，尤其是

• KZPlayground - 用于 Swift 和 Objective-C 的强大 Playground
• KZFileWatchers - 用于观察本地和远程文件更改的守护程序，用于构建其他开发工具（Sourcery 使用它）

您可以在 Twitter 上关注我，获取有关我正在创建的其他项目的新闻/更新。