SwiftGen 迁移指南：从旧版本平滑升级到最新版

SwiftGen 迁移指南：从旧版本平滑升级到最新版

SwiftGen The Swift code generator for your assets, storyboards, Localizable.strings, … — Get rid of all String-based APIs! 项目地址: https://gitcode.com/gh_mirrors/sw/SwiftGen

前言

SwiftGen 作为一款强大的 Swift 代码生成工具，随着版本迭代会引入一些破坏性变更。本文将为开发者详细梳理从 SwiftGen 4.x 到最新版本的迁移路径，帮助您理解变更内容并顺利完成升级。

版本迁移概览

SwiftGen 的迁移指南分为多个部分，针对不同用户群体：

1. 核心迁移指南（本文）：面向所有用户，涵盖配置变更和全局性修改
2. 模板迁移指南：面向使用内置模板的用户
3. SwiftGenKit 迁移指南：面向自定义模板开发者
4. StencilSwiftKit 迁移指南：面向需要使用额外过滤器和标签的模板开发者

最新版本迁移要点

迁移至 SwiftGen 6.6

空白字符处理行为变更：

• 弃用了旧版 Stencil 空白字符控制的解决方案
• 内置模板已适配新行为
• 可通过 --experimental-modern-spacing 标志预览新行为
• 此行为在 7.0 版本前仍可能调整

迁移至 SwiftGen 6.2

命名模板查找机制变更：

• 弃用了从 ~/Library/Application Support 查找命名模板的功能
• 建议改用 templatePath 明确指定模板路径
• 推荐将自定义模板移入项目目录，确保跨机器兼容性

命令行调用变更：

1. 弃用 swiftgen <parser> 形式，改用 swiftgen run <parser>
2. swiftgen templates 命令更名为 swiftgen template（单数形式）

模板变更：

• 移除了对 Swift 3 的支持模板
• 详细变更请参考模板专项迁移指南

重大版本迁移详解

迁移至 SwiftGen 6.0

核心变更：

1. 命令重命名：

   • storyboards 命令更名为 ib（为未来支持 XIB 文件做准备）

2. 模板结构调整：

   • 移除了 Swift 2 支持模板
   • 资源目录模板增强了对 NSDataAssets 的支持
   • 故事板模板拆分为场景(scenes)和转场(segues)两个独立模板

3. 配置格式升级：

   # 旧格式
   storyboards:
     paths: path/to/storyboards
     templateName: swift4
     output: Storyboards.swift
   
   # 新格式
   ib:
     inputs: path/to/storyboards
     outputs:
       - templateName: scenes-swift4
         output: Storyboard Scenes.swift
       - templateName: segues-swift4
         output: Storyboard Segues.swift
   

   • paths → inputs
   • 支持多输出配置
   • 解析性能优化（资源只需解析一次）

4. 新增功能：

   • 支持 JSON/Plist/YAML 文件解析
   • 提供运行时和内联两种处理模式
   • 新增 Mint 安装方式

迁移至 SwiftGen 5.0

重大变更：

1. 命令调整：

   • images 命令更名为 xcassets
   • --enumName 参数改为通用 --param 形式
   • 必须显式指定模板（不再有默认模板）

2. 模板重构：

   • 统一了 iOS/macOS 故事板模板
   • 生成代码不向后兼容（需修改调用方式）

   // 旧方式
   StoryboardScene.Message.instantiateMessageList()
   
   // 新方式
   StoryboardScene.Message.messageList.instantiate()
   

3. 上下文变量调整：

   • 颜色：colors → palettes
   • 资源：images → catalogs
   • 字符串：strings → tables

最佳实践建议

1. 配置管理：

   • 优先使用 YAML 配置文件而非命令行参数
   • 将自定义模板纳入版本控制
   • 利用多输出功能优化构建性能

2. 升级策略：

   • 先在小规模项目测试迁移
   • 逐步替换弃用功能
   • 关注模板专项指南了解细节变更

3. 自定义模板开发：

   • 适配新的上下文变量结构
   • 利用新版 Stencil 功能增强模板
   • 测试不同空白字符控制方案

结语

SwiftGen 的每次大版本升级都带来了更合理的架构设计和更强大的功能。虽然迁移需要一定工作量，但遵循本指南可以最大限度降低升级成本。建议开发者定期关注版本更新，及时获取性能改进和新特性支持。

对于复杂项目，可考虑分阶段迁移：先更新配置格式，再逐步调整模板使用方式，最后优化自定义模板。遇到问题时，可参考各专项迁移指南获取更详细的技术细节。

SwiftGen The Swift code generator for your assets, storyboards, Localizable.strings, … — Get rid of all String-based APIs! 项目地址: https://gitcode.com/gh_mirrors/sw/SwiftGen