Sourcery调试工具推荐：提升模板开发效率的利器

Sourcery作为Swift元编程工具，能自动生成大量样板代码，但模板开发过程中常遇到调试难题。本文将介绍6款必备调试工具，结合项目内实用资源，帮助开发者快速定位模板错误、优化生成代码质量。

1. 内置文件监视工具：实时反馈模板变更

Sourcery提供的文件监视功能可实时监测模板和源代码变化，自动触发重新生成。这一特性极大缩短了"修改-测试"循环周期，尤其适合模板调试阶段。

启用方法：在命令行添加--watch参数

./bin/sourcery --sources Sources/ --templates Templates/ --output Generated/ --watch

核心实现代码位于Sourcery/Utils/FolderWatcher.swift，基于KZFileWatchers库开发，支持跨平台文件系统事件监听。

2. 模板语法验证器：提前捕获语法错误

模板文件（尤其是Stencil和EJS格式）的语法错误往往难以排查。Sourcery在解析阶段会进行基础语法校验，并输出详细错误信息。

推荐配合使用SourceryTests/Stub/Errors/localized-error.swift中的错误处理机制，通过模拟错误场景学习常见问题的解决方案。

常见语法问题：

• Stencil模板中未闭合的标签（如{% if %}缺少{% endif %}）
• Swift模板中错误的控制流语法（如<% for ... { %>忘记闭合）
• EJS模板中JavaScript语法错误

3. 类型元数据检查工具：理解代码结构

调试模板时，常需了解Sourcery解析后的类型结构。可通过打印types全局变量查看所有可访问的类型元数据：

// 在模板中添加
<%= types.all.map { $0.name }.joined(separator: ", ") %>

完整的类型元数据模型定义在SourceryRuntime/Sources/Common/TemplateContext.swift，包含以下核心类型：

• Type：表示类、结构体、枚举或协议
• Variable：属性/变量信息
• Method：方法定义
• EnumCase：枚举成员

4. 配置验证器：确保正确的项目设置

错误的配置文件会导致模板无法正常工作。Sourcery提供了配置文件验证功能，可通过加载测试配置进行验证：

./bin/sourcery --config SourceryTests/Stub/Configs/valid.yml --verbose

配置文件格式规范参见docs/usage.html#configuration-file，测试配置示例可参考：

• SourceryTests/Stub/Configs/valid.yml（正确配置）
• SourceryTests/Stub/Configs/invalid.yml（错误配置示例）

5. 代码生成预览工具：无干扰测试模板效果

调试模板时，可使用--prune参数避免生成空文件，使用--quiet减少日志干扰，专注于模板输出结果：

./bin/sourcery --sources Sources/ --templates Templates/ --output Generated/ --prune --quiet

推荐将生成结果与预期输出对比，测试用例可参考SourceryTests/Stub/Result/目录下的各类生成代码示例。

6. 性能分析工具：优化模板执行效率

复杂模板可能导致生成速度缓慢。可使用--verbose参数查看详细性能数据，定位瓶颈：

./bin/sourcery --sources Sources/ --templates Templates/ --output Generated/ --verbose

性能测试基准代码位于SourceryTests/Sourcery+PerformanceSpec.swift，包含解析大型代码库的性能测试用例。

调试工作流建议

1. 准备阶段：

   • 启用文件监视模式（--watch）
   • 打开两个终端窗口：一个运行Sourcery，一个查看输出日志

2. 定位问题：

   • 使用<%= debugPrint(variable) %>在模板中输出变量结构
   • 检查SourceryTests/Stub/Result/中的预期输出
   • 参考官方模板示例Templates/

3. 验证修复：

   • 运行单元测试验证模板正确性：swift test
   • 检查生成代码是否符合预期格式

完整的调试指南可参考guides/Usage.md和docs/writing-templates.html文档。

通过上述工具和方法，可显著提升Sourcery模板开发效率，减少调试时间。建议将常用调试命令添加到项目的Scripts/目录，如Scripts/bootstrap脚本，实现一键调试环境配置。

提示：遇到复杂问题时，可在模板中使用条件注释临时屏蔽部分代码，逐步定位问题所在。