从 HandyJSON 迁移到 SmartCodable：我们团队的实践

本文记录了我们团队将一个 10 万行 Swift 项目从 HandyJSON 迁移到 SmartCodable 的完整过程，包括迁移动机、踩过的坑、API 对照表，以及迁移后的效果对比。如果你的项目还在用 HandyJSON，希望这篇文章能帮你做出判断。

一、为什么要迁移

HandyJSON 的定时炸弹

HandyJSON 是国内 iOS 社区广泛使用的 JSON 解析库。它的优点很明显------API 简洁，支持 Any 类型，支持继承，几乎不需要额外的模板代码。我们团队用了两年多，一直没出什么问题。

直到 Swift 5.5 引入结构化并发之后，问题开始浮现。

HandyJSON 的核心实现依赖 Swift 运行时的内存布局反射------直接读取 struct/class 的内存 metadata，计算属性偏移量，然后写入值。这个机制有两个致命问题：

0. 不是官方支持的 API 。Swift 的内存布局在不同版本之间没有 ABI 稳定性承诺。Apple 每次更新 Swift 版本，都有可能改变 metadata 的结构，导致 HandyJSON 静默地写错内存位置。这不会崩溃，而是静默返回错误的数据------更危险。
1. 与 Swift 并发模型冲突。Swift 5.5+ 的并发检查越来越严格，HandyJSON 的运行时反射无法被标记为 Sendable，在启用严格并发检查的项目中会产生大量警告。

我们在一次 Xcode 15 升级后遇到了一个诡异的 Bug：某个嵌套模型的属性偶尔解析为零值。排查了两天才发现是 HandyJSON 的内存偏移计算在新版 Swift 编译器下出了问题。这次事件让我们决定迁移。

为什么选择 SmartCodable

我们评估了三个方案：

方案	优点	缺点
手写 init(from:)	零依赖，完全可控	样板代码爆炸，100 个 Model 就是地狱
CodableWrapper / BetterCodable	轻量，只用属性包装器	只解决默认值问题，不解决类型转换、Any 支持
SmartCodable	功能对齐 HandyJSON，基于原生 Codable	学习成本低，API 设计与 HandyJSON 相似

SmartCodable 胜出的原因很简单：它是唯一一个在功能上能完全替代 HandyJSON 的方案，同时又基于 Apple 原生 Codable 协议，没有运行时安全隐患。

---

二、迁移前的准备

评估工作量

我们先做了一次全局搜索，统计 HandyJSON 的使用范围：

 # 统计引用 HandyJSON 的文件数
 grep -rl "HandyJSON" --include="*.swift" . | wc -l
 ​
 # 统计 deserialize 调用次数
 grep -rn "deserialize(from:" --include="*.swift" . | wc -l
 ​
 # 统计 mapping 方法使用次数
 grep -rn "mapping(mapper:" --include="*.swift" . | wc -l
 ​
 # 统计 Any 类型属性
 grep -rn "var.*: Any" --include="*.swift" . | wc -l

我们的项目情况：

• 约 200 个 Model 文件
• 80+ 处 deserialize 调用
• 15 处 mapping(mapper:) 自定义映射
• 8 处 Any 类型属性
• 3 处继承关系

制定迁移策略

根据评估结果，我们制定了分步迁移策略：

0. 第一步：全局替换协议名（工作量最大但最简单）
1. 第二步 ：处理 mapping 方法（需要逐个改写）
2. 第三步 ：处理 Any 类型属性（加 @SmartAny）
3. 第四步 ：处理继承关系（加 @SmartSubclass）
4. 第五步 ：处理枚举（HandyJSONEnum → SmartCaseDefaultable）
5. 第六步 ：处理序列化（toJSON() → toDictionary()）
6. 第七步：全量测试

---

三、逐步迁移

第一步：替换协议名（5 分钟）

这是最简单的一步，全局搜索替换即可：

 import HandyJSON → import SmartCodable
 HandyJSON         → SmartCodable       （作为协议名使用的地方）

SmartCodable 的 deserialize(from:) API 与 HandyJSON 完全一致，所以替换协议名后，所有反序列化代码不需要改动。

 // HandyJSON（替换前）
 guard let model = Model.deserialize(from: dict) else { return }
 ​
 // SmartCodable（替换后）------ 调用方式完全一样
 guard let model = Model.deserialize(from: dict) else { return }

唯一的小差异 ：HandyJSON 解码数组时返回 [Model]?，有些地方写了 as? [Model] 强转。SmartCodable 不需要这个强转，但保留也不会报错，可以后续清理。

 // HandyJSON 写法
 guard let models = [Model].deserialize(from: arr) as? [Model] else { return }
 ​
 // SmartCodable 写法（as? [Model] 可以删掉，不删也没问题）
 guard let models = [Model].deserialize(from: arr) else { return }

第二步：改写自定义映射（30 分钟）

这是工作量最大的一步。HandyJSON 用 mapping(mapper:) 方法，SmartCodable 用 mappingForKey()，语法不同：

HandyJSON：

 struct Model: HandyJSON {
     var nickName: String = ""
     var userAge: Int = 0
     var ignoreField: String = ""
 ​
     mutating func mapping(mapper: HelpingMapper) {
         mapper <<< self.nickName <-- ["nick_name", "realName"]
         mapper <<< self.userAge <-- "user_age"
         mapper >>> self.ignoreField   // 忽略该字段
     }
 }

SmartCodable：

 struct Model: SmartCodable {
     var nickName: String = ""
     var userAge: Int = 0
     @SmartIgnored
     var ignoreField: String = ""
 ​
     static func mappingForKey() -> [SmartKeyTransformer]? {
         [
             CodingKeys.nickName <--- ["nick_name", "realName"],
             CodingKeys.userAge <--- "user_age"
         ]
     }
 }

对照表：

HandyJSON	SmartCodable	说明
mapper <<< self.prop <-- "key"	CodingKeys.prop <--- "key"	单字段映射
mapper <<< self.prop <-- ["k1", "k2"]	CodingKeys.prop <--- ["k1", "k2"]	多候选映射
mapper >>> self.prop	@SmartIgnored var prop	忽略字段

踩坑提醒 ：SmartCodable 的 mappingForKey() 是 static func，不是 mutating func。如果你的 mapping 中有依赖 self 的逻辑，需要调整。

第三步：处理 Any 类型（10 分钟）

HandyJSON 天然支持 Any 类型，SmartCodable 需要加 @SmartAny 属性包装器：

 // HandyJSON
 struct Model: HandyJSON {
     var extra: [String: Any] = [:]
     var tags: [Any] = []
     var value: Any?
 }
 ​
 // SmartCodable
 struct Model: SmartCodable {
     @SmartAny var extra: [String: Any] = [:]
     @SmartAny var tags: [Any] = []
     @SmartAny var value: Any?
 }

全局搜索 var.*: Any、var.*: [Any]、var.*: [String: Any]，逐个加上 @SmartAny 即可。

第四步：处理继承（5 分钟）

HandyJSON 自动处理继承，SmartCodable 需要在子类上加 @SmartSubclass：

 // HandyJSON ------ 什么都不用加
 class BaseModel: HandyJSON {
     var name: String = ""
     required init() {}
 }
 class SubModel: BaseModel {
     var age: Int = 0
 }
 ​
 // SmartCodable ------ 子类加 @SmartSubclass
 class BaseModel: SmartCodable {
     var name: String = ""
     required init() {}
 }
 @SmartSubclass
 class SubModel: BaseModel {
     var age: Int = 0
 }

注意 ：@SmartSubclass 是 Swift 宏，需要 Swift 5.9+ 和 Xcode 15+。如果你的项目还在用低版本，可以参考 低版本继承方案。

第五步：处理枚举（5 分钟）

 // HandyJSON
 enum Sex: String, HandyJSONEnum {
     case man
     case woman
 }
 ​
 // SmartCodable
 enum Sex: String, SmartCaseDefaultable {
     case man
     case woman
 }

全局替换 HandyJSONEnum → SmartCaseDefaultable。

第六步：处理序列化（10 分钟）

序列化的 API 名称有变化：

HandyJSON	SmartCodable
model.toJSON()	model.toDictionary()
model.toJSONString()	model.toJSONString()
models.toJSON()	models.toArray()
models.toJSONString()	models.toJSONString()

全局搜索 .toJSON() 替换为 .toDictionary()（注意排除 toJSONString）。数组序列化搜索替换即可。

第七步：全量测试

移除 HandyJSON 依赖，编译通过后进行全量测试。

我们的测试策略：

0. 先开启 SmartSentinel 日志，跑一遍主流程：

 SmartSentinel.debugMode = .verbose

2. 观察日志中是否有异常的类型转换或缺失字段
3. 重点验证有 mapping 的模型、有 Any 类型的模型、有继承的模型
4. 回归测试核心业务流程

---

四、迁移后的收获

解析异常不再是黑盒

HandyJSON 解析失败时，你只知道"解析返回了 nil"，但不知道哪个字段出了问题。SmartCodable 的 SmartSentinel 日志系统会精确告诉你：

 ================================ [Smart Sentinel] ================================
 UserModel 👈🏻 👀
 ╆━ UserModel
 ┆┄ age       : Expected Int, got String --- auto-converted
 ┆┄ email     : Key not found --- using default ""
 ====================================================================================

我们在迁移后第一周就通过 Sentinel 日志发现了 3 个后端接口返回类型不一致的问题------这些问题在 HandyJSON 时代被静默吞掉了。

告别运行时崩溃的恐惧

HandyJSON 的每次 Swift 版本升级都是一次赌博。SmartCodable 基于原生 Codable，Swift 版本升级时完全不需要担心底层兼容性。

类型转换更智能

SmartCodable 内置的类型转换比 HandyJSON 更全面：

 // 后端返回 String 类型的 "123"，Model 声明为 Int
 var age: Int = 0
 // HandyJSON: age = 0（转换失败，静默用默认值）
 // SmartCodable: age = 123（自动转换成功）

编译速度

移除 HandyJSON 后，项目的 clean build 时间减少了约 8%（HandyJSON 的运行时反射代码量较大）。

---

五、迁移清单（Checklist）

供你在实际迁移时对照使用：

• 全局替换 import HandyJSON → import SmartCodable
• 全局替换协议名 HandyJSON → SmartCodable（注意只替换作为协议使用的）
• 改写所有 mapping(mapper:) → mappingForKey() + @SmartIgnored
• 所有 Any / [Any] / [String: Any] 属性加 @SmartAny
• 所有子类加 @SmartSubclass
• 全局替换 HandyJSONEnum → SmartCaseDefaultable
• 全局替换 .toJSON() → .toDictionary()（排除 toJSONString）
• 数组序列化 .toJSON() → .toArray()
• 移除 HandyJSON 依赖（Podfile / Package.swift）
• 编译通过
• 开启 SmartSentinel.debugMode = .verbose，跑主流程
• 全量回归测试
• 关闭 Sentinel（SmartSentinel.debugMode = .none）
• 上线观察

---

六、总结

整个迁移过程比我们预想的顺利很多。200 个 Model 的项目，两个人花了一天半 完成迁移和测试。其中 80% 的工作量是全局替换（第一步），真正需要手动处理的只有 mapping 改写和 @SmartAny 标注。

如果你的项目还在用 HandyJSON，我的建议是：不要等到被 Swift 版本升级逼着迁移，主动迁移的成本远低于被动修 Bug。

SmartCodable 的 API 设计明显考虑了 HandyJSON 用户的迁移体验------deserialize、didFinishMapping、designatedPath 这些核心 API 完全一致，迁移门槛很低。