Swift 更新Codable的MacroLog模型并兼容已有存储数据的方案

现有方案的核心问题 #

直接在新模型里添加无默认值的必填let timestamp: Date属性，依赖Swift自动合成的Codable逻辑解码旧本地数据时，会因为旧JSON文件中完全不存在timestamp这个键，直接抛出解码错误，导致所有历史日志都无法加载。

本次字段变更的具体处理 #

要保证旧数据正常读取，不能依赖自动合成的Codable实现，需要自定义解码逻辑：

1. 重写MacroLog的解码初始化方法，对新增的timestamp字段做兜底兼容：

   struct MacroLog: Codable {
       let timestamp: Date
       var date: Date = Date()
       var type: MacroType
       var beforeValue: Int
       var afterValue: Int
       var description: String
       var isOverwrite: Bool = false
       
       // 自定义解码逻辑适配新旧格式
       init(from decoder: Decoder) throws {
           let container = try decoder.container(keyedBy: CodingKeys.self)
           // 新格式优先读取独立的timestamp字段，旧数据无该字段时，用原有日志日期值兜底
           timestamp = try container.decodeIfPresent(Date.self, forKey: .timestamp) 
               ?? container.decode(Date.self, forKey: .date)
           date = try container.decodeIfPresent(Date.self, forKey: .date) ?? Date()
           type = try container.decode(MacroType.self, forKey: .type)
           beforeValue = try container.decode(Int.self, forKey: .beforeValue)
           afterValue = try container.decode(Int.self, forKey: .afterValue)
           description = try container.decode(String.self, forKey: .description)
           isOverwrite = try container.decodeIfPresent(Bool.self, forKey: .isOverwrite) ?? false
       }
       
       func valueDifference() -> Int {
           afterValue - beforeValue
       }
   }
   

2. 全局排查所有手动创建MacroLog实例的代码，补上必填的timestamp参数，解决编译报错。

常见踩坑提醒：不要以为给timestamp属性加默认值就能兼容旧数据。Swift自动合成的Codable解码逻辑中，只要属性被纳入CodingKeys，就算有默认值，遇到旧数据缺失对应键的情况还是会直接解码失败；只有手动编写的decodeIfPresent逻辑，才会触发默认值兜底。

数据模型变更的通用管理规范 #

后续遇到字段调整、类型修改、结构变动的场景，遵循下面的规则可以最大程度避免旧数据丢失、加载崩溃的问题：

• 所有新增的存储属性，不要使用无兜底的强制解码逻辑。必须为旧版本生成的JSON数据，留足兼容的兜底路径，不能让旧数据因为缺字段直接解码失败。
• 给整个本地存储结构增加版本标识，避免格式混乱。可以把原来直接存储[MacroLog]的结构，改为带版本号的外层包装：

  struct LogStore: Codable {
      let version: Int
      let logs: [MacroLog]
  }
  

  首次发布的存储格式version记为1，本次新增timestamp的新格式version记为2。加载本地数据时先识别版本号：如果读到的是version=1的旧数据，就用对应版本的旧模型类解码，转换为新模型结构后，以version=2的格式重新写入本地，后续加载就不需要重复走兼容逻辑。
• 解码失败时不要直接清空本地数据。当前的加载逻辑如果遇到解码报错，默认会返回空数组，直接在后续写入时覆盖用户的历史日志。正确的处理是：首次解码失败时，尝试用历史版本的模型类做二次解码，转换完成后再走正常的写入流程。
• 跨版本兼容的过渡期内，如果App用户尚未完成全量升级，编码时可以同步保留旧字段的输出，避免低版本App读取新格式数据时崩溃；等所有用户都升级到包含新模型的版本后，再删除旧字段的编码逻辑。

内容的提问来源于stack exchange，提问作者ab1428x