R.swift 项目版本迁移指南：从旧版本平滑升级到最新版

R.swift 项目版本迁移指南：从旧版本平滑升级到最新版

R.swift Strong typed, autocompleted resources like images, fonts and segues in Swift projects 项目地址: https://gitcode.com/gh_mirrors/rs/R.swift

前言

R.swift 是一个强大的 Swift 资源管理工具，它通过类型安全的方式帮助开发者访问图片、字符串、Storyboard 等资源。随着项目的发展，R.swift 经历了多次重大版本更新，每个版本都带来了显著的改进和变化。本文将全面梳理从旧版本迁移到最新版本（特别是 7.0 版本）的关键注意事项，帮助开发者顺利完成升级。

升级到 7.0 版本的核心变化

字符串处理的重大调整

在 7.0 版本中，字符串处理机制发生了根本性变化：

1. 格式化方式统一：所有字符串现在都使用 String(format:) 方法进行格式化，即使是不含参数的字符串也不例外。这意味着：

   • 如果字符串中包含百分号 %，必须转义为 %%
   • 例如：原字符串 "完成 50%" 需要改为 "完成 50%%"

2. 多语言支持增强：现在可以通过指定首选语言来获取特定语言的字符串资源：

   R.string(preferredLanguages: ["fr"]).example.hello()
   

构建方式革新

7.0 版本引入了全新的构建方式，主要变化包括：

1. SPM 集成简化：

   • 不再需要单独的 R.swift.Library 依赖
   • 删除项目中原有的 R.generated.swift 文件
   • 移除调用 rswift 二进制文件的 Run Script Build Phase

2. 新构建流程：

   • 添加对 R.swift 包的 SPM 依赖
   • 在目标中添加 RswiftLibrary
   • 在 "Run Build Tool Plug-ins" 构建阶段添加 RswiftGenerateInternalResources 或 RswiftGeneratePublicResources
   • 右键项目并运行 RswiftXcodeModifyPackages 以确保构建工具插件能在构建过程中运行

命令行工具变更

对于使用命令行工具 rswift 的用户（非 SPM 用户）：

• 参数重命名：accessLevel → access-level
• 移除的参数：generateUITestFile、hostingBundle 等
• 新增替代方案：如需指定 bundle，现在可以在代码中使用 _R(bundle: someBundle)

库内部重构

7.0 版本对内部实现进行了大规模重构：

1. 视图引用简化：移除了对 R.nib.XXX.secondView 到 .twentiethView 的支持，仅保留 .firstView
2. 模块重命名：import Rswift → import RswiftResources
3. 协议清理：移除了多个协议如 ColorResourceType、FileResourceType 等
4. 类型增强：
   • 新增 StringResource1 到 StringResource9，用于支持带参数的字符串
   • 多个类型进行了重命名，如 ReuseIdentifierType → ReuseIdentifierContainer

持续集成系统配置

在 CI 服务器上使用 SPM 插件时，可能会遇到插件验证错误。解决方案是：

build_app(
  # ...其他参数...
  xcargs: "-skipPackagePluginValidation"
)

历史版本迁移要点回顾

升级到 6.0 版本

• 构建阶段调整：
  • 取消勾选 "Based on dependency analysis"
  • 从 "Input Files" 中移除 $TEMP_DIR/rswift-lastrun
  • 保留 R.generated.swift 在 "Output Files" 中

升级到 5.0 版本

• 最低要求 Xcode 10
• 新构建系统需要：
  • 显式指定输出文件路径
  • 添加输入/输出文件到构建阶段
• 旧构建系统需要添加 --disable-input-output-files-validation 标志

升级到 4.0 版本

• 最低要求 Swift 4/Xcode 9
• 新增 generate 命令
• CLR 文件支持被弃用，迁移到 Color assets
• 方法/属性命名规范化

升级到 3.0 版本

• 最低要求 Swift 3/Xcode 8
• 方法命名遵循 Swift 3 新规范

升级到 2.0 版本

• 最低要求 Swift 2.2/Xcode 7.3

升级到 1.0 版本

• 放弃 iOS 7 支持
• 引入 R.swift.Library 依赖
• 方法调用方式变更（属性→方法）

最佳实践建议

1. 逐步升级：建议按照版本顺序逐步升级，特别是从很旧的版本迁移时
2. 充分测试：每次升级后，全面测试应用中所有资源访问代码
3. 利用编译器：新版 R.swift 通常提供良好的编译器提示，善用这些提示可以简化迁移过程
4. 文档参考：保留各版本的迁移指南，便于排查问题

结语

R.swift 的每次重大版本更新都带来了更好的性能和更安全的类型系统。虽然迁移过程可能需要一些调整，但这些改进最终将使您的代码更加健壮和易于维护。建议开发者在项目相对空闲时安排升级，并确保团队所有成员都了解相关变更。

通过遵循本指南，您应该能够顺利完成 R.swift 的版本迁移工作，享受新版带来的各种改进和便利。如果在迁移过程中遇到特殊问题，建议查阅对应版本的详细发布说明以获取更多信息。

R.swift Strong typed, autocompleted resources like images, fonts and segues in Swift projects 项目地址: https://gitcode.com/gh_mirrors/rs/R.swift